> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kugelaudio.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Dictionaries
> Control pronunciations for brand names, acronyms, and domain vocabulary
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](#choose-dictionaries-per-request).
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](/api-reference/endpoints/dictionaries) and shown in the
dashboard. Unknown IDs or IDs from another project are rejected with a
`400` before any audio is generated.
```python Python theme={null}
# 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=[],
)
```
```typescript JavaScript theme={null}
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 Python theme={null}
async with client.tts.streaming_session(
voice_id=123,
language="en",
dictionary_ids=[7, 9],
) as session:
...
```
## Example Entries
| Word | Replacement | Use case |
| ------------ | ----------------- | ------------------------------------------------ |
| `Postgres` | `post-gres` | Make a technical term sound natural |
| `Kubernetes` | `koo-ber-net-eez` | Fix a product pronunciation |
| `API` | `A P I` | Spell 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.
Create dictionaries, add entries, and run atomic glossary syncs.
Manage dictionaries from Node.js, TypeScript, or browser apps.
Manage dictionaries from Java services.
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 Python theme={null}
audio = client.tts.generate(
text="Postgres runs our product analytics.",
model_id="kugel-3",
language="en",
normalize=True,
)
```