Dictionaries

Custom dictionaries are per-project pronunciation and replacement lists. Each entry maps a written word to the text or IPA the TTS pipeline should pronounce instead. Use them for brand names, product names, acronyms, and domain vocabulary that should sound consistent across requests. To apply a dictionary when generating speech, pass its project_id; see Dictionaries at synthesis. For the full HTTP contract, field limits, master-key project_id rules, and error codes, see the Dictionaries API reference.

Create a Dictionary

import os

from kugelaudio import KugelAudio

client = KugelAudio(api_key=os.environ["KUGELAUDIO_API_KEY"])

dictionary = client.dictionaries.create(
    name="Brand names",
    description="Product and company names",
    language="en",
)

print(dictionary.id)

Manage Dictionaries

# List every dictionary in the project
dictionaries = client.dictionaries.list()

# Fetch one
dictionary = client.dictionaries.get(dictionary.id)

# Update name / description / language / is_active (only provided fields change)
dictionary = client.dictionaries.update(
    dictionary.id,
    description="Updated description",
)

Every dictionary and entry method accepts a keyword-only project_id. It is required only for master-key callers acting on a specific project; with a normal project-scoped API key, omit it.

Add and Manage Entries

Use replacement for normal spelling-based fixes. Use ipa when you need an exact phonetic pronunciation; IPA takes precedence over replacement.

created_entry = client.dictionaries.entries.add(
    dictionary.id,
    word="Postgres",
    replacement="post-gres",
)

page = client.dictionaries.entries.list(
    dictionary.id,
    search="post",
    limit=50,
)

for entry in page.entries:
    print(f"{entry.word} → {entry.replacement}")

client.dictionaries.entries.update(
    dictionary.id,
    page.entries[0].id,
    replacement="postgres",
)

client.dictionaries.entries.delete(dictionary.id, page.entries[0].id)

Atomic Bulk Sync

replace_all upserts every entry in one transaction and deletes entries currently in the dictionary whose word is not in the payload. Use it to sync from a CMS, PIM, or internal glossary.

replace_all is intentionally destructive for omitted words. Only call it with the complete desired contents of that dictionary.

result = client.dictionaries.entries.replace_all(
    dictionary.id,
    entries=[
        {"word": "Postgres", "replacement": "post-gres"},
        {"word": "Kubernetes", "replacement": "koo-ber-net-eez"},
    ],
)

print(f"upserted={result.upserted} deleted={result.deleted}")

Dictionaries at synthesis

Dictionaries apply to a synthesis request only when it carries the dictionary’s project_id. Every generation and session method accepts a project_id keyword: generate(), generate_async(), stream(), stream_async(), streaming_session(), streaming_session_sync() and multi_context_session(). With project_id set, the project’s active dictionaries for the request language apply. Add dictionary_ids for an exact selection, or pass [] to disable dictionaries for the request. A non-empty dictionary_ids without project_id is rejected.

audio = client.tts.generate(
    text="Willkommen bei Kugel Audio.",
    voice_id=1071,
    language="de",
    project_id=dictionary.project_id,
    dictionary_ids=[dictionary.id],  # optional: exactly this dictionary
)

Clean up

# Delete a dictionary (cascades to its entries)
client.dictionaries.delete(dictionary.id)

Next steps

Types & Errors: Dictionary, DictionaryEntry, and result models
Text Normalization: how normalization interacts with dictionaries

Get started

Build a voice agent

Generate audio

Voices

Enhance audio

Hosting and deployment

SDK Reference

API Reference

Create a Dictionary

Manage Dictionaries

Add and Manage Entries

Atomic Bulk Sync

Dictionaries at synthesis

Clean up

Next steps

​Create a Dictionary

​Manage Dictionaries

​Add and Manage Entries

​Atomic Bulk Sync

​Dictionaries at synthesis

​Clean up

​Next steps

Create a Dictionary

Manage Dictionaries

Add and Manage Entries

Atomic Bulk Sync

Dictionaries at synthesis

Clean up

Next steps