TTS Settings Reference

A text-to-speech request is judged on three things: whether the voice sounds right for your application, whether the first audio arrives fast enough that callers do not notice the wait, and whether the audio plays cleanly on your telephony path. The settings in this article control all three. They let you choose the language, voice, and engine, shape the delivery, set the audio format and sample rate, and bound how long a synthesis may take. This reference lists every TTS setting in the gRPC API, with its type, default, range, and effect.

Before you start. Most TTS settings are supplied on the request that creates the interaction. The exceptions, voice mappings and logging, are inherited from the session or deployment and are covered below. How settings are inherited across levels is explained in Speech Settings: Hierarchy, Inheritance and Value Types. If you use MRCP instead of gRPC, see Mapping to MRCP settings.

Where TTS settings go

Where it is set	Settings
On each TTS interaction (`InteractionCreateTtsRequest`)	`language`, `inline_request` or `ssml_request`, `audio_format`, `synthesis_timeout_ms`, `enable_partial_results`, `engine`, `general_interaction_settings`
Deployment or session, inherited by interactions	`tts_settings` (voice mappings), `logging_settings`, and the session settings

The audio format in particular is not configurable at the session or deployment level, because it is required explicitly on every interaction.

Interaction settings

These settings are part of the request that creates a TTS interaction.

Setting	Type	Default	Range or values	Description
`language`	String	None	A language and country code, such as `en-US` or `de-DE`	The synthesis language for this request.
`audio_format`	Message	None (required)	See Audio format	The audio format the synthesis generates. It is required on every interaction.
`synthesis_timeout_ms`	Integer	5000	Milliseconds	Limits the maximum time allowed for a synthesis.
`enable_partial_results`	Boolean	false	true, false	When true, partial results callbacks are enabled for the interaction, which speeds up the return of synthesis results.
`engine`	Enumeration	TTS_ENGINE_UNSPECIFIED	See the table below	The specific engine to use for this synthesis.
`general_interaction_settings`	Message	None	See below	Settings that apply to every interaction type.

Engines

Legacy and Neural TTS can run for the same language. By default, the platform routes a request to the engine that matches the voice you select. Set engine to override that routing.

Value	Number	Meaning
`TTS_ENGINE_UNSPECIFIED`	0	The default. Routes based on the installed CPU-based TTS, legacy or neural. The default is kept for backward compatibility.
`TTS_ENGINE_NEURAL`	1	Explicitly requests the Neural engine.
`TTS_ENGINE_ION`	2	Explicitly requests the Ion engine.

Partial results

With partial results enabled, partial results callbacks are delivered for the interaction, which speeds up the return of synthesis results. Enable it per interaction with enable_partial_results. The enable_partial_results field inside tts_settings is deprecated; use the interaction field instead.

General interaction settings

Setting	Type	Default	Range or values	Description
`secure_context`	Boolean	false	true, false	When true, certain ASR and TTS data is not logged. Wherever sensitive data would have been recorded, the log shows `_SUPPRESSED` instead. Enable it for prompts that speak account numbers, balances, or other sensitive values.
`custom_interaction_data`	String	None	Free-form	Data you attach for your own external purposes. The platform does not use it.
`logging_tag`	String (repeated)	None	Free-form	Reserved for future use.

Text to synthesize

Supply the text with either an inline request or an SSML URL request. The text can be plain text or SSML. For SSML elements and attributes, see Introduction to SSML.

Inline request

Setting	Type	Default	Range or values	Description
`text`	String	None	Plain text or SSML	The text to synthesize.
`tts_inline_synthesis_settings`	Message	None	See the table below	Optional voice and delivery settings for plain text.
`ssl_verify_peer`	Boolean	true	true, false	Verifies the certificate of the peer on HTTPS requests, using a local certificate authority file. Set to false to skip verification for trusted sites.

SSML URL request

Use this when the SSML is hosted at a URL that the platform should fetch.

Setting	Type	Default	Range or values	Description
`ssml_url`	String	None	A URL	The URL from which to fetch the SSML for the synthesis request.
`ssl_verify_peer`	Boolean	true	true, false	Verifies the certificate of the peer on HTTPS requests, using a local certificate authority file. Set to false to skip verification for trusted sites.

Voice and delivery settings

These optional settings in tts_inline_synthesis_settings choose the voice and shape the delivery of plain text. Most values follow the W3C SSML standard, so you can also express them with SSML elements in the text itself.

Setting	Type	Default	Range or values	Description
`voice`	String	None	A valid voice name	The voice to use, if you are using plain text or the SSML does not specify one. See Neural TTS Languages for available voices.
`synth_emphasis_level`	String	None	strong, moderate, none, reduced	The strength of the emphasis used in the voice.
`synth_prosody_pitch`	String	None	A number followed by `Hz`, a relative change, or x-low, low, medium, high, x-high, default	The pitch of the synthesized audio.
`synth_prosody_contour`	String	None	See the SSML standard on pitch contour	The pitch contour of the synthesized audio.
`synth_prosody_rate`	String	None	A relative change, or x-slow, slow, medium, fast, x-fast, default	The speaking rate.
`synth_prosody_duration`	String	None	A time, such as `250ms` or `3s`	How long the synthesized text takes to play.
`synth_prosody_volume`	String	None	A number, a relative change, or silent, x-soft, soft, medium, loud, x-loud, default	The volume of the synthesized audio.
`synth_voice_age`	String	None	A non-negative integer	The age of the voice.
`synth_voice_gender`	String	None	neutral (uses the default), male, female	The gender to use if none is specified.

Audio format

The audio format is part of every TTS interaction request. Choose it to match what your telephony or media path can play.

Setting	Type	Default	Range or values	Description
`standard_audio_format`	Enumeration	None (required)	See the table below	The audio format to generate.
`sample_rate_hertz`	Integer	8000 (8 kHz)	Hertz	The sample rate of the audio. It is mandatory for raw PCM audio and optional for the other formats. For formats with headers, the value from the file header is used instead.
`channel_count`	Integer	1 (mono)	Number of channels	Specify it only for raw (headerless) multi-channel audio, such as stereo PCM or ULAW. For formats with headers, the file header value is used.

Neural voices are available for 24 kHz, 16 kHz, and 8 kHz synthesis. G.711 formats (ULAW and ALAW) are 8 kHz telephony formats.

Value	Number	Description
`STANDARD_AUDIO_FORMAT_LINEAR16`	1	Uncompressed 16-bit signed little-endian samples (linear PCM)
`STANDARD_AUDIO_FORMAT_ULAW`	2	8-bit audio samples using G.711 PCMU (mu-law)
`STANDARD_AUDIO_FORMAT_ALAW`	3	8-bit audio samples using G.711 PCMA (a-law)
`STANDARD_AUDIO_FORMAT_WAV`	4	WAV formatted audio
`STANDARD_AUDIO_FORMAT_FLAC`	5	FLAC formatted audio
`STANDARD_AUDIO_FORMAT_MP3`	6	MP3 formatted audio
`STANDARD_AUDIO_FORMAT_OPUS`	7	OPUS formatted audio
`STANDARD_AUDIO_FORMAT_M4A`	8	M4A formatted audio
`STANDARD_AUDIO_FORMAT_MP4`	9	Audio packed into an MP4 container
`STANDARD_AUDIO_FORMAT_GSM`	10	GSM audio
`STANDARD_AUDIO_FORMAT_NO_AUDIO_RESOURCE`	100	Explicitly indicates that no audio resource should be allocated

Not every standard format is supported in every case, because different operations natively handle a subset of the formats.

Voice mappings

Voice mappings let a request that names one voice be synthesized with another. The most common use is keeping existing applications working when you move to Neural voices: your SSML and MRCP requests keep their familiar voice names, and the mapping routes each name to the Neural voice you want, so you make no application changes. Mappings are part of the TTS settings, so they are inherited from the deployment or session rather than sent with each request.

Setting	Type	Default	Range or values	Description
`voice_mappings`	Map	None	Keyed by language, such as `fr-CA`	A set of voice mappings for each language. The key is the language the mappings apply to.
`voicePairs`	Map of strings	None	Voice names	Within a language, each key is the voice an application requests, and each value is the platform voice used for synthesis. Use the key `default` to set the default voice for the language.

In JSON, the structure looks like this. Note that the key is voicePairs in camel case. In this example, a request for Elodie in fr-CA is synthesized with Florence, and the default entry sets the default voice for fr-CA.

"ttsSettings": {
  "voiceMappings": {
    "fr-CA": {
      "voicePairs": {
        "Elodie": "Florence",
        "default": "Florence"
      }
    },
    "en-AU": {
      "voicePairs": {
        "Ian": "Leo",
        "default": "Leo"
      }
    }
  }
}

To see how speech settings are edited in a deployment, see Configuring Speech Settings Using the Management API.

Session and logging settings

Session settings (archiving, call and channel identifiers for call detail records, custom session data) and logging verbosity work the same way for TTS as for the other speech products. They are described in the ASR & Transcription Settings Reference.

Mapping to MRCP settings

MRCP clients configure comparable behavior through the [TTS] section of client_property.conf, which uses different names and, in some cases, different defaults and scales. Do not copy a value from one interface to the other without checking the table.

gRPC setting	MRCP / client_property.conf name	Difference
`language`	`SYNTHESIS_LANGUAGE`	MRCP default is `en-US`. In gRPC, specify the language on each request.
`voice`	`SYNTH_VOICE_NAME`	Same meaning. If blank in MRCP, the first licensed voice is used.
`synth_emphasis_level`	`SYNTH_EMPHASIS_LEVEL`	Same values. MRCP default is `moderate`.
`synth_prosody_pitch`	`SYNTH_PROSODY_PITCH`	Same values. MRCP default is `default`.
`synth_prosody_contour`	`SYNTH_PROSODY_CONTOUR`	Same values.
`synth_prosody_rate`	`SYNTH_PROSODY_RATE`	Same values. MRCP default is `default`.
`synth_prosody_duration`	`SYNTH_PROSODY_DURATION`	Same values.
`synth_prosody_volume`	`SYNTH_PROSODY_VOLUME`	Same values. MRCP default is `default`.
`synth_voice_age`	`SYNTH_VOICE_AGE`	Same values.
`synth_voice_gender`	`SYNTH_VOICE_GENDER`	Same values. MRCP default is `neutral`.
`synthesis_timeout_ms`	`TTS_REQUEST_TIMEOUT`	The gRPC default is 5000 ms; the MRCP default is 10000 ms. The setting is the time to wait for synthesis to complete, not the length of the audio.
`audio_format.standard_audio_format`	`SYNTHESIS_SOUND_FORMAT`	gRPC offers the formats listed above; MRCP offers 1 = ULAW, 2 = PCM, 3 = ALAW, default 1.
`audio_format.sample_rate_hertz`	`SYNTHESIS_SAMPLING_RATE`	The gRPC default is 8000. The MRCP article documents 8000 and 22050, with a default of 8000.
`secure_context`	`SECURE_CONTEXT` (in the `[TTS]` section)	Both default to off.
`enable_partial_results`	`MEDIA_SERVER__ENABLE_TTS_PARTIAL_STREAMING` (MRCP API server environment variable)	Documented for MRCP in the release notes where partial results were introduced.

The MRCP client also has TTS properties with no gRPC counterpart: SYNTH_PROSODY_RANGE, SYNTH_VOICE_VARIANT, VISEME_GENERATION, TTS_SERVERS, and LOG_TTS_EVENTS. See Speech Client Configuration (client_property.conf).

Troubleshooting

Symptom	Likely cause and fix
The request fails or the audio is unusable	The audio format is required on every interaction. Set `standard_audio_format`, and set `sample_rate_hertz` for raw PCM. Check that the format suits your telephony path (for example, 8 kHz for G.711).
Synthesis times out on long text	The default `synthesis_timeout_ms` is 5000 ms. Raise it for long prompts. Consider `enable_partial_results` to speed up the return of results.
Callers wait too long before hearing the prompt	Enable `enable_partial_results` on the interaction to speed up the return of synthesis results.
A voice name from an older application is not found	Add a voice mapping that routes the old name to a platform voice, with a `default` entry for the language.
The wrong engine is used	Without an explicit setting, routing follows the voice you select. Set `engine` to request Neural or Ion directly.
A default set in the portal does not change the audio format or timeout	The audio format is required on each request, and the timeout is carried on the create request. Set them there.
Fetching SSML from an HTTPS URL fails	`ssl_verify_peer` is true by default, so the server certificate must be trusted. Fix the certificate chain, or set it to false only for trusted sites.
Sensitive text appears in logs	Set `secure_context` to true for those interactions, so the text is replaced with `_SUPPRESSED` in the logs.

Was this article helpful?