Speko Docs
Text to speech

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.pcm
routingobject

The routing object. Omit for auto/balanced.

inputstringrequired

The text to synthesize. Must be non-empty.

voicestring

Optional 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.

languagestring

Optional 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.

audioobjectrequired

Output format: encoding (pcm_s16le or opus), sample_rate_hz (8000–192000), channels (1–8).

optionsobject

Optional 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.

SettingValuesRoutes
cartesia.normalization"auto", "off", or a language or locale such as "en" or "en-IN"Cartesia sonic-3.6
elevenlabs.stability0 to 1All ElevenLabs models
elevenlabs.similarity_boost0 to 1Flash, Turbo and Multilingual models
elevenlabs.style0 to 1Flash, Turbo and Multilingual models
elevenlabs.speed0.7 to 1.2Flash, Turbo and Multilingual models
elevenlabs.use_speaker_boosttrue or falseFlash, 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 with invalid_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:

HeaderMeaning
Speko-Usage-CharactersCharacters metered for this synthesis
Speko-Provider, Speko-Model, Speko-RegionThe route that served you
Speko-Request-ID, Speko-Attempt-IDCorrelation 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.

On this page