ElevenLabs API paths

Endpoints

POST /v1/text-to-speech/{voice_id}
POST /v1/text-to-speech/{voice_id}/stream
POST /v1/text-to-speech/{voice_id}/stream/with-timestamps
POST /v1/speech-to-text
POST /v1/single-use-token/{token_type}
POST /v1/convai/webhook/{model_provider_id}
xi-api-key: vk-lw-<ULID>

The audio paths mirror ElevenLabs’ own, with ElevenLabs’ own request bodies. Point the ElevenLabs SDK at the gateway with base_url="https://gateway.langwatch.ai" and the virtual key in place of the ElevenLabs key. The key goes in the xi-api-key header the SDK already sends. The ElevenLabs key itself stays on the organization’s ElevenLabs model provider. An SDK that still sends it gets 401 invalid_api_key, because the gateway reads that header as a virtual key. The audio paths are served only by an ElevenLabs credential. A key that cannot reach ElevenLabs answers 400 model_provider_not_bound and no provider is called. There is no fallback to another provider.

Text to speech

curl "https://gateway.langwatch.ai/v1/text-to-speech/EXAVITQu4vr4xnSDxMaL?output_format=mp3_44100_128" \
  -H "xi-api-key: $LANGWATCH_VIRTUAL_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text": "Hello from the gateway.", "model_id": "eleven_flash_v2_5"}' \
  --output hello.mp3

The response is ElevenLabs’ audio bytes and headers, unchanged, relayed as ElevenLabs sends them. /stream and /stream/with-timestamps take the same body and query string and reach the same paths on ElevenLabs. They are gated and metered exactly like the plain path.

curl -N "https://gateway.langwatch.ai/v1/text-to-speech/EXAVITQu4vr4xnSDxMaL/stream?output_format=mp3_44100_128" \
  -H "xi-api-key: $LANGWATCH_VIRTUAL_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text": "Hello from the gateway.", "model_id": "eleven_flash_v2_5"}' \
  --output - | ffplay -i -

/stream/with-timestamps answers with a stream of JSON objects, each carrying audio_base64, alignment and normalized_alignment:

curl -N "https://gateway.langwatch.ai/v1/text-to-speech/EXAVITQu4vr4xnSDxMaL/stream/with-timestamps" \
  -H "xi-api-key: $LANGWATCH_VIRTUAL_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text": "Hello from the gateway.", "model_id": "eleven_flash_v2_5"}' \
  --output -

Parameter	What the gateway does
`text`	Required. Missing: `400 bad_request`. Metered as Unicode characters, from the moment ElevenLabs accepts the request. A caller that disconnects mid-stream is still charged the full text.
`model_id`	Resolved through the key’s aliases and allowlist, then rewritten to the bare model id ElevenLabs knows. Absent: billed and gated as `eleven_multilingual_v2`, the vendor’s own default. Outside the allowlist: `400 model_not_allowed`.
Query string (`output_format`, `enable_logging`, latency settings)	Forwarded as written.
Every other body field (voice settings, and the rest)	Forwarded as written.

The request body is capped at 1 MB; over the cap: 413 payload_too_large. The audio response is capped at 32 MiB, counted as it is relayed: a longer response is cut at the cap.

Speech to text

curl https://gateway.langwatch.ai/v1/speech-to-text \
  -H "xi-api-key: $LANGWATCH_VIRTUAL_KEY" \
  -F "model_id=scribe_v1" \
  -F "file=@call-recording.wav"

The response is ElevenLabs’ transcript JSON, unchanged. Transcription is metered by the audio duration ElevenLabs reports on it.

Form part	What the gateway does
`model_id`	Required, as a form part. Missing: `400 missing_model`. Resolved through the key’s aliases and allowlist.
`file` or `cloud_storage_url`	One of the two is required; missing both: `400 bad_request`. An upload is capped at 26 MB; over the cap: `413 payload_too_large`. For a larger file send `cloud_storage_url`, which ElevenLabs fetches itself.
`webhook`	Refused when truthy with `400 bad_request`, before any call is made. In that mode ElevenLabs answers before it has transcribed, so the call would carry no duration to bill. Send the request without it and read the transcript from the response.
Every other part (diarization, timestamps, and the rest)	Forwarded as written.

Request and response headers

The X-LangWatch-End-User-Id, X-LangWatch-Metadata and Traceparent request headers work as on Chat Completions. The audio paths return the same response headers as Chat Completions, plus ElevenLabs’ own response headers. A forwarded ElevenLabs error carries X-LangWatch-Provider: elevenlabs and the vendor’s Retry-After when it sent one.

Streaming

All three text to speech paths answer with a chunked body that is written and flushed as ElevenLabs sends it. If ElevenLabs fails mid-stream the connection is closed without the terminating chunk, so the HTTP client reports a truncated body. Speech to text does not stream. The transcript is returned complete.

Single-use tokens

curl -X POST "https://gateway.langwatch.ai/v1/single-use-token/tts_websocket?model_id=eleven_flash_v2_5" \
  -H "xi-api-key: $LANGWATCH_VIRTUAL_KEY"

{
  "token": "sutkn_...",
  "langwatch": { "session_id": "req_01K6Y3M8QF7W2VZ4N9DXTB5C0A" }
}

The path is ElevenLabs’ own. The gateway checks the key’s budgets and its open-session cap, mints the token with the stored ElevenLabs key, and returns ElevenLabs’ body with langwatch.session_id added. The same id is on the X-LangWatch-Session-Id response header. A token is valid for 15 minutes and opens one socket. The socket runs from your client to ElevenLabs and does not pass through the gateway. The gateway does not see what the socket used, so your client reports it.

`token_type`	Opens	Default `model_id`
`tts_websocket`	A text to speech socket (`stream-input`, `multi-stream-input`)	`eleven_multilingual_v2`
`ttd_websocket`	The Text to Dialogue socket	`eleven_v3_conversational`
`realtime_scribe`	The realtime speech to text socket	`scribe_v2_realtime`
`batch_scribe`	One `POST /v1/speech-to-text` call made directly to ElevenLabs	`scribe_v2`

Any other token_type answers 400 bad_request. ElevenLabs’ token route takes no model, so the gateway reads one from the model_id query parameter. It is resolved through the key’s aliases and allowlist and is the model the session is billed under. Pass the model your socket will use. Outside the allowlist: 400 model_not_allowed. model_id is not forwarded to ElevenLabs. The route is served only by an ElevenLabs credential, and a customer on a residency host is minted on that host.

Opening the socket

The query parameter that carries the token differs per socket.

Socket	Token type	Query parameter
`wss://api.elevenlabs.io/v1/text-to-speech/{voice_id}/stream-input`	`tts_websocket`	`single_use_token`
`wss://api.elevenlabs.io/v1/text-to-speech/{voice_id}/multi-stream-input`	`tts_websocket`	`single_use_token`
`wss://api.elevenlabs.io/v1/text-to-dialogue/stream-input`	`ttd_websocket`	`single_use_token`
`wss://api.elevenlabs.io/v1/speech-to-text/realtime`	`realtime_scribe`	`token`
`POST https://api.elevenlabs.io/v1/speech-to-text`	`batch_scribe`	`token`

const ws = new WebSocket(
  `wss://api.elevenlabs.io/v1/text-to-speech/${voiceId}/stream-input` +
    `?model_id=eleven_flash_v2_5&single_use_token=${token}`,
);

eleven_v3 and eleven_v4 models run on the Text to Dialogue socket, not on stream-input. Mint a ttd_websocket token for it. ElevenLabs’ reference does not list that token type, and the Text to Dialogue socket accepts no other: a tts_websocket token is refused with close code 1008 and invalid_token_type.

Reporting usage and closing

ElevenLabs sockets send no usage. Count it in your client and post it to the session:

curl -X POST "https://gateway.langwatch.ai/v1/realtime/sessions/$SESSION_ID/usage" \
  -H "xi-api-key: $LANGWATCH_VIRTUAL_KEY" \
  -H "Content-Type: application/json" \
  -d '{"id": "flush-1", "usage": {"characters": 123}}'

Socket	Usage to report
Text to speech	`{"usage":{"characters":N}}`: the characters of text sent for synthesis.
Speech to text	`{"usage":{"audio_seconds":N}}`: the seconds of audio sent.

id names the report. Reports with different ids add up, and a report resent with the same id is recorded once. A report with no id and no final is read as the session total and closes the session. Add "final": true to any report to close the session after it is recorded. To close without usage:

curl -X POST "https://gateway.langwatch.ai/v1/realtime/sessions/$SESSION_ID/close" \
  -H "xi-api-key: $LANGWATCH_VIRTUAL_KEY"

The response body and the charge for a session that never reports are described on Realtime voice.

Relayed sockets

The gateway also serves the ElevenLabs sockets itself. The client opens the socket on the gateway with its virtual key, the gateway opens the same path at ElevenLabs with the stored key and passes frames both ways. Use this when the client should hold no ElevenLabs credential at all and should not report its own usage. A single-use token keeps the socket client to ElevenLabs and saves the hop.

Route (WebSocket upgrade)	Default `model_id`	Metered by
`GET /v1/text-to-speech/{voice_id}/stream-input`	`eleven_multilingual_v2`	Characters
`GET /v1/text-to-speech/{voice_id}/multi-stream-input`	`eleven_multilingual_v2`	Characters
`GET /v1/text-to-dialogue/stream-input`	`eleven_v3_conversational`	Characters
`GET /v1/speech-to-text/realtime`	`scribe_v2_realtime`	Audio seconds

Pass the virtual key as Authorization: Bearer, as the xi-api-key header, or as the xi-api-key or authorization query parameter. The gateway removes the key parameters from the query string and forwards the rest as written (output_format, audio_format, language_code and so on). model_id goes through the key’s aliases and allowlist; outside the allowlist the request answers 400 model_not_allowed before the upgrade.

wscat -c "wss://gateway.langwatch.ai/v1/text-to-speech/$VOICE_ID/stream-input?model_id=eleven_flash_v2_5" \
  -H "xi-api-key: $LANGWATCH_VIRTUAL_KEY"
> {"text":" "}
> {"text":"Hello from the gateway. "}
> {"text":""}

websocat "wss://gateway.langwatch.ai/v1/speech-to-text/realtime?audio_format=pcm_16000&xi-api-key=$LANGWATCH_VIRTUAL_KEY"
{"message_type":"input_audio_chunk","audio_base_64":"<base64 PCM>","commit":false,"sample_rate":16000}

If the first frame carries xi-api-key, xi_api_key or authorization, the gateway strips those fields from that frame. Every other frame is forwarded byte for byte, in both directions.

How relayed sockets are metered

ElevenLabs sockets state no usage, so the gateway counts what the client sends.

Speech. The characters of every text field the client sends: text on stream-input and on each context of multi-stream-input, and each inputs[].text on Text to Dialogue. The keep-alive " " counts one character and the closing "" counts none.
Transcription. The seconds of audio sent: the decoded length of each audio_base_64 chunk divided by the byte rate of audio_format. pcm_16000, the default, is 32,000 bytes per second, and ulaw_8000 is 8,000.

The gateway reads client text frames for those fields only. Usage is recorded at most every 10 seconds while the socket runs and once more when it closes. Do not post usage for a relayed socket. A relayed socket is closed by the gateway on an exhausted budget (1008), a revoked key (1008) and a deploy (1012). The codes and what the client should do are on Realtime voice.

Post-call webhook

POST /v1/convai/webhook/{model_provider_id}
ElevenLabs-Signature: t=<timestamp>,v0=<hmac>

This is the URL to paste into the ElevenLabs workspace webhook settings, for Conversational AI sessions brokered by the gateway. {model_provider_id} is the id of the ElevenLabs model provider row in Settings, Model Providers. Store the webhook secret from ElevenLabs on that same provider row, under ELEVENLABS_WEBHOOK_SECRET. The route takes no virtual key. Each delivery authenticates itself: the gateway relays the raw bytes and the ElevenLabs-Signature header to LangWatch, which computes the HMAC with the provider’s stored secret and accepts a signature timestamp at most 30 minutes old. What happens with a delivery:

Event	What LangWatch does
`post_call_transcription`	Matches the conversation to its session and closes the session’s spend record with the reported cost and duration.
`post_call_audio`, `call_initiation_failure`	Acknowledged and not applied. They carry no duration.

Responses:

Status	Meaning
`200` `{"received":true}`	Accepted, or acknowledged as an event LangWatch does not act on.
`400`	The payload did not parse as a post-call event.
`401`	The signature did not verify.
`404`	No ElevenLabs provider with that id has a webhook secret stored.
`413`	The delivery is too large to relay.
`502`	The gateway could not reach LangWatch to relay the delivery.

The webhook is the fast path. Two minutes after a mint, LangWatch also reads the conversation back from ElevenLabs by its own id, so a session bills even when no delivery arrives.

Errors

The full table is on Errors.

Get Started

SDK Integration

Virtual Keys & Budgets

Billing & Metering

Governance

Providers

Features

API Reference

Self-Hosting

Cookbooks

ElevenLabs API paths

Endpoints

Text to speech

Speech to text

Request and response headers

Streaming

Single-use tokens

Opening the socket

Reporting usage and closing

Relayed sockets

How relayed sockets are metered

Post-call webhook

Errors

​Endpoints

​Text to speech

​Speech to text

​Request and response headers

​Streaming

​Single-use tokens

​Opening the socket

​Reporting usage and closing

​Relayed sockets

​How relayed sockets are metered

​Post-call webhook

​Errors

Endpoints

Text to speech

Speech to text

Request and response headers

Streaming

Single-use tokens

Opening the socket

Reporting usage and closing

Relayed sockets

How relayed sockets are metered

Post-call webhook

Errors