Text to speech

ElevenLabs text to speech

Submit a script, follow the job and download the audio.

POST/api/v1/tts

Submit a text-to-speech job. Returns a task_id immediately. Poll the job with GET /api/v1/tts?task_id=.... Cost = 1 credit per character.

Request body

FieldTypeRequiredDescription
textstringyesText to synthesise. Up to 500,000 characters.
voice_idstringyesA 15-25 char alphanumeric ElevenLabs voice id (e.g. LB3SchLS4lHotJg4GcZW, "Aaden - Friendly, Warm and Confident"), or a prefixed vbee_... / fishaudio_... id from GET /voices?provider=vbee|fishaudio (see the Vbee & Fish Audio tab). List with GET /voices. Minimax ids are rejected here — use POST /api/minimax-tts.
model_idstringnoStored as eleven_multilingual_v2 when omitted. On the standard backend model_id is stored with the job but every request renders with the same standard model. While the extended ElevenLabs model set is enabled, model_id is honoured: eleven_v4 (also used for any unknown id), eleven_v4_turbo, eleven_multilingual_v2, eleven_v3, eleven_turbo_v2_5, eleven_flash_v2_5, eleven_turbo_v2, eleven_flash_v2. See Which model set is active below.
languagestringnoauto (default — server auto-detects from text) or ISO 639-1 code (en, tr, es, fr, de, it, pt, ru, pl, cs, ro, uk, nl, ar, hi, ja, ko, zh, ...). Invalid values are dropped silently and the server falls back to auto-detect.
voice_settingsobjectnoSee below.
webhook_urlstringnoCalled once with the final audio URL when the job finishes.

voice_settings object

FieldTypeDefaultDescription
speednumber1.0Standard backend: 0.5 – 1.5; out-of-range values fall back to the default. Extended model set: applied on Multilingual v2 and the Turbo / Flash models, clamped to 0.7 – 1.2.
context_chainingbooleanfalseStandard backend: keeps multi-turn voice continuity across the whole script and bills +50% credits. While the extended model set is enabled it is not applied and not billed.
with_transcriptbooleanfalseReturns an SRT subtitle file alongside the audio. Works on both backends.
pronunciation_dictionary_idstring–Applies the given dictionary's rules to the text before synthesis. Only affects audio.
stabilitynumber0.5Extended model set: applied on every model, 0 – 1. Standard backend: ignored.
similarity_boostnumber0.75Extended model set: applied on every model except v3, 0 – 1. Standard backend: ignored.
stylenumber0Style exaggeration, 0 – 1. Applied on eleven_multilingual_v2 with the extended model set; ignored otherwise.
use_speaker_boostbooleantrueSpeaker boost. Applied on eleven_multilingual_v2 with the extended model set; ignored otherwise.

Settings applied per model (extended model set) — each model applies only its own; other fields are ignored for it:

model_idApplied settings
eleven_v4, eleven_v4_turbostability, similarity_boost
eleven_multilingual_v2speed, stability, similarity_boost, style, use_speaker_boost
eleven_v3stability
eleven_turbo_v2_5, eleven_flash_v2_5, eleven_turbo_v2, eleven_flash_v2speed, stability, similarity_boost

language works on both backends. On the standard backend stability / similarity / style / speaker boost have no effect — performance is driven by inline tags in text (see Performance tags below). Sending the fields is harmless.

Which model set is active

GET /api/tts/backend (no auth) reports it:

JSON
{ "elevenlabs": "backup", "models": [{ "id": "eleven_v4", "label": "v4", "settings": ["stability", "similarity_boost"] }, ...], "default_model": "eleven_v4", "speed_range": { "min": 0.7, "max": 1.2 } }

elevenlabs is "primary" or "backup". A non-empty models array means the extended ElevenLabs model set is enabled and model_id is honoured, with each model's settings listing the voice settings it applies; an empty array means the standard backend (default_model is then eleven_multilingual_v2).

Performance tags (inline in text)

Drop these tags directly into the text — they steer pacing, pauses, emotion, sound effects, style and tone.

  • Speed: [speed_very_slow] · [speed_slow] · [speed_fast] · [speed_very_fast]
  • Pause: [pause] · [long_pause]
  • Emotion (31): [affection], [amusement], [anger], [awe], [confusion], [contentment], [curiosity], [disappointment], [doubt], [empathy], [envy], [excitement], [fear], [guilt], [happiness], [hesitation], [hope], [hurt], [interest], [joy], [love], [nostalgia], [pity], [pride], [relief], [sadness], [satisfaction], [shame], [surprise], [sympathy], [wonder]
  • Sound effects (onomatopoeia is part of the tag — keep it attached): [cough]ahem · [laughter]haha · [crying]boohoo · [screaming]ahh · [burping]burp · [humming]hmm · [sigh]uh · [sniff]sniff · [sneeze]achoo
  • Style: [whispering] · [shouting] · [singing] · [narrating] · [storytelling] · [announcing] · [reporting] · [conversational]
  • Tone: [serious] · [playful] · [formal] · [casual] · [confident] · [warm] · [friendly] · [calm] · [authoritative] · [sarcastic] · [dramatic] · [mysterious]

Tags go between words or between sentences — never inside a word. The dashboard exposes a one-click tag picker plus an Enhance text with AI button that injects them automatically (via POST /api/tts/enhance).

Example

cURL
curl -X POST "https://www.dubvoice.ai/api/v1/tts" \
  -H "Authorization: Bearer sk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "[warm] Hello there. [pause] [excitement] Today is going to be amazing!",
    "voice_id": "LB3SchLS4lHotJg4GcZW",
    "model_id": "eleven_multilingual_v2",
    "language": "auto",
    "voice_settings": { "speed": 1.0, "context_chaining": false }
  }'

Response (immediate)

JSON
{ "task_id": "550e8400-e29b-41d4-a716-446655440000", "status": "pending", "characters": 30 }

GET/api/v1/tts?task_id=<id>

Poll a single job. Returns status, audio URL, progress %, and error if any.

JSON
{
  "task_id": "...", "status": "completed",
  "result": "https://your-storage.supabase.co/.../final.mp3",
  "characters": 30, "progress": 100,
  "created_at": "...", "completed_at": "..."
}

Statuses: pending → processing → completed | failed. Recommended poll interval: 3-5 seconds.

GET/api/v1/tts

Paginated list of your jobs: ?page=1&limit=20 (max 100).

Limits

  • Up to 30 jobs in progress per user.
  • 240 requests / minute per API key.
  • Max text length: 500,000 chars per job.

Search docs

Find a page or an endpoint