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

# Tool classes

> Use Conversation, Voice, and utility classes to manage state and configure TTS providers in functions.

**This page requires Python familiarity.** If you are a non-technical operator, work with your developer to configure these classes.

Use these classes in your [functions](https://docs.poly.ai/tools/introduction.md) to manage conversation state and voice configuration.

## Core class

### `Conversation`

The primary class for managing conversation state at runtime. Every function receives a `Conversation` instance as its first argument.

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
def get_conversation_id(conv: Conversation):
    return conv.id
```

For full attributes and methods, see the [`conv` object](https://docs.poly.ai/tools/classes/conv-object) page.

## Voice classes

Use voice classes to configure TTS providers programmatically – for example, in a [start function](https://docs.poly.ai/tools/start-tool.md) or when using [multi-voice](https://docs.poly.ai/voice-channel/multi-voice.md).

### `VoiceWeighting`

Assign specific weightings to voices for [multi-voice](https://docs.poly.ai/voice-channel/multi-voice.md) setups, adjusting their prominence in a given context.

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
VoiceWeighting(
      voice=ElevenLabsVoice(
        provider_voice_id="LcfcDJNUP1GQjkzn1xUU",
        similarity_boost=0.2,
        stability=0.4
      ),
      weight=0.25
    )
```

### TTS provider classes

> [tab] ElevenLabs
>
> Configures voice settings for [ElevenLabs](https://docs.elevenlabs.io/api-reference/voices) TTS, with control over stability and similarity.
>
> ```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
> elevenlabs_voice = ElevenLabsVoice(
>     provider_voice_id="a1b2C3d4E5f6G7h8I9j0",
>     stability=0.5,
>     similarity_boost=0.7
> )
> ```
>
> | Parameter | Description |
> | - | - |
> | `provider_voice_id` | The [ElevenLabs voice ID](https://help.elevenlabs.io/hc/en-us/articles/14599760033937-How-do-I-find-my-voices-ID-of-my-voices-via-the-website-and-through-the-API) |
> | `stability` | Consistency of tone and delivery (0.0–1.0) |
> | `similarity_boost` | How closely the voice matches the original (0.0–1.0) |

> [tab] Cartesia
>
> Configures voice settings for [Cartesia](https://docs.cartesia.ai/api-reference/tts/tts) TTS. Uses `Emotion` objects for expressive control.
>
> ```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
> from polyai.voice import CartesiaVoice, Emotion, EmotionKind, EmotionIntensity
>
> cartesia_voice = CartesiaVoice(
>     provider_voice_id="a1b2c3d4",
>     speed=0.0,
>     emotions=[Emotion(EmotionKind.POSITIVITY, EmotionIntensity.HIGH)]
> )
> ```
>
> | Parameter | Description |
> | - | - |
> | `provider_voice_id` | The Cartesia voice to use |
> | `speed` | Speech rate: -1.0 (slowest) to 1.0 (fastest) |
> | `emotions` | List of `Emotion` objects (see [voice reference](https://docs.poly.ai/tools/classes/voice.md)) |
> | `model_id` | `"sonic"` or `"sonic-preview"` |

> [tab] PlayHT
>
> Configures voice settings for [PlayHT](https://docs.play.ht/reference/api-getting-started) TTS.
>
> ```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
> playht_voice = PlayHTVoice(
>     provider_voice_id="en_us_male_1",
>     voice_engine="Play3.0-mini",
>     speed=1.0
> )
> ```
>
> | Parameter | Description |
> | - | - |
> | `provider_voice_id` | The PlayHT voice to use |
> | `voice_engine` | `"Play3.0-mini"`, `"PlayDialog"`, `"PlayHT2.0-turbo"`, `"PlayHT2.0"`, or `"PlayHT1.0"` |
> | `speed` | Speech rate (0.1–5.0) |
> | `temperature` | Variation in output (0–2) |
> | `emotion` | e.g. `"female_happy"`, `"male_sad"`; only supported by some engines |
> | `voice_guidance` | Adherence to the base voice (1–6) |
> | `style_guidance` | Expressiveness (1–30) |

> [tab] Rime
>
> Configures voice settings for [Rime](https://docs.rime.ai/api-reference/voices) TTS.
>
> ```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
> rime_voice = RimeVoice(
>     provider_voice_id="voice_id",
>     speech_alpha=1.0,
>     model_id="mistv2"
> )
> ```
>
> | Parameter | Description |
> | - | - |
> | `provider_voice_id` | Your configured Rime voice identifier. Contact your PolyAI rep or [Rime](https://docs.rime.ai) for the correct value. |
> | `speech_alpha` | Speech rate multiplier: \<1.0 faster, >1.0 slower |
> | `model_id` | `"mistv2"` or `"mist"` |

> [tab] Minimax
>
> Configures voice settings for Minimax TTS.
>
> ```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
> minimax_voice = MinimaxVoice(
>     model_id="speech-02-hd",
>     voice_id="voice_id",
>     speed=1.0,
>     emotion="happy"
> )
> ```
>
> | Parameter | Description |
> | - | - |
> | `model_id` | `"speech-02-hd"`, `"speech-02-turbo"`, `"speech-01-hd"`, or `"speech-01-turbo"` |
> | `voice_id` | The Minimax voice ID |
> | `speed` | Speech rate (0.5–2.0) |
> | `emotion` | `"happy"`, `"sad"`, `"angry"`, `"fearful"`, `"disgusted"`, `"surprised"`, `"neutral"` |

> [tab] Hume
>
> Configures voice settings for [Hume](https://www.hume.ai/) TTS.
>
> ```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
> hume_voice = HumeVoice(
>     provider_voice_id="voice_uuid_or_name",
>     version="2"
> )
> ```
>
> | Parameter | Description |
> | - | - |
> | `provider_voice_id` | Voice UUID or name |
> | `voice_description` | Optional description for voice personality |
> | `version` | `"1"` (octave-1) or `"2"` (octave-2) |
> | `instant_mode` | Ultra-low latency mode (boolean) |

> [tab] Custom
>
> Define voice configurations for a custom TTS provider.
>
> ```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
> voice_config = CustomVoice(
>     provider="MY_PROVIDER",
>     provider_voice_id="voice_id"
> )
> ```
>
> | Parameter | Description |
> | - | - |
> | `provider` | Custom TTS provider name |
> | `provider_voice_id` | Voice ID within the provider |

For full voice configuration examples including ElevenLabs model IDs, Cartesia emotions, and cache behavior, see the [Voice class reference](https://docs.poly.ai/tools/classes/voice.md).