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

def get_conversation_id(conv: Conversation):
    return conv.id

For full attributes and methods, see the conv object page.

Voice classes

Use voice classes to configure TTS providers programmatically – for example, in a start function or when using multi-voice.

VoiceWeighting

Assign specific weightings to voices for multi-voice setups, adjusting their prominence in a given context.

VoiceWeighting(
      voice=ElevenLabsVoice(
        provider_voice_id="LcfcDJNUP1GQjkzn1xUU",
        similarity_boost=0.2,
        stability=0.4
      ),
      weight=0.25
    )

TTS provider classes

ElevenLabs

Configures voice settings for ElevenLabs TTS, with control over stability and similarity.

elevenlabs_voice = ElevenLabsVoice(
    provider_voice_id="a1b2C3d4E5f6G7h8I9j0",
    stability=0.5,
    similarity_boost=0.7
)

Parameter	Description
provider_voice_id	The ElevenLabs voice ID
stability	Consistency of tone and delivery (0.0–1.0)
similarity_boost	How closely the voice matches the original (0.0–1.0)

Cartesia

Configures voice settings for Cartesia TTS. Uses Emotion objects for expressive control.

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)
model_id	"sonic" or "sonic-preview"

PlayHT

Configures voice settings for PlayHT TTS.

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

Rime

Configures voice settings for Rime TTS.

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 for the correct value.
speech_alpha	Speech rate multiplier: <1.0 faster, >1.0 slower
model_id	"mistv2" or "mist"

Minimax

Configures voice settings for Minimax TTS.

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"

Hume

Configures voice settings for Hume TTS.

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)

Custom

Define voice configurations for a custom TTS provider.

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.