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.

Note: Pronunciation dictionaries are exclusive to ElevenLabs voices and require specific model configurations.

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 voice
• Understanding of phonetic notation (IPA or CMU Arpabet) for phoneme-based rules
• Access to Vapi’s API for dictionary creation

Types of Pronunciation 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

Implementation

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

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

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
}

Best Practices

Common Issues

Pronunciation Not Applied

• Verify you’re using a compatible ElevenLabs model for phoneme rules
• Check that the stringToReplace 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