Skip to main content
Check available models and prices with GET /v1/audio/models. Authenticate HTTP requests using Authorization: Bearer <GENGEN_API_KEY>.

​
API categories

​
Generate speech

Send this body to /v1/audio/generations and use an Idempotency-Key of 1–128 printable non-space ASCII characters. Reuse it with the same request after timeouts. Changing a request under the same key returns 409. Idempotency is scoped to this API key and endpoint. Use x-gengen-task-id from the /speech response to poll delivery/settlement status. Streaming chunks alone do not confirm successful completion. If the response was lost before its task ID arrived, repeat the same request/key to recover the task; never submit with a new key merely because a connection failed. Models: eleven_v3, eleven_v4, eleven_v4_turbo. Maximum 2,000 characters per request, including whitespace and speech tags. Supported formats are MP3 at 44.1 kHz/128 kbps and pcm_24000 raw signed 16-bit mono PCM. Optional controls.languageCode accepts a two/three-letter language code. Advanced options: providerOptions.elevenlabs.seed (integer 0–4294967295) and .applyTextNormalization (auto, on, off). Unsupported fields return 400. See Text to Dialogue for a complete multi-speaker request. For v3/v4 dialogue, set mode: "text_to_dialogue", omit prompt and controls.voiceId, and provide dialogue: [{ "text": "Hi!", "voiceId": "voice_george" }, { "text": "Hello!", "voiceId": "voice_sarah" }]. At most 100 entries and ten distinct voices. Turbo currently accepts single-speaker speech only. A completed task has standard leading fields id, model, status, outputs. outputs.audios contains url, contentType, bytes and expiresAt. URLs are renewable by polling during seven-day retention. usage contains inputCharacters, billableCharacters and chargedUsd; billed characters may differ because of provider usage rounding. Consult /models or /estimate for current final USD prices. Task status is queued, processing, succeeded, failed or cancelled. phase: "reconciliationRequired" means the operation is still resolving its usage/delivery; continue polling without resubmitting. Failed delivery after accepted generation can still have charged usage.

​
Complete-turn WebSocket

Create a session with { "model": "eleven_v4", "controls": { "voiceId": "voice_george" }, "maxCostUsd": 1 }. The response includes sessionId, url, token, tokenExpiresAt, expiresAt and inputMode: "completeTurn". Connect to the returned WSS URL and send the ticket as the first frame within five seconds:
After session.ready, send complete text:
Events: turn.accepted includes a durable taskId; audio.delta includes base64 audio; turn.completed includes final task status and measured usage after settlement. A nonterminal/failed result uses turn.status; error indicates a rejected frame/operation. Only one turn may be in flight. turnId accepts 1–80 ASCII letters, digits, _ or -. Text delta/append frames are unsupported. Reconnect with a new ticket; repeat the same complete turn ID/text to recover its task without regeneration. Completed audio is not replayed or archived for realtime turns. Sessions expire after 50 minutes; tickets after 60 seconds and one use. Only one active connection is allowed. A lost connection lease may take up to 90 seconds to expire before reconnection. maxCostUsd is a cumulative allocation ceiling, default 1/max 10; estimates allocated to accepted turns do not replenish within that session. A closed/disconnected session does not cancel accepted generation or its usage charge.

​
Completion webhooks

Create POST /v1/webhook-endpoints with { "url": "https://your-service.example/audio", "events": ["audio.generation.succeeded", "audio.generation.failed"] }. Save the returned secret; it is shown once. Attach the returned ID as webhookEndpointId on a generation request. Endpoint and task must belong to the same API key. Manage with GET /v1/webhook-endpoints, PATCH /v1/webhook-endpoints/{id} (url/events/enabled), DELETE /v1/webhook-endpoints/{id} (disable), and POST /v1/webhook-endpoints/{id}/rotate-secret. Inspect deliveries with GET /v1/webhook-endpoints/{id}/deliveries; retry eligible failures via POST /v1/webhook-endpoints/{id}/deliveries/{deliveryId}/retry. Verify x-gengen-signature over the exact raw request body: t=<seconds>,v1=<HMAC-SHA256(secret, seconds + "." + rawBody)>. Enforce a five-minute tolerance and constant-time comparison. Deduplicate x-gengen-event-id and respond 2xx quickly. Delivery retries network failures, 429 and 5xx for up to 24 hours. Redirects are not followed. Payload fields are id, type, createdAt, and data containing taskId, model, status, usage. Query the task for a fresh output URL.

​
Errors

400: invalid fields, unsupported mode or voice, text limit. 401/403: invalid/revoked credentials or ticket. 402: insufficient wallet balance or exhausted session budget. 404: resource not owned/found. 409: idempotency conflict, active session or processing HTTP result. 429: too many pending operations. 503: temporarily unavailable service or state requiring retry with the same key. JSON errors use { "error": { "code": "audio.…", "message": "…" } }; bounded-body errors use request.….

​
Try the API

Open the Audio API Explorer to estimate a request, generate MP3 audio, query tasks and test complete-turn WebSocket delivery.

​
Try speech in Playground

Open Playground and select Speech to use Eleven v3, Eleven v4 or Eleven v4 Turbo. Choose a voice, enter up to 2,000 characters and review the estimate before generating. Sign in to generate, listen to the MP3 and download it. Recent tasks remain available after refreshing the page; audio is retained for seven days. Final charges use measured character usage.