Developers
VoicesLab API & MCP
Turn text into natural speech from your own code, or let AI assistants like Claude, ChatGPT and Cursor do it for you. The API uses the voice library and the voices you cloned on VoicesLab, and spends the same credits as the website.
Base URL: https://voiceslab.io/api/v1 · OpenAPI: /api/v1/openapi.json
Quickstart
- Get a paid plan or a credit pack on the pricing page.
- Create a key in Dashboard → API & MCP. Copy it; it is shown only once.
- Make your first request:
curl https://voiceslab.io/api/v1/tts \
-H "Authorization: Bearer $VOICESLAB_API_KEY" \
-H "Content-Type: application/json" \
-d '{"text": "Hello from VoicesLab!", "voice_id": "Rachel"}' \
--output hello.mp3Python
import os, requests
r = requests.post(
"https://voiceslab.io/api/v1/tts",
headers={"Authorization": f"Bearer {os.environ['VOICESLAB_API_KEY']}"},
json={"text": "Hello from VoicesLab!", "voice_id": "Rachel", "format": "mp3"},
timeout=300,
)
r.raise_for_status()
open("hello.mp3", "wb").write(r.content)
print("credits left:", r.headers.get("X-Credits-Remaining"))Node.js
import { writeFile } from "node:fs/promises";
const res = await fetch("https://voiceslab.io/api/v1/tts", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.VOICESLAB_API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({ text: "Hello from VoicesLab!", voice_id: "Rachel" }),
});
if (!res.ok) throw new Error((await res.json()).error.message);
await writeFile("hello.mp3", Buffer.from(await res.arrayBuffer()));Authentication
Send your key in the Authorization header: Authorization: Bearer vl_live_…. Keys start with vl_live_. You can have up to 5 active keys, give each a daily character limit, and revoke a key at any time in the dashboard. Keep keys on your server; never put them in a web page or mobile app.
Plans and credits
API and MCP requests spend the same credits as the website: 1 credit per character of input text, in every language. Monthly plan credits are used first, then credit-pack credits. Failed generations are not charged.
- Basic: 200,000 credits per month
- Pro: 500,000 credits per month
- Credit pack: 50,000 credits, never expire ($6.99)
- Credit pack: 200,000 credits, never expire ($19.99)
Generating speech needs an active paid plan or a credit-pack balance. Free accounts can create keys and call /voices and /quota.
List voices
GET /v1/voices returns the voice library and your own cloned voices. Use the id as voice_id. Cloned voices are created in the dashboard and can only be used by your account.
curl "https://voiceslab.io/api/v1/voices?language=en&gender=female&limit=5" \
-H "Authorization: Bearer $VOICESLAB_API_KEY"Query parameters: source (all, library, cloned), language (prefix such as en, zh, es-MX), gender, query, limit (max 500), offset.
{
"data": [
{
"id": "Rachel",
"name": "Rachel",
"type": "library",
"language": "en-US",
"gender": "female",
"category": "professional",
"tags": ["personable", "conversational", "friendly"],
"description": "personable female voice, great for conversational and friendly interactions",
"preview_url": "https://voiceslab.io/audio/sample/rachel.mp3"
}
],
"total": 42,
"limit": 5,
"offset": 0
}Text to speech
POST /v1/tts · up to 11,000 characters per request.
| Field | Type | Description |
|---|---|---|
| text | string, required | Text to speak, 1–11,000 characters. |
| voice_id | string, required | A voice id from /v1/voices. |
| format | string | mp3 (default), wav or opus. |
| speed | number | 0.5–2, default 1. |
| volume | number | Volume change in dB, -20 to 20, default 0. |
By default the response body is the audio file. Add ?response=json (or send Accept: application/json) to get a download link instead:
{
"id": "6b0c7f8e-2a51-4b8e-9d0f-1c2b3a4d5e6f",
"status": "succeeded",
"endpoint": "tts",
"format": "mp3",
"characters": 21,
"credits_charged": 21,
"credits_remaining": 199979,
"audio_url": "https://…signed link…",
"audio_url_expires_at": "2026-11-18T14:00:00.000Z",
"audio_expires_at": "2026-11-25T13:00:00.000Z",
"created_at": "2026-11-18T13:00:00.000Z"
}Every generation response carries the headers X-Generation-Id, X-Credits-Charged, X-Credits-Remaining and X-Request-Id.
Dialogue
POST /v1/dialogue creates one mp3 of a conversation: up to 30 lines, 5 different voices, 2,000 characters per line and 11,000 in total. Credits are the sum of all line lengths.
curl https://voiceslab.io/api/v1/dialogue?response=json \
-H "Authorization: Bearer $VOICESLAB_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"lines": [
{"voice_id": "Rachel", "text": "Did you hear the new episode?"},
{"voice_id": "Adam", "text": "Not yet. Is it good?"}
]
}'Generations and downloads
Audio is stored for 7 days. Download links are signed and valid for 1 hour. GET /v1/generations/{id} returns the generation with a fresh link, and GET /v1/generations/{id}/audio redirects straight to the file. After 7 days the audio is gone (410 audio_expired).
Quota
GET /v1/quota returns your plan, whether you can generate, and the remaining monthly and credit-pack balances.
{
"plan": "pro",
"subscription_active": true,
"subscription_canceling": false,
"subscription_ends_at": "2026-12-01T00:00:00.000Z",
"can_generate": true,
"credits": { "total_remaining": 512340, "monthly_remaining": 462340, "monthly_allowance": 500000, "pack_remaining": 50000 },
"monthly_credits_reset_at": "2026-12-01T00:00:00.000Z",
"billing_unit": "1 credit = 1 character of input text"
}Retries and idempotency
Network errors happen. Send an Idempotency-Key header (any unique string up to 255 characters, such as a UUID) with /tts and /dialogue. If you retry with the same key and body within 24 hours, you get the original result and are never charged twice. Reusing a key with a different body returns 409. Failed requests are not charged and can be retried with the same key.
Errors
Errors return JSON with a stable code:
{ "error": { "code": "insufficient_credits", "message": "This request needs 1200 credits but only 300 are left.", "request_id": "req_…", "details": { "required": 1200, "left": 300 } } }| Code | HTTP | Meaning |
|---|---|---|
| invalid_request | 400 | The body or a parameter is invalid. The message says which field. |
| missing_api_key | 401 | No Authorization header. |
| invalid_api_key | 401 | The key is wrong, expired or revoked. |
| paid_plan_required | 402 | Generation needs an active paid plan or a credit pack. |
| insufficient_credits | 402 | Not enough credits left. details.required and details.left show the numbers. |
| insufficient_scope | 403 | The key does not have the needed permission. |
| account_disabled | 403 | The account is disabled. |
| voice_not_found | 404 | Unknown voice_id, or a cloned voice that belongs to another account. |
| not_found | 404 | Unknown generation id. |
| idempotency_conflict | 409 | The Idempotency-Key was used with a different body. |
| request_in_progress | 409 | A request with this Idempotency-Key is still running. |
| audio_expired | 410 | The audio was deleted after 7 days. |
| text_too_long | 413 | Text is over the limit for this endpoint. |
| rate_limited | 429 | Too many requests. Wait for Retry-After seconds. |
| too_many_concurrent_requests | 429 | Too many generations running at once for this account. |
| key_daily_limit_reached | 429 | The daily character limit you set on this key was reached. |
| generation_failed | 502 | Speech generation failed upstream. Nothing was charged; retry. |
| upstream_busy | 503 | The service is at capacity. Retry after a few seconds. |
| api_paused | 503 | The API is temporarily paused. |
Rate limits
- 60 requests per minute per key.
- 10 generations per minute per account, and 2 running at the same time.
- An optional daily character limit per key, set in the dashboard.
When you hit a limit you get 429 with a Retry-After header. Need more? Contact us from the website.
MCP server
The VoicesLab MCP server lets AI assistants list voices, generate speech and dialogue, and check your balance. It is a remote server (Streamable HTTP) at https://voiceslab.io/api/mcp. Tools: list_voices, text_to_speech, create_dialogue, get_generation, get_quota. Generated audio comes back as a download link.
Claude.ai, ChatGPT and other apps with connectors
Add a custom connector with the URL above. You will be sent to VoicesLab to sign in and approve access (OAuth). No API key needed. You can disconnect apps in the dashboard.
Claude Code
claude mcp add --transport http voiceslab https://voiceslab.io/api/mcp \
--header "Authorization: Bearer $VOICESLAB_API_KEY"Cursor, Windsurf, VS Code and other clients
{
"mcpServers": {
"voiceslab": {
"url": "https://voiceslab.io/api/mcp",
"headers": { "Authorization": "Bearer vl_live_..." }
}
}
}Clients that only support local (stdio) servers
{
"mcpServers": {
"voiceslab": {
"command": "npx",
"args": ["-y", "mcp-remote", "https://voiceslab.io/api/mcp", "--header", "Authorization: Bearer vl_live_..."]
}
}
}