Skip to main content
Custom dictionaries let you define how specific words should be spoken before text reaches the TTS model. Each dictionary belongs to a project and contains entries that map a written word to a replacement pronunciation or an IPA transcription. Use dictionaries when a word should always be pronounced the same way:
  • Brand, product, and company names
  • Acronyms that should be expanded or spoken letter by letter
  • Domain terms, customer names, and internal vocabulary
  • Words where normal text normalization is not enough

​
How Dictionaries Work

The TTS pipeline applies active dictionaries during text processing. When a request contains a matching word, KugelAudio substitutes the configured replacement before synthesis. If an entry has ipa, IPA takes precedence over the replacement text. By default you do not pass a dictionary ID to generation requests: all active dictionaries of the API key’s project are applied automatically to both generation and streaming requests, filtered by the request language. To control which dictionaries apply for a specific request, use per-request selection.
Dictionary changes apply to the next synthesis request after the mutation finishes.

​
Choose Dictionaries Per Request

Pass dictionary_ids on a TTS request to choose exactly which dictionaries apply to that request:
  • Omit the field — default behavior: all active dictionaries apply, filtered by language.
  • [] (empty list) — no dictionary applies to this request.
  • [7, 9] (list of IDs) — exactly those dictionaries apply. Explicit selection overrides the is_active flag (an inactive dictionary applies when selected) and bypasses the language filter.
This makes is_active mean “apply by default”: keep a dictionary inactive and select it per request when you want full control over which vocabulary applies to each synthesis. Dictionary IDs are the same id values returned by the Dictionaries API and shown in the dashboard. Unknown IDs or IDs from another project are rejected with a 400 before any audio is generated.
Python
# Apply exactly one dictionary, even if it is inactive
audio = client.tts.generate(
    text="Postgres runs our product analytics.",
    model_id="kugel-3",
    language="en",
    dictionary_ids=[7],
)

# Disable all dictionaries for this request
audio = client.tts.generate(
    text="Postgres runs our product analytics.",
    model_id="kugel-3",
    language="en",
    dictionary_ids=[],
)
JavaScript
const audio = await client.tts.generate({
  text: 'Postgres runs our product analytics.',
  modelId: 'kugel-3',
  language: 'en',
  dictionaryIds: [7],
});
For streaming sessions, set the selection once in the session config — it applies to every turn of the session:
Python
async with client.tts.streaming_session(
    voice_id=123,
    language="en",
    dictionary_ids=[7, 9],
) as session:
    ...

​
Example Entries

WordReplacementUse case
Postgrespost-gresMake a technical term sound natural
Kuberneteskoo-ber-net-eezFix a product pronunciation
APIA P ISpell an acronym instead of reading it as a word

​
Manage Dictionaries

You can manage dictionaries from the dashboard, the SDKs, or the raw API. Use the SDKs for application code and bulk sync jobs; use the API reference when you need exact HTTP fields, response shapes, or error codes.

Python SDK

Create dictionaries, add entries, and run atomic glossary syncs.

JavaScript SDK

Manage dictionaries from Node.js, TypeScript, or browser apps.

Java SDK

Manage dictionaries from Java services.

Dictionaries API

Raw HTTP contract for dictionary and entry CRUD.

​
Bulk Sync

For CMS, PIM, or internal glossary workflows, use the SDK bulk replace method. It atomically upserts every entry in the payload and deletes entries currently in the dictionary whose word is omitted.
Bulk replace is intentionally destructive for omitted words. Call it only with the complete desired contents of that dictionary.

​
Generate Audio

After a dictionary is active, generate normally. Keep text normalization on unless your application has a specific reason to bypass it.
Python
audio = client.tts.generate(
    text="Postgres runs our product analytics.",
    model_id="kugel-3",
    language="en",
    normalize=True,
)