Synthesize speech
POST /v1/tts/speech — synthesize audio from text in one request.
Request
POST https://router.speko.dev/v1/tts/speech
curl -s https://router.speko.dev/v1/tts/speech \
-H "Authorization: Bearer $SPEKO_API_KEY" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{
"routing": { "mode": "explicit", "provider": "cartesia", "model": "sonic-3" },
"input": "Your order has shipped and will arrive on Thursday.",
"audio": { "encoding": "pcm_s16le", "sample_rate_hz": 24000, "channels": 1 }
}' \
--output speech.pcmroutingobjectThe routing object. Omit for auto/balanced.
inputstringrequiredThe text to synthesize. Must be non-empty.
voicestringOptional provider voice ID. When omitted, the route's default voice is used — useful in auto mode, where you cannot know which provider's voice ID space applies.
languagestringOptional language hint, such as hi or en-GB. Auto routing ranks providers on that language's benchmark board and picks a voice curated for it; the routed provider also reads the text with that language's rules. Omitted means English.
audioobjectrequiredOutput format: encoding (pcm_s16le or opus), sample_rate_hz (8000–192000), channels (1–8).
optionsobjectOptional synthesis settings. options.provider_options carries a vendor's own settings, namespaced by provider name. See Provider settings.
Provider settings
options.provider_options passes a vendor's own synthesis settings through the Router. The same object works on one-shot synthesis and on the streaming session.configure frame, where it applies to every utterance of the session.
| Setting | Values | Routes |
|---|---|---|
cartesia.normalization | "auto", "off", or a language or locale such as "en" or "en-IN" | Cartesia sonic-3.6 |
elevenlabs.stability | 0 to 1 | All ElevenLabs models |
elevenlabs.similarity_boost | 0 to 1 | Flash, Turbo and Multilingual models |
elevenlabs.style | 0 to 1 | Flash, Turbo and Multilingual models |
elevenlabs.speed | 0.7 to 1.2 | Flash, Turbo and Multilingual models |
elevenlabs.use_speaker_boost | true or false | Flash, Turbo and Multilingual models |
Cartesia's normalization decides how numbers, dates, times and currency are read. Set it to a different language from the request's language to keep the speech in one language and read the numbers in another. This Hindi request reads 19,497 and 25/10/2026 the Indian-English way:
{
"routing": { "mode": "explicit", "provider": "cartesia", "model": "sonic-3.6" },
"input": "आपका प्लान 19,497 रुपये का है और due date 25/10/2026 है।",
"voice": "6b02ffe5-e3cb-48c0-a023-c72f85953375",
"language": "hi",
"audio": { "encoding": "pcm_s16le", "sample_rate_hz": 24000, "channels": 1 },
"options": { "provider_options": { "cartesia": { "normalization": "en-IN" } } }
}ElevenLabs' settings are the voice's voice_settings, written flat. similarity_boost is the dashboard's "Clarity + Similarity Enhancement" and style is "Style Exaggeration". When you set none, the voice's own saved settings apply. On ElevenLabs v3 and v4 models the Router currently passes stability only:
"options": { "provider_options": { "elevenlabs": { "stability": 0.4, "similarity_boost": 0.8, "style": 0.2 } } }Rules:
- Settings for a provider the request doesn't reach are ignored, so you can tune several providers and let auto routing choose.
- A setting the routed model can't honor fails with
capability_unsupported, naming the setting and the reason. In auto mode, candidates that can't honor it are skipped instead. A provider name that takes no settings at all fails withinvalid_request. - Values are scalars (boolean, number or string). Names are lower case. At most 8 providers with 16 settings each.
Response
The response body is the raw audio stream (Content-Type: application/octet-stream). Route and usage information travel in headers:
| Header | Meaning |
|---|---|
Speko-Usage-Characters | Characters metered for this synthesis |
Speko-Provider, Speko-Model, Speko-Region | The route that served you |
Speko-Request-ID, Speko-Attempt-ID | Correlation IDs |
One-shot synthesis returns audio only. Word timings are emitted on the streaming endpoint and are not available here.
Metering
TTS bills characters accepted for synthesis. A one-shot request accepts its entire input, so the metered quantity is the character count of input — reported back in Speko-Usage-Characters.