Skip to main content

​
Two Configuration Surfaces

SurfaceWhenWhatMutable?
Query parametersWebSocket URLVoice selection, audio format, sample rate, connection optionsNo — locked at connect
voice_settingsInit frame ({"text": " "})Provider-specific tuning (speed, pitch, format, etc.)No — locked at init
Both are one-shot. After the init frame, no configuration can change for the session. To change settings, open a new connection.

​
Query Parameters

Set on the URL at connect time. Immutable for the session.

​
Voice Selection

ParameterTypeDefaultDescription
voicestring—Voice identifier in Provider.Model.VoiceId format.
The voice_id segment (third part of the voice string) refers to different things depending on the provider and model:
TypeExampleHow you get it
Pre-built voiceTelnyx.NaturalHD.astraBrowse via the Voices API or Voice Design Lab. Shipped by the provider — available to everyone.
Your cloned voiceTelnyx.Qwen3TTS.my-ceo-cloneCreate in the Voice Design Lab. Scoped to your organization — only your API key can use it. Available for Qwen3TTS and Minimax.
BYOK provider voiceelevenlabs.v3.AdamA voice ID from your own ElevenLabs or Resemble account. You bring your own API key; Telnyx relays the request.
The Voices API (GET /v2/ai/tts/voices) returns all voices available to your account — pre-built and cloned — with each voice’s compound id ready to use as the voice parameter.

​
Connection Options

ParameterTypeDefaultDescription
languagestring—BCP-47 language code. Passed to the provider as language_code. Only used by providers that accept it (AWS Polly, Azure, ElevenLabs, Inworld).
text_typestringtextText type hint: text or ssml. Only AWS Polly and Azure use this.
audio_formatstringmp3Output audio format: mp3, linear16, wav, mulaw, alaw, ogg_vorbis. Not all formats are supported by every provider — see providers dedicated pages.
sample_rateintegerprovider defaultOutput sample rate in Hz. Accepted values vary by provider — see providers dedicated pages.
| disable_cache | boolean | false | Bypass the audio cache and always synthesize fresh. |

​
Example

wss://api.telnyx.com/v2/text-to-speech/speech?voice=Telnyx.NaturalHD.astra&audio_format=linear16&disable_cache=true

​
Voice Settings

Provider-specific tuning (speed, pitch, format, emotion, etc.) is not set via query parameters. It is passed once in the voice_settings object on the initialization frame: 
{
  "text": " ",
  "voice_settings": {
    "voice_speed": 1.2,
    "emotion": "happy"
  }
}
Voice settings are applied when the synthesis worker starts and cannot be changed mid-session. There are no common voice_settings fields. Every field is provider-specific — the available fields, defaults, and accepted values are completely different per provider. Unrecognized fields are silently ignored. See your selected provider’s page under Providers for the exact fields.