Skip to main content
Pronunciation dictionaries let you define custom pronunciation rules so your persona says words exactly how you want. This is useful for brand names, technical terms, acronyms, and foreign words that TTS engines may mispronounce. Tavus automatically syncs your dictionary to your TTS provider, so rules work regardless of which TTS engine your persona uses.

​
How it works

  1. You create a pronunciation dictionary with a set of rules
  2. Each rule maps a text (the word to match) to a pronunciation (how it should be spoken)
  3. You attach the dictionary to a persona via the pronunciation_dictionary_id field in the TTS layer
When you update a dictionary’s rules, all personas referencing it are automatically updated. When you delete a dictionary, it is cleanly removed from all linked personas.

​
Bring your own TTS API key

If you provide your own TTS API key, you can use Tavus pronunciation dictionaries the same way — just set pronunciation_dictionary_id on the TTS layer. Tavus will sync the dictionary rules to your provider account automatically.

​
Rule types

Each rule requires a type that determines how the pronunciation is interpreted:
TypeDescriptionExample
aliasReplace the matched text with a different spoken phrase"Tavus" → "TAH-vus"
ipaUse IPA (International Phonetic Alphabet) notation"bayou" → "ˈbɑju"

​
Alias rules

Alias rules perform simple text substitution. The TTS engine speaks the pronunciation value instead of the original text. 
{
  "text": "Tavus",
  "pronunciation": "TAH-vus",
  "type": "alias"
}

​
IPA rules

IPA rules let you specify exact phonetic pronunciation. You can provide IPA in two formats:
  • Raw IPA: Standard IPA string (e.g., "hɛloʊ")
  • Pipe-delimited IPA: Pre-tokenized phonemes separated by | (e.g., "ˈ|b|ɑ|j|u")
{
  "text": "bayou",
  "pronunciation": "ˈ|b|ɑ|j|u",
  "type": "ipa"
}

​
Rule options

Each rule supports optional matching parameters:
ParameterTypeDefaultDescription
case_sensitivebooleanfalseWhether matching is case-sensitive
word_boundariesbooleantrueWhether to match only whole words
word_boundaries is only applied by ElevenLabs. When syncing to Cartesia, this option is ignored and the rule is applied without word-boundary matching.
{
  "text": "UN",
  "pronunciation": "United Nations",
  "type": "alias",
  "case_sensitive": false,
  "word_boundaries": false
}

​
Attaching a dictionary to a persona

Set pronunciation_dictionary_id in the TTS layer when creating or updating a persona: 
{
  "persona_name": "Sales Agent",
  "system_prompt": "You are a helpful sales agent.",
  "layers": {
    "tts": {
      "tts_engine": "cartesia",
      "pronunciation_dictionary_id": "pd_abc123def456"
    }
  }
}
Each persona supports one pronunciation dictionary at a time. Setting a new pronunciation_dictionary_id replaces the previous one. Setting it to an empty string removes the dictionary.

​
Limits

LimitValue
Text field max length200 characters
Pronunciation field max length500 characters
Dictionary name max length255 characters

​
API reference