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

  1. Get a paid plan or a credit pack on the pricing page.
  2. Create a key in Dashboard → API & MCP. Copy it; it is shown only once.
  3. 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.mp3

Python

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.

FieldTypeDescription
textstring, requiredText to speak, 1–11,000 characters.
voice_idstring, requiredA voice id from /v1/voices.
formatstringmp3 (default), wav or opus.
speednumber0.5–2, default 1.
volumenumberVolume 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 } } }
CodeHTTPMeaning
invalid_request400The body or a parameter is invalid. The message says which field.
missing_api_key401No Authorization header.
invalid_api_key401The key is wrong, expired or revoked.
paid_plan_required402Generation needs an active paid plan or a credit pack.
insufficient_credits402Not enough credits left. details.required and details.left show the numbers.
insufficient_scope403The key does not have the needed permission.
account_disabled403The account is disabled.
voice_not_found404Unknown voice_id, or a cloned voice that belongs to another account.
not_found404Unknown generation id.
idempotency_conflict409The Idempotency-Key was used with a different body.
request_in_progress409A request with this Idempotency-Key is still running.
audio_expired410The audio was deleted after 7 days.
text_too_long413Text is over the limit for this endpoint.
rate_limited429Too many requests. Wait for Retry-After seconds.
too_many_concurrent_requests429Too many generations running at once for this account.
key_daily_limit_reached429The daily character limit you set on this key was reached.
generation_failed502Speech generation failed upstream. Nothing was charged; retry.
upstream_busy503The service is at capacity. Retry after a few seconds.
api_paused503The 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_..."]
    }
  }
}
VoicesLab API & MCP Documentation | Text to Speech API