> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gengen.farm/llms.txt
> Use this file to discover all available pages before exploring further.

# Audio API

> Generate speech and dialogue with Eleven v3, v4 and v4 Turbo.

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

## API categories

| Category | Guides and endpoints |
| - | - |
| Text to Speech | [Generate speech audio](/api-reference/elevenlabs/speech), including HTTP streaming; [WebSocket sessions](/api-reference/elevenlabs/create-session) for complete-turn delivery |
| Text to Dialogue | [Generate multi-speaker dialogue](/api-reference/elevenlabs/dialogue) with Eleven v3 or v4 |
| Voices | [Browse the voice library](/api-reference/elevenlabs/voice-library), [list saved voices](/api-reference/elevenlabs/voices), [import a voice](/api-reference/elevenlabs/import-voice), or [remove a binding](/api-reference/elevenlabs/delete-voice) |
| Generations | [Estimate cost](/api-reference/elevenlabs/estimate), [create a task](/api-reference/elevenlabs/create-generation), [list tasks](/api-reference/elevenlabs/list-generations), or [retrieve a task](/api-reference/elevenlabs/get-generation) for speech and dialogue |
| Models | [List available models](/api-reference/elevenlabs/models), supported modes, limits, and final prices |
| Webhooks | [Register a completion webhook](/api-reference/elevenlabs/create-webhook), [manage endpoints](/api-reference/elevenlabs/list-webhooks), and [inspect deliveries](/api-reference/elevenlabs/deliveries) |

## Generate speech

```json theme={"dark"}
{
  "model": "eleven_v4",
  "mode": "text_to_speech",
  "prompt": "Hello, welcome to GENGEN.",
  "controls": { "voiceId": "JBFqnCBsd6RMkjVDRZzb", "outputFormat": "mp3_44100_128" }
}
```

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](/api-reference/elevenlabs/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.

## Choose a voice

`controls.voiceId` accepts an official ElevenLabs voice ID directly, for example
`JBFqnCBsd6RMkjVDRZzb` (George). The same IDs work in dialogue entries and
WebSocket session controls. Existing aliases such as `voice_george`, `voice_sarah`,
`voice_bella` and `voice_roger` remain supported.

Browse standard-rate public voices with
`GET /v1/audio/voice-library?search=narrator&language=en&page=0`.
Optional filters are `search` (name or exact official ID), `language`, `gender`
(`female`, `male`, `neutral`) and `age` (`young`, `middle_aged`, `old`). Pages are
zero-based with up to 30 voices; follow `hasMore`. Responses include `voices`,
`page`, `hasMore` and `totalCount`. Each voice includes its official `id`, name,
description, language, accent and a `previewUrl` when a sample is available.
For an exact lookup, use `?voiceId=JBFqnCBsd6RMkjVDRZzb`.

You can submit an official ID without first saving it. Only available public
library voices with standard rates and official premade voices are supported.
Private voices in another ElevenLabs account, removed voices and custom-rate
voices are rejected. `POST /v1/audio/voices/import` saves a favorite; it does not
clone a voice or transfer ownership. Voice samples can be played without a speech
generation charge.

## 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:

```json theme={"dark"}
{ "type": "session.authenticate", "token": "<ticket>" }
```

After `session.ready`, send complete text:

```json theme={"dark"}
{ "type": "turn.commit", "turnId": "greeting-1", "text": "Hello there." }
```

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](https://gengen.farm/api-explorer/demos/audio-generation) to estimate a request, generate MP3 audio, query tasks and test complete-turn WebSocket delivery.

## Try speech in Playground

Open [Playground](https://gengen.farm/playground?media=audio) and select **Speech** to use Eleven v3, Eleven v4 or Eleven v4 Turbo. Open the voice library to search, filter and audition voices, then 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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.