> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://poly-ai.ferndocs.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://poly-ai.ferndocs.com/_mcp/server.

# Add a voice

**This page requires Python familiarity.** It covers programmatic voice configuration using provider classes. For no-code voice selection, see the [Voice library](/agent-studio/voice/voice-design/voice-library).

The PolyAI platform supports flexible voice selection for external providers including Cartesia, ElevenLabs, Hume, Rime, Minimax, PlayHT, and Google TTS.

## Provider classes

When picking models, adjusting stability, or accessing third-party providers – use provider-specific `TTSVoice` classes. See the [Voice classes](/agent-studio/tools/classes-and-objects/voice) reference for the full list of providers and parameters.

### Example: Cartesia

Cartesia is the recommended provider for new projects due to its low latency and natural output.

```python
from polyai.voice import CartesiaVoice, Emotion, EmotionKind, EmotionIntensity

conv.set_voice(
    CartesiaVoice(
        provider_voice_id="a1b2c3d4",
        speed=0.0,  # -1.0 (slowest) to 1.0 (fastest)
        emotions=[
            Emotion(EmotionKind.POSITIVITY, EmotionIntensity.HIGH)
        ],
        model_id="sonic-3"  # or "sonic-3.5", "sonic-preview"
    )
)
```

### Example: ElevenLabs

```python
from polyai.voice import ElevenLabsVoice

conv.set_voice(
    ElevenLabsVoice(
        provider_voice_id="gDnGxUcsitTxRiGHr904",
        model_id="eleven_turbo_v2_5",  # Recommended default
        stability=1.0,
        similarity_boost=0.7,
        speed=1.0,              # Optional: 0.7–1.2, adjusts speech rate
    )
)
```

Available model IDs: `eleven_monolingual_v1`, `eleven_multilingual_v1`, `eleven_turbo_v2`, `eleven_turbo_v2_5`, `eleven_flash_v2_5`, and `eleven_v3`. The default is `eleven_turbo_v2_5`.

> **Warning**
>
> **`eleven_v3` limitations:**
>
> * **Stability:** Only supports discrete values: `0.0` (Creative), `0.5` (Natural), and `1.0` (Robust). Values between these are not supported and may produce unexpected results.
> * **Streaming latency:** Do not set `optimize_streaming_latency` when using `eleven_v3` – this parameter is not supported and will cause an error.

### Example: Hume

```python
from polyai.voice import HumeVoice

conv.set_voice(
    HumeVoice(
        provider_voice_id="voice_uuid_or_name",
        voice_description="patient, empathetic counselor",  # Optional
        version="2",        # "1" for octave-1, "2" for octave-2
        instant_mode=False,  # Ultra-low latency mode
    )
)
```

## Cache behavior

* Changing `model_id` does not automatically invalidate cached audio.
* To reset cached audio after changing models:
  * Go to **Voice > Audio library** and delete existing cache entries.
  * Or, create a new voice entry with a different voice ID.

> **Tip**
>
> Prepend the model ID to the voice ID (e.g. `eleven_turbo_v2_5/a1b2c3...`) to isolate cache entries per model. This is the most reliable way to ensure the correct model is used after a switch.

## Related pages

#### [Voice library](/agent-studio/voice/voice-design/voice-library)

Browse and select voices

#### [Agent Voice](/agent-studio/voice/settings)

Configure voice settings and fine-tuning

#### [Multi-voice](/agent-studio/voice/voice-design/multi-voice)

Use multiple voices in a single agent

#### [Advanced voice settings](/agent-studio/voice/advanced-settings)

Configure model selection and call settings