AssistantsConversation behavior

Pronunciation dictionaries

Control how your AI assistant pronounces specific words and phrases

Overview

Pronunciation dictionaries allow you to customize how your AI assistant pronounces specific words, names, acronyms, or technical terms. This feature is particularly useful for ensuring consistent pronunciation of brand names, proper nouns, or industry-specific terminology that might be mispronounced by default.

Pronunciation dictionaries are supported by the following voice providers:

  • ElevenLabs — phoneme rules (IPA and CMU Arpabet) and alias rules
  • Cartesia — “sounds-like” aliases and IPA notation (sonic-3 model only)
  • Vapi built-in voices — pronunciation dictionaries via a unified locator (v1 voices only)

Pronunciation dictionaries are supported on Vapi v1 voices only. Vapi v2 voices are powered by xAI’s Grok model, which doesn’t support pronunciation dictionaries yet. For v2 voices, use speech tags to control pronunciation and delivery inline in your text instead.

How Pronunciation Dictionaries Work

1

Create Pronunciation Rules

Define specific words or phrases and how they should be pronounced using either phonetic notation or word substitutions.

2

Upload Dictionary to Vapi

Create a pronunciation dictionary through Vapi’s API with your custom rules.

3

Configure Your Assistant

Associate the pronunciation dictionary with your assistant’s voice configuration.

4

Automatic Application

When your assistant encounters the specified words during conversation, it will use your custom pronunciations automatically.

Sample Audio Examples

Below are examples demonstrating the difference between pronunciations with and without pronunciation dictionaries:

Corrected pronunciations:

  • “Nginx” → “Engine-X” (using alias rule)
  • “Kubernetes” → “/ˌkuːbərˈneɪtiːz/” (using phoneme rule)

Without Pronunciation Dictionary:

With Pronunciation Dictionary:

Prerequisites

  • A Vapi assistant configured with an ElevenLabs, Cartesia, or Vapi voice
  • For ElevenLabs: understanding of phonetic notation (IPA or CMU Arpabet) for phoneme-based rules
  • For Cartesia: the sonic-3 voice model (pronunciation dictionaries are only available on sonic-3)
  • Access to Vapi’s API for dictionary creation

Types of Pronunciation Rules

ElevenLabs Rules

Phoneme Rules

Phoneme rules specify exact pronunciation using phonetic alphabets. These provide the most precise control over pronunciation.

Supported Alphabets:

  • IPA (International Phonetic Alphabet): More universal, uses symbols like /tə'meɪtoʊ/
  • CMU Arpabet: ASCII-based format, uses notation like T AH M EY T OW

Model Compatibility: Phoneme rules only work with specific ElevenLabs models:

  • eleven_turbo_v2
  • eleven_flash_v2

Alias Rules

Alias rules replace words with alternative spellings or phrases. These work with all ElevenLabs models and are useful for:

  • Converting acronyms to full phrases (e.g., “UN” → “United Nations”)
  • Providing phonetic spellings for difficult words
  • Standardizing pronunciation across different contexts

Cartesia Rules

Cartesia pronunciation dictionaries use a text and alias format. Each entry maps a word to its pronunciation. Cartesia supports two alias styles:

  • Sounds-like guidance: A plain-English hint for how to say the word (e.g., "VAH-pee")
  • IPA notation: Precise phonetic spelling wrapped in angle brackets (e.g., "<<ˈ|v|ɑ|ˈ|p|i>>")

Cartesia pronunciation dictionaries are only available with the sonic-3 (or newer) model. In the dashboard, the pronunciation dictionary option only appears once you select a supported model.

Implementation

ElevenLabs

1

Create a Pronunciation Dictionary

Use Vapi’s API to create a pronunciation dictionary with your custom rules.

$POST https://api.vapi.ai/provider/11labs/pronunciation-dictionary
$Content-Type: application/json
$Authorization: Bearer YOUR_API_KEY
1{
2  "name": "My Custom Dictionary",
3  "rules": [
4    {
5      "stringToReplace": "tomato",
6      "type": "phoneme",
7      "phoneme": "/tə'meɪtoʊ/",
8      "alphabet": "ipa"
9    },
10    {
11      "stringToReplace": "Vapi",
12      "type": "phoneme", 
13      "phoneme": "V AE P IY",
14      "alphabet": "cmu-arpabet"
15    },
16    {
17      "stringToReplace": "UN",
18      "type": "alias",
19      "alias": "United Nations"
20    }
21  ]
22}

The API will respond with:

1{
2  "pronunciationDictionaryId": "rjshI10OgN6KxqtJBqO4",
3  "versionId": "xJl0ImZzi3cYp61T0UQG",
4  "name": "My Custom Dictionary",
5  "rules": [
6    {
7      "stringToReplace": "UN",
8      "type": "alias",
9      "alias": "United Nations"
10    }
11  ],
12  "createdAt": "2024-01-15T10:30:00Z"
13}
2

Configure Your Assistant's Voice

Update your assistant configuration to use the pronunciation dictionary.

1{
2  "voice": {
3    "model": "eleven_turbo_v2_5",
4    "voiceId": "sarah",
5    "provider": "11labs",
6    "stability": 0.5,
7    "similarityBoost": 0.75,
8    "pronunciationDictionaryLocators": [
9      {
10        "pronunciationDictionaryId": "rjshI10OgN6KxqtJBqO4",
11        "versionId": "xJl0ImZzi3cYp61T0UQG"
12      }
13    ]
14  }
15}

When a pronunciation dictionary is added, SSML parsing will be automatically enabled for your assistant.

3

Test Your Pronunciation

Create a test call or use the Vapi playground to verify that your custom pronunciations are working correctly.

Cartesia

1

Create a Pronunciation Dictionary

Use Vapi’s API to create a Cartesia pronunciation dictionary.

$POST https://api.vapi.ai/provider/cartesia/pronunciation-dictionary
$Content-Type: application/json
$Authorization: Bearer YOUR_API_KEY
1{
2  "name": "My Cartesia Dictionary",
3  "items": [
4    {
5      "text": "Vapi",
6      "alias": "VAH-pee"
7    },
8    {
9      "text": "Nginx",
10      "alias": "Engine-X"
11    },
12    {
13      "text": "GIF",
14      "alias": "<<ˈ|dʒ|ɪ|f>>"
15    }
16  ]
17}

The API will respond with a dictionary object containing an id you’ll use in the next step.

2

Configure Your Assistant's Voice

Add the pronunciation dictionary ID to your Cartesia voice configuration.

1{
2  "voice": {
3    "model": "sonic-3",
4    "voiceId": "your-cartesia-voice-id",
5    "provider": "cartesia",
6    "pronunciationDictId": "dict_abc123"
7  }
8}
3

Test Your Pronunciation

Create a test call or use the Vapi playground to verify that your custom pronunciations are working correctly.

Vapi Built-in Voices

1

Create an ElevenLabs Pronunciation Dictionary

For Vapi v1 built-in voices, create the pronunciation dictionary through the ElevenLabs endpoint shown above. The response includes both a dictionary ID and a versionId; keep both values.

Vapi built-in voices use a unified pronunciationDictionary field, but most v1 built-in voices route through ElevenLabs under the hood. Do not assume a Cartesia dictionary ID works with every Vapi built-in voice. Cartesia dictionary IDs only apply to Vapi voices that are routed to a Cartesia Sonic voice path.

2

Configure Your Assistant's Voice

Add the ElevenLabs pronunciation dictionary locator to your Vapi voice configuration.

1{
2  "voice": {
3    "provider": "vapi",
4    "version": 1,
5    "voiceId": "Kylie",
6    "pronunciationDictionary": [
7      {
8        "pronunciationDictId": "rjshI10OgN6KxqtJBqO4",
9        "versionId": "xJl0ImZzi3cYp61T0UQG"
10      }
11    ]
12  }
13}

For ElevenLabs-backed dictionaries, versionId is required. It pins the exact dictionary version that the Vapi voice should use.

3

Test Your Pronunciation

Create a test call or use the Vapi playground to verify that your custom pronunciations are working correctly.

Using Your Own ElevenLabs Account (BYOK)

If you’re using your own ElevenLabs API key (Bring Your Own Key), you can create pronunciation dictionaries directly in your ElevenLabs account and reference them in Vapi:

  1. Create a pronunciation dictionary in your ElevenLabs account
  2. Note the pronunciationDictionaryId and versionId from ElevenLabs
  3. Use these IDs in your Vapi assistant configuration:
1{
2  "voice": {
3    "model": "eleven_turbo_v2_5",
4    "voiceId": "your-voice-id",
5    "provider": "11labs",
6    "pronunciationDictionaryLocators": [
7      {
8        "pronunciationDictionaryId": "your-elevenlabs-dict-id",
9        "versionId": "your-elevenlabs-version-id"
10      }
11    ]
12  }
13}

Managing Pronunciation Dictionaries

ElevenLabs

List Your Dictionaries

$GET https://api.vapi.ai/provider/11labs/pronunciation-dictionary
$Authorization: Bearer YOUR_API_KEY

Update Dictionary Rules

$PATCH https://api.vapi.ai/provider/11labs/pronunciation-dictionary/{dictionaryId}
$Content-Type: application/json
$Authorization: Bearer YOUR_API_KEY
1{
2  "rules": [
3    {
4      "stringToReplace": "tomato",
5      "type": "phoneme",
6      "phoneme": "/tə'mɑːtoʊ/",
7      "alphabet": "ipa"
8    }
9  ]
10}

Cartesia

List Your Dictionaries

$GET https://api.vapi.ai/provider/cartesia/pronunciation-dictionary
$Authorization: Bearer YOUR_API_KEY

Update Dictionary Items

$PATCH https://api.vapi.ai/provider/cartesia/pronunciation-dictionary/{dictionaryId}
$Content-Type: application/json
$Authorization: Bearer YOUR_API_KEY
1{
2  "items": [
3    {
4      "text": "Vapi",
5      "alias": "VAH-pee"
6    }
7  ]
8}

Best Practices

  • Case Sensitivity: Pronunciation dictionary searches are case-sensitive. Create separate entries for different capitalizations if needed.
  • Order Matters: Rules are applied in the order they appear in the dictionary. The first matching rule is used.
  • Testing: Always test pronunciation changes with your specific voice and model combination.
  • Phoneme Accuracy: Ensure proper stress marking for multi-syllable words when using phoneme rules.
  • Model Compatibility: ElevenLabs phoneme rules only work with eleven_turbo_v2 and eleven_flash_v2. Cartesia pronunciation dictionaries require the sonic-3 model.

Common Issues

Pronunciation Not Applied

  • Verify you’re using a compatible model (ElevenLabs phoneme rules need specific models; Cartesia needs sonic-3)
  • Check that the word to replace exactly matches the text in your content (case-sensitive)
  • Ensure the pronunciation dictionary is properly referenced in your voice configuration

SSML Conflicts

  • When pronunciation dictionaries are enabled, SSML parsing is automatically activated
  • Ensure any existing SSML tags in your content are properly formatted

Performance Impact

  • Large dictionaries may slightly increase processing time
  • Consider organizing rules by frequency of use for optimal performance