> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.vapi.ai/llms.txt.
> For full documentation content, see https://docs.vapi.ai/llms-full.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.vapi.ai/_mcp/server.

# 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

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

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

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

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:**
<audio controls src="https://files.buildwithfern.com/https://vapi.docs.buildwithfern.com/3dc4c9345045ac240689f0572f451d182cbfcdeb12b03555f99db2281132167b/static/audio/without-pronunciation-dictionary.wav">Your browser does not support the audio element.</audio>

**With Pronunciation Dictionary:**
<audio controls src="https://files.buildwithfern.com/https://vapi.docs.buildwithfern.com/53211e502cb2303b155723846f31271a6a53f4b213f27e27accbe7cd19d763c5/static/audio/with-pronunciation-dictionary.wav">Your browser does not support the audio element.</audio>

## 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` model.

## Implementation

### ElevenLabs

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

```bash
POST https://api.vapi.ai/provider/11labs/pronunciation-dictionary
Content-Type: application/json
Authorization: Bearer YOUR_API_KEY
```

```json
{
  "name": "My Custom Dictionary",
  "rules": [
    {
      "stringToReplace": "tomato",
      "type": "phoneme",
      "phoneme": "/tə'meɪtoʊ/",
      "alphabet": "ipa"
    },
    {
      "stringToReplace": "Vapi",
      "type": "phoneme", 
      "phoneme": "V AE P IY",
      "alphabet": "cmu-arpabet"
    },
    {
      "stringToReplace": "UN",
      "type": "alias",
      "alias": "United Nations"
    }
  ]
}
```

The API will respond with:

```json
{
  "pronunciationDictionaryId": "rjshI10OgN6KxqtJBqO4",
  "versionId": "xJl0ImZzi3cYp61T0UQG",
  "name": "My Custom Dictionary",
  "rules": [...],
  "createdAt": "2024-01-15T10:30:00Z"
}
```

Update your assistant configuration to use the pronunciation dictionary.

```json
{
  "voice": {
    "model": "eleven_turbo_v2_5",
    "voiceId": "sarah",
    "provider": "11labs",
    "stability": 0.5,
    "similarityBoost": 0.75,
    "pronunciationDictionaryLocators": [
      {
        "pronunciationDictionaryId": "rjshI10OgN6KxqtJBqO4",
        "versionId": "xJl0ImZzi3cYp61T0UQG"
      }
    ]
  }
}
```

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

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

### Cartesia

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

```bash
POST https://api.vapi.ai/provider/cartesia/pronunciation-dictionary
Content-Type: application/json
Authorization: Bearer YOUR_API_KEY
```

```json
{
  "name": "My Cartesia Dictionary",
  "items": [
    {
      "text": "Vapi",
      "alias": "VAH-pee"
    },
    {
      "text": "Nginx",
      "alias": "Engine-X"
    },
    {
      "text": "GIF",
      "alias": "<<ˈ|dʒ|ɪ|f>>"
    }
  ]
}
```

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

Add the pronunciation dictionary ID to your Cartesia voice configuration.

```json
{
  "voice": {
    "model": "sonic-3",
    "voiceId": "your-cartesia-voice-id",
    "provider": "cartesia",
    "pronunciationDictId": "dict_abc123"
  }
}
```

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

### Vapi Built-in Voices

Create a pronunciation dictionary using either the ElevenLabs or Cartesia API endpoints shown above. The dictionary ID from either provider can be used with Vapi built-in voices.

Add the pronunciation dictionary locator to your Vapi voice configuration.

```json
{
  "voice": {
    "provider": "vapi",
    "version": 2,
    "voiceId": "Elliot",
    "pronunciationDictionary": [
      {
        "pronunciationDictId": "pdict_abc123"
      }
    ]
  }
}
```

The `versionId` field is optional for Vapi voices. It is only required when referencing an ElevenLabs-backed dictionary.

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:

```json
{
  "voice": {
    "model": "eleven_turbo_v2_5",
    "voiceId": "your-voice-id",
    "provider": "11labs",
    "pronunciationDictionaryLocators": [
      {
        "pronunciationDictionaryId": "your-elevenlabs-dict-id",
        "versionId": "your-elevenlabs-version-id"
      }
    ]
  }
}
```

## Managing Pronunciation Dictionaries

### ElevenLabs

#### List Your Dictionaries

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

#### Update Dictionary Rules

```bash
PATCH https://api.vapi.ai/provider/11labs/pronunciation-dictionary/{dictionaryId}
Content-Type: application/json
Authorization: Bearer YOUR_API_KEY
```

```json
{
  "rules": [
    {
      "stringToReplace": "tomato",
      "type": "phoneme",
      "phoneme": "/tə'mɑːtoʊ/",
      "alphabet": "ipa"
    }
  ]
}
```

### Cartesia

#### List Your Dictionaries

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

#### Update Dictionary Items

```bash
PATCH https://api.vapi.ai/provider/cartesia/pronunciation-dictionary/{dictionaryId}
Content-Type: application/json
Authorization: Bearer YOUR_API_KEY
```

```json
{
  "items": [
    {
      "text": "Vapi",
      "alias": "VAH-pee"
    }
  ]
}
```

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