API reference / Output formats
Output formats
Set output_format as a query parameter to choose
the container, codec, and sample rate. The default is
mp3_44100_128. The engine renders at 24 kHz and transcodes on the
box via ffmpeg, a raw pass-through, or a Python RIFF wrap.
output_format is a query parameter on the request URL. The
Accept header is ignored. There is
no tier gating — every format below is available.
The menu
| Family | Values | Content-Type |
|---|---|---|
| MP3 | mp3_22050_32, mp3_24000_48, mp3_44100_32 / _64 / _96 / _128 / _192 | audio/mpeg |
| PCM (raw s16le) | pcm_8000 / 16000 / 22050 / 24000 / 32000 / 44100 / 48000 | audio/pcm |
| μ-law (telephony / Twilio) | ulaw_8000 | audio/basic |
| A-law | alaw_8000 | audio/x-alaw-basic |
| Opus (Ogg) | opus_48000_32 / _64 / _96 / _128 / _192 | audio/ogg |
| WAV | wav_8000 / 16000 / 22050 / 24000 / 32000 / 44100 / 48000 | audio/wav |
Naming
Format strings read family_rate[_bitrate]:
mp3_44100_128→ MP3, 44.1 kHz, 128 kbps.pcm_24000→ raw signed 16-bit little-endian PCM, 24 kHz.ulaw_8000→ 8 kHz μ-law, 8-bit — the telephony standard.opus_48000_96→ Opus in an Ogg container, 48 kHz, 96 kbps.
Choosing a format
The engine's native rate — no resample, lowest overhead. Best when you control both ends.
A good general-purpose default: broadly compatible, small.
Ready for Twilio Media Streams and other phone pipelines.
Efficient for real-time / bandwidth-constrained delivery (Ogg container).
How it's produced
- MP3 / Opus / μ-law / A-law — transcoded with ffmpeg
(
libmp3lame/libopus/pcm_mulaw/pcm_alaw). pcm_24000— a raw pass-through of the engine's native PCM (ffmpeg-free).wav_24000— a Python RIFF wrap of the native PCM (ffmpeg-free).
Streaming uses one continuous encoder per request, so a streamed container stays valid end to end.
Examples
curl -X POST \
"https://voice.your-domain.com/v1/text-to-speech/zeli-voice-1?output_format=mp3_44100_192" \
-H "Authorization: Bearer sk-zeli-..." -H "Content-Type: application/json" \
-d '{"text":"High-bitrate MP3."}' --output out.mp3curl -X POST \
"https://voice.your-domain.com/v1/text-to-speech/zeli-voice-1?output_format=ulaw_8000" \
-H "Authorization: Bearer sk-zeli-..." -H "Content-Type: application/json" \
-d '{"text":"Telephony-ready."}' --output out.ulawcurl -X POST \
"https://voice.your-domain.com/v1/text-to-speech/zeli-voice-1?output_format=wav_24000" \
-H "Authorization: Bearer sk-zeli-..." -H "Content-Type: application/json" \
-d '{"text":"Native-rate WAV, no resample."}' --output out.wavAn unknown value returns 400 invalid_output_format — see
Errors.