Text-to-Speech (TTS)

Discover how to integrate custom voices from third-party TTS engines for multilingual or localized speech output.

The TTS layer generates natural-sounding voice responses for your PAL. You can use Tavus’s default engine or configure a third-party provider for a specific voice.

Set layers.tts when you Create PAL or update a PAL. For how a PAL fits together, see PAL overview. For languages and locale-oriented setup, see Language support.

Configuring the TTS Layer

Define the TTS layer under the layers.tts object. The snippets below show only the tts object for readability; in a full PAL payload it is nested under layers (see Example configuration).

Below are the parameters available:

1. tts_engine

Specifies the TTS engine.

• Options: tavus-auto (default), cartesia, elevenlabs. Also azure, only as a fallback when your language is not otherwise supported.

tavus-auto is the default. Use it unless you need a specific provider or voice. It selects the best TTS engine and model for each conversation; the underlying provider may change over time. For deterministic behavior, set an explicit provider and model.

If you use tavus-auto, you do not need to specify any other parameters in the tts layer.

Use azure only if you need a language that is not supported by the default engines. Prefer tavus-auto, cartesia, or elevenlabs whenever your language is already covered. See Additional language support via Azure.

"tts": {
  "tts_engine": "cartesia"
}

2. api_key

Authenticates requests to your selected third-party TTS provider. You can obtain an API key from one of the following:

For Cartesia and ElevenLabs, only required when using private (non-public) voices. If you are using Azure as a fallback for an unsupported language, an API key is required.

• Cartesia
• ElevenLabs - if using pronunciation dictionaries, the key must have the pronunciation_dictionaries_write scope (or full account access). See ElevenLabs API key scopes.
• Azure (fallback only) - required when using Azure. Use your own Azure Speech resource key; the resource must be in the East US region (Tavus synthesizes via eastus; a key from another region returns an authentication error). Any standard neural voice available in East US works; only Custom Neural Voices need to be deployed in your resource.

"tts": {
  "api_key": "your-api-key"
}

3. external_voice_id

Specifies which voice to use with the selected TTS engine. To find supported voice IDs, refer to the provider’s documentation:

• Cartesia
• ElevenLabs
• Azure (fallback only; e.g. en-US-JennyNeural) - if using Azure, the voice determines the accent, not the language: any voice speaks the conversation’s language, carrying that voice’s own accent. For a natural result, choose a voice whose locale matches your target language, or use an Azure *MultilingualNeural voice.

You can use any publicly accessible custom voice from ElevenLabs or Cartesia without the provider’s API key. If the custom voice is private, you still need to use the provider’s API key.

"tts": {
  "external_voice_id": "external-voice-id"
}

4. tts_model_name

Model name used by the TTS engine. Refer to:

• Cartesia
• ElevenLabs

tts_model_name is not supported when tts_engine is azure. If you are using Azure as a language fallback, omit this field.

"tts": {
  "tts_model_name": "sonic-3"
}

5. tts_emotion_control

If set to true, enables emotion control in speech. Defaults to true.

"tts": {
  "tts_emotion_control": true
}

6. voice_settings

Optional object for controlling speed, volume, and similar effects. Which approach you use depends on your TTS engine and model:

Engine	Model	Approach
ElevenLabs	All models	voice_settings in PAL config
Cartesia	sonic-2	voice_settings in PAL config
Cartesia	sonic-3	Either voice_settings (global, set once per conversation) or prompt the LLM in system_prompt to output Cartesia SSML tags for dynamic control. Not both.

Cartesia sonic-3: If you use voice_settings for speed/volume, those settings apply globally for the whole conversation and you cannot use SSML tags for dynamic, per-phrase control. If you want dynamic control, omit voice_settings and have the LLM output SSML tags instead. See Cartesia volume, speed, and emotion.

ElevenLabs (all models): Set parameters in the voice_settings object:

Parameter	ElevenLabs
speed	Range 0.7 to 1.2 (0.7 = slowest, 1.2 = fastest)
stability	Range 0.0 to 1.0 (0.0 = variable, 1.0 = stable)
similarity_boost	Range 0.0 to 1.0 (0.0 = creative, 1.0 = original)
style	Range 0.0 to 1.0 (0.0 = neutral, 1.0 = exaggerated)
use_speaker_boost	Boolean (enhances speaker similarity)

See ElevenLabs Voice Settings for details.

Cartesia sonic-2: Use the voice_settings object (e.g. speed, emotion). SSML tags are not used for sonic-2.

Cartesia sonic-3: You can use either of these, but not both:

• voice_settings - We accept speed/volume params for sonic-3. They apply globally, set once per conversation. Use this when you want a single default speed and volume for the entire conversation. Using voice_settings prevents dynamic SSML control.
• SSML in LLM output - Omit voice_settings for speed/volume and instead add instructions to your system_prompt so the LLM outputs Cartesia SSML tags in its responses. This gives you dynamic, per-phrase control. See Cartesia volume, speed, and emotion.

Emotion control is separate; see Emotion Control with Phoenix-4.

Example: system prompt for Cartesia sonic-3 (dynamic speed and volume)

If you are not using voice_settings for sonic-3, add instructions like this to your system_prompt so the LLM outputs Cartesia SSML tags:

When you want to emphasize a word or phrase, use Cartesia SSML tags for speed and volume:
- To slow down: <speed level="0.8">phrase</speed>
- To speed up: <speed level="1.2">phrase</speed>
- To speak louder: <volume level="1.2">phrase</volume>
- To speak more quietly: <volume level="0.8">phrase</volume>
You can combine tags, e.g. <speed level="0.9"><volume level="1.1">important point</volume></speed>.
Only use these tags when it improves clarity or emphasis; keep most of your response in plain text.

Example: voice_settings (ElevenLabs, Cartesia sonic-2, or Cartesia sonic-3 global)

"tts": {
  "voice_settings": {
    "speed": 0.9
  }
}

For sonic-3, this sets global speed once per conversation; for sonic-2 and ElevenLabs, it applies as configured.

Example Configuration

Below is an example PAL with a fully configured TTS layer:

Cartesia

{
  "pal_name": "AI Presenter",
  "system_prompt": "You are a friendly and informative video host.",
  "pipeline_mode": "full",
  "context": "You're delivering updates in a conversational tone.",
  "default_face_id": "r90bbd427f71",
  "layers": {
    "tts": {
      "tts_engine": "cartesia",
      "api_key": "your-api-key",
      "external_voice_id": "external-voice-id",
      "tts_emotion_control": true,
      "tts_model_name": "sonic-3"
    }
  }
}

The Azure example above is only for cases where your target language is not supported by the default engines. Prefer Cartesia or ElevenLabs (or leave tts_engine unset for tavus-auto) whenever possible.

Refer to Create PAL for a complete list of supported fields.