Skip to navigation
Tools

ElevenLabs

Audio generation plus the voice and model catalog on one gateway route
View as Markdown

Fronts ElevenLabs audio generation together with the voice/model catalog at https://api.elevenlabs.io; the secret xi-api-key header comes from the gateway. The path following /elevenlabs/ is relayed upstream, restricted to generation POSTs and catalog-read GETs:

GET|POST /elevenlabs/<api path>   → https://api.elevenlabs.io/<api path>

Admission is default-deny against a fixed allowlist: the generation POSTs alongside the catalog GETs listed below are what passes, and any other path draws a 404 until the endpoint concerned is added to the allowlist. Kept out: PATCH and DELETE (/v1/convai/agents included), plus the account, workspace, and history reads. Mounted methods: GET, POST.

Common paths

PathPurpose
POST /elevenlabs/v1/text-to-speech/{voice_id}Text to speech (returns audio)
POST /elevenlabs/v1/text-to-speech/{voice_id}/streamStreaming text to speech
POST /elevenlabs/v1/text-to-dialogueMulti-speaker dialogue from scripted turns (returns audio)
POST /elevenlabs/v1/sound-generationGenerate sound effects
POST /elevenlabs/v1/speech-to-textTranscribe audio
POST /elevenlabs/v1/voice-changer/{voice_id}Speech-to-speech: re-voice an uploaded audio clip as the target voice
POST /elevenlabs/v1/audio-isolationIsolate the voice track from an uploaded clip’s background noise
GET /elevenlabs/v1/voices, GET /elevenlabs/v2/voicesList voices
GET /elevenlabs/v1/shared-voicesBrowse the community Voice Library
GET /elevenlabs/v1/modelsList models
GET /elevenlabs/v1/convai/conversation/get-signed-urlSigned URL for a ConvAI WebSocket

Speech-to-text takes a form

POST /elevenlabs/v1/speech-to-text reads multipart/form-data, not JSON; a JSON body answers 422. Send model_id and either the audio file or, for audio already online, cloud_storage_url:

curl -X POST "$GATEWAY/elevenlabs/v1/speech-to-text" \
  -H "Authorization: Bearer $TOKEN" \
  -F model_id=scribe_v1 \
  -F cloud_storage_url=https://storage.googleapis.com/cloud-samples-data/speech/hello.wav

Over MCP, pass the same fields in call_endpoint’s form. Uploading the file itself needs the direct HTTP call above, with -F file=@clip.mp3.

Credential handling

  • xi-api-key is injected as a header; a client-supplied one is overwritten.
  • An xi-api-key query parameter from the client is discarded (any encoding).
  • Authorization is removed before the request goes upstream.

Responses (binary audio included)

Nothing is transformed on the way back. Text-to-speech and sound generation yield binary audio (PCM or audio/mpeg), with chunked delivery on the /stream variants; the gateway relays the bytes exactly.

curl -X POST "$GATEWAY/elevenlabs/v1/text-to-speech/JBFqnCBsd6RMkjVDRZzb" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"text": "Hello from the gateway", "model_id": "eleven_multilingual_v2"}' \
  --output speech.mp3

WebSocket / realtime use

No WebSocket endpoint is proxied — bearer gating and forwarding cover plain HTTP alone.

When realtime is needed, obtain a short-lived credential via the gateway first, then open your socket straight against ElevenLabs:

  1. Call GET /elevenlabs/v1/convai/conversation/get-signed-url via the gateway.
  2. Use the credential it returns to open the WebSocket directly against ElevenLabs.

As before, the master key never lands on the client.

Field-level request and response detail lives in ElevenLabs’ API reference; the gateway modifies neither.