Pronunciation dictionaries

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

How Pronunciation Dictionaries Work

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>>")

Implementation

ElevenLabs

$
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
}

1
{
2
  "pronunciationDictionaryId": "rjshI10OgN6KxqtJBqO4",
3
  "versionId": "xJl0ImZzi3cYp61T0UQG",
4
  "name": "My Custom Dictionary",
5
  "rules": [...],
6
  "createdAt": "2024-01-15T10:30:00Z"
7
}

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
}

Cartesia

$
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
}

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

Vapi Built-in Voices

1
{
2
  "voice": {
3
    "voiceId": "Elliot",
4
    "provider": "vapi",
5
    "pronunciationDictionary": [
6
      {
7
        "pronunciationDictId": "pdict_abc123"
8
      }
9
    ]
10
  }
11
}

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

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