Skip to content
KugelAudioDocs

Dictionaries

Per-project pronunciation and replacement lists for brand names and domain vocabulary

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. The concept is covered in Dictionaries.

Generating speech with a key of the dictionary's project applies it without a project ID; see Dictionaries at synthesis. Changes are available to synthesis after the dictionary mutation finishes.

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

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

The bulk replace (replace_all in Python, Rust and C++, replaceAll in TypeScript, Java and Dart) 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.

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 from the request's project: the project ID you pass, or, when you omit it, the project of your API key. The project's active dictionaries for the request language apply. Add dictionary IDs for an exact selection (inactive ones included), or pass an empty list to disable dictionaries for the request. A non-empty dictionary-ID list from a caller without a project is rejected. If you serve many end customers, give each its own project and key with the Projects API. Keep normalization enabled unless you have a specific reason to bypass it.

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
)

Streaming and multi-context sessions take the same two settings in their configuration and send them with the session configuration; they apply to every turn or context on that connection:

Every generation and session method accepts project_id and dictionary_ids: generate(), generate_async(), stream(), stream_async(), streaming_session(), streaming_session_sync() and multi_context_session().

Python
async with client.tts.streaming_session(
    voice_id=1071, language="en", project_id=dictionary.project_id
) as session:
    ...

Delete a dictionary

Deleting a dictionary also deletes its entries:

client.dictionaries.delete(dictionary.id)

Next steps