Skip to main content

​
Overview

Pronunciation dictionaries allow you to customize how specific words or phrases are pronounced in your generated audio. This is particularly useful for:
  • Technical terms and abbreviations
  • Brand names and product names
  • Foreign words or names
  • Homographs that need different pronunciations based on context

​
Creating Dictionaries

There are two ways to create pronunciation dictionaries: from rules or from a PLS file.

​
From Rules

Create a dictionary by defining pronunciation rules programmatically: 
from elevenlabs import ElevenLabs
from elevenlabs.pronunciation_dictionaries import (
    BodyAddAPronunciationDictionaryV1PronunciationDictionariesAddFromRulesPostRulesItem_Alias,
)

client = ElevenLabs(api_key="YOUR_API_KEY")

dictionary = client.pronunciation_dictionaries.create_from_rules(
    rules=[
        BodyAddAPronunciationDictionaryV1PronunciationDictionariesAddFromRulesPostRulesItem_Alias(
            string_to_replace="Thailand",
            case_sensitive=True,
            word_boundaries=True,
            alias="tie-land",
        )
    ],
    name="My Dictionary",
)

print(f"Created dictionary with ID: {dictionary.id}")

​
From PLS File

Create a dictionary from a lexicon PLS (Pronunciation Lexicon Specification) file: 
from elevenlabs import ElevenLabs
from elevenlabs.core import File

client = ElevenLabs(api_key="YOUR_API_KEY")

with open("pronunciation.pls", "rb") as f:
    dictionary = client.pronunciation_dictionaries.create_from_file(
        name="Technical Terms",
        description="Pronunciation rules for technical terminology",
        file=File(content=f.read(), file_name="pronunciation.pls")
    )

print(f"Created dictionary: {dictionary.id}")

​
Rule Types

There are two types of pronunciation rules:

​
Alias Rules

Replace a word or phrase with a different spelling: 
from elevenlabs.pronunciation_dictionaries import (
    BodyAddAPronunciationDictionaryV1PronunciationDictionariesAddFromRulesPostRulesItem_Alias,
)

alias_rule = BodyAddAPronunciationDictionaryV1PronunciationDictionariesAddFromRulesPostRulesItem_Alias(
    string_to_replace="AI",
    case_sensitive=True,
    word_boundaries=True,
    alias="Artificial Intelligence",
)
​
string_to_replace
str
required
The word or phrase to be replaced.
​
alias
str
required
The replacement text that will be pronounced instead.
​
case_sensitive
bool
default:false
Whether the match should be case-sensitive.
​
word_boundaries
bool
default:true
Whether to only match whole words (not parts of words).

​
Phoneme Rules

Define pronunciation using phonetic alphabets (IPA or CMU): 
from elevenlabs.pronunciation_dictionaries import (
    BodyAddAPronunciationDictionaryV1PronunciationDictionariesAddFromRulesPostRulesItem_Phoneme,
)

phoneme_rule = BodyAddAPronunciationDictionaryV1PronunciationDictionariesAddFromRulesPostRulesItem_Phoneme(
    string_to_replace="tomato",
    case_sensitive=False,
    word_boundaries=True,
    phoneme="təˈmeɪtoʊ",
    alphabet="ipa",  # or "cmu"
)
​
phoneme
str
required
The phonetic pronunciation in IPA or CMU format.
​
alphabet
str
required
The phonetic alphabet used: "ipa" or "cmu".

​
Managing Dictionaries

​
List All Dictionaries

from elevenlabs import ElevenLabs

client = ElevenLabs(api_key="YOUR_API_KEY")

response = client.pronunciation_dictionaries.list(
    page_size=30,
    sort="creation_time_unix",
    sort_direction="descending"
)

for dictionary in response.pronunciation_dictionaries:
    print(f"{dictionary.name} (ID: {dictionary.id})")
    print(f"  Created: {dictionary.created_at_unix}")

​
Get Dictionary Details

Retrieve a specific dictionary with all its rules: 
dictionary = client.pronunciation_dictionaries.get(
    pronunciation_dictionary_id="21m00Tcm4TlvDq8ikWAM"
)

print(f"Dictionary: {dictionary.name}")
print(f"Version: {dictionary.version_id}")
print(f"Rules: {len(dictionary.rules)} rules defined")

​
Update Dictionary Metadata

Update the name or archive status without changing the rules: 
updated = client.pronunciation_dictionaries.update(
    pronunciation_dictionary_id="21m00Tcm4TlvDq8ikWAM",
    name="Updated Dictionary Name",
    archived=False
)

print(f"Updated: {updated.name}")

​
Download Dictionary

Download a dictionary version as a PLS file: 
pls_content = client.pronunciation_dictionaries.download(
    dictionary_id="dictionary_id",
    version_id="version_id"
)

with open("downloaded.pls", "wb") as f:
    for chunk in pls_content:
        f.write(chunk)

​
Working with Rules

Once you have a dictionary, you can manage its rules:

​
Add Rules

from elevenlabs.pronunciation_dictionaries import (
    BodyAddAPronunciationDictionaryV1PronunciationDictionariesAddFromRulesPostRulesItem_Alias,
)

response = client.pronunciation_dictionaries.rules.add(
    pronunciation_dictionary_id="dictionary_id",
    rules=[
        BodyAddAPronunciationDictionaryV1PronunciationDictionariesAddFromRulesPostRulesItem_Alias(
            string_to_replace="API",
            alias="A P I",
            case_sensitive=True,
        )
    ]
)

print(f"New version: {response.version_id}")

​
Remove Rules

response = client.pronunciation_dictionaries.rules.remove(
    pronunciation_dictionary_id="dictionary_id",
    rule_strings=["API", "SDK"]
)

print(f"Rules removed. New version: {response.version_id}")

​
Using with Text-to-Speech

Apply pronunciation dictionaries when generating audio: 
from elevenlabs import ElevenLabs

client = ElevenLabs(api_key="YOUR_API_KEY")

# First, create or get your dictionary ID
dictionary_id = "your_dictionary_id"

# Use it in text-to-speech
audio = client.text_to_speech.convert(
    text="The AI will process your API request.",
    voice_id="JBFqnCBsd6RMkjVDRZzb",
    model_id="eleven_multilingual_v2",
    pronunciation_dictionary_locators=[
        {"pronunciation_dictionary_id": dictionary_id, "version_id": "latest"}
    ]
)

with open("output.mp3", "wb") as f:
    f.write(audio)

​
Async Support

All pronunciation dictionary operations support async: 
import asyncio
from elevenlabs import AsyncElevenLabs
from elevenlabs.pronunciation_dictionaries import (
    BodyAddAPronunciationDictionaryV1PronunciationDictionariesAddFromRulesPostRulesItem_Alias,
)

client = AsyncElevenLabs(api_key="YOUR_API_KEY")

async def create_and_list():
    # Create dictionary
    dictionary = await client.pronunciation_dictionaries.create_from_rules(
        rules=[
            BodyAddAPronunciationDictionaryV1PronunciationDictionariesAddFromRulesPostRulesItem_Alias(
                string_to_replace="Thailand",
                case_sensitive=True,
                word_boundaries=True,
                alias="tie-land",
            )
        ],
        name="My Dictionary",
    )
    
    # List all dictionaries
    response = await client.pronunciation_dictionaries.list()
    
    for dict_item in response.pronunciation_dictionaries:
        print(f"Found: {dict_item.name}")

asyncio.run(create_and_list())

​
Workspace Access

Control who can access your pronunciation dictionaries: 
from elevenlabs.pronunciation_dictionaries import (
    BodyAddAPronunciationDictionaryV1PronunciationDictionariesAddFromRulesPostWorkspaceAccess,
)

dictionary = client.pronunciation_dictionaries.create_from_rules(
    rules=[...],
    name="Shared Dictionary",
    workspace_access="editor"  # Options: "admin", "editor", "viewer"
)
​
workspace_access
str
Access level for workspace members:
  • "admin" - Full control including deletion
  • "editor" - Can modify and use the dictionary
  • "viewer" - Can only view and use the dictionary
  • Not provided - No workspace access (private)

​
Best Practices

When creating rules for abbreviations like “API” or “AI”, set word_boundaries=True to avoid replacing these letters within other words.
# Good - only replaces standalone "AI"
BodyAddAPronunciationDictionaryV1PronunciationDictionariesAddFromRulesPostRulesItem_Alias(
    string_to_replace="AI",
    alias="A I",
    word_boundaries=True  # Won't replace AI in "CHAIR"
)
Always test your pronunciation rules with sample audio before deploying to production. Different voices may handle the same rules differently.
Dictionaries are versioned automatically when rules change. Keep track of version IDs if you need to reference specific rule sets.
Give your dictionaries clear, descriptive names and descriptions to make them easy to identify and manage.
For phoneme rules, use the IPA (International Phonetic Alphabet) for most languages. CMU is specifically designed for American English.

​
Common Use Cases

​
Technical Documentation

tech_rules = [
    # Abbreviations
    {"string_to_replace": "API", "alias": "A P I"},
    {"string_to_replace": "SDK", "alias": "S D K"},
    {"string_to_replace": "HTTP", "alias": "H T T P"},
    
    # Brand names
    {"string_to_replace": "GitHub", "alias": "git hub"},
    {"string_to_replace": "PostgreSQL", "alias": "post gres Q L"},
]

​
Medical Terminology

medical_rules = [
    BodyAddAPronunciationDictionaryV1PronunciationDictionariesAddFromRulesPostRulesItem_Phoneme(
        string_to_replace="arrhythmia",
        phoneme="əˈrɪðmiə",
        alphabet="ipa"
    ),
]

​
Multilingual Content

multilingual_rules = [
    # French names
    {"string_to_replace": "Renault", "alias": "ruh-noh"},
    # Japanese companies
    {"string_to_replace": "Mitsubishi", "alias": "mit-soo-bee-shee"},
]

​
Next Steps

Async Client

Use pronunciation dictionaries with async operations

Error Handling

Handle errors when working with dictionaries

Build docs developers (and LLMs) love

Get started for freeTalk to us