> ## 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.

<AgentInstructions>

## Submitting Feedback

If you encounter incorrect, outdated, or confusing documentation on this page, submit feedback:

POST https://docs.poly.ai/feedback

```json
{
  "path": "/tools/classes",
  "feedback": "Description of the issue"
}
```

Only submit feedback when you have something specific and actionable to report.

</AgentInstructions>

# 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](/tools/introduction) 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](/tools/classes/conv-object) page.

## Voice classes

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

### `VoiceWeighting`

Assign specific weightings to voices for [multi-voice](/voice/multi-voice) 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

<Tabs>
  <Tab title="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>

  <Tab title="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](/tools/classes/voice)) |
    | `model_id`          | `"sonic"` or `"sonic-preview"`                                          |
  </Tab>

  <Tab title="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",
        style="conversational"
    )
    ```

    | Parameter           | Description             |
    | ------------------- | ----------------------- |
    | `provider_voice_id` | The PlayHT voice to use |
    | `style`             | Speaking style or tone  |
  </Tab>

  <Tab title="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>

  <Tab title="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>

  <Tab title="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>

  <Tab title="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 |
  </Tab>
</Tabs>

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