> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tavus.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Text-to-Speech (TTS)

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

The **TTS Layer** in Tavus enables your persona to generate natural-sounding voice responses.
You can configure the TTS layer using a third-party tts engine provider. If `layers.tts` is not specified, Tavus will default to `cartesia` engine.

<Note>
  If you use the default engine, you do not need to specify any parameters within the `tts` layer.
</Note>

## Configuring the TTS Layer

Define the TTS layer under the `layers.tts` object. Below are the parameters available:

### 1. `tts_engine`

Specifies the supported third-party TTS engine.

* **Options**:  `cartesia`, `elevenlabs`.

```json  theme={null}
"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:

<Warning>
  Only required when using private voices.
</Warning>

* <a href="https://play.cartesia.ai/keys" target="_blank">Cartesia</a>
* <a href="https://elevenlabs.io/app/settings/api-keys" target="_blank">ElevenLabs</a>

```json  theme={null}
"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:

* <a href="https://docs.cartesia.ai/api-reference/voices/list" target="_blank">Cartesia</a>
* <a href="https://elevenlabs.io/docs/api-reference/voices/search" target="_blank">ElevenLabs</a>

<Note>
  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.
</Note>

```json  theme={null}
"tts": {
  "external_voice_id": "external-voice-id"
}
```

### 4. `tts_model_name`

Model name used by the TTS engine. Refer to:

* <a href="https://docs.cartesia.ai/2025-04-16/build-with-cartesia/models" target="_blank">Cartesia</a>
* <a href="https://elevenlabs.io/docs/models" target="_blank">ElevenLabs</a>

```json  theme={null}
"tts": {
  "tts_model_name": "sonic-3"
}
```

### 5. `tts_emotion_control`

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

```json  theme={null}
"tts": {
  "tts_emotion_control": true
}
```

### 6. `voice_settings`

Optional object containing additional settings specific to the selected TTS engine.

For **Cartesia**, we support [inline Cartesia SSML settings](https://docs.cartesia.ai/build-with-cartesia/sonic-3/ssml-tags). For **ElevenLabs**, we support the following parameters:

| 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)                       |

<Note>
  See <a href="https://elevenlabs.io/docs/api-reference/voices/settings/get" target="_blank">ElevenLabs Voice Settings</a> for details.
</Note>

```json  theme={null}
"tts": {
  "voice_settings": {
    "speed": 0.9,
    "emotion": ["positivity:high", "curiosity"]
  }
}
```

## Example Configuration

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

<CodeGroup>
  ```json Cartesia theme={null}
  {
    "persona_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_replica_id": "r665388ec672",
    "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"
      }
    }
  }
  ```

  ```json ElevenLabs theme={null}
  {
    "persona_name": "Narrator",
    "system_prompt": "You narrate long stories with clarity and consistency.",
    "pipeline_mode": "full",
    "context": "You're reading a fictional audiobook.",
    "default_replica_id": "r665388ec672",
    "layers": {
      "tts": {
        "tts_engine": "elevenlabs",
        "api_key": "your-api-key",
        "external_voice_id": "elevenlabs-voice-id",
        "voice_settings": {
          "speed": 0.9
        },
        "tts_emotion_control": true,
        "tts_model_name": "eleven_multilingual_v2"
      }
    }
  }
  ```
</CodeGroup>

<Note>
  Refer to the <a href="https://docs.tavus.io/api-reference/personas/create-persona" target="_blank">Create Persona API</a> for a complete list of supported fields.
</Note>


Built with [Mintlify](https://mintlify.com).