Dictionaries

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. Dictionaries apply to the request’s project: the project_id you send, or, when you omit it, the project of the API key making the request. To use another project’s dictionaries, send its project_id (d.project_id in the API and Python, d.projectId in JavaScript). When dictionary_ids is omitted, all active dictionaries of that project apply, filtered by language: a dictionary with a language applies only when it matches the request language. If you omit language, the voice’s primary language (the first entry of its supported_languages) is used for this filter, so set language explicitly. A caller without a project loads no dictionary. 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. The IDs must belong to the request’s project:

Omit the field: all active dictionaries of the project apply, filtered by language; a caller without a project gets none.
[] (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

audio = client.tts.generate(
    text="Postgres runs our product analytics.",
    voice_id=1071,
    language="en",
    project_id=42,
    dictionary_ids=[7],
)

JavaScript

const audio = await client.tts.generate({
  text: 'Postgres runs our product analytics.',
  modelId: 'kugel-3.5',
  voiceId: 1071,
  language: 'en',
  projectId: 42,
  dictionaryIds: [7],
});

Java

AudioResponse audio = client.tts().generate(
    GenerateRequest.builder("Postgres runs our product analytics.")
        .voiceId(1071)
        .language("en")
        .projectId(42)
        .dictionaryIds(List.of(7))
        .build()
);

cURL

curl -X POST https://api.kugelaudio.com/v1/tts/generate \
  -H "Authorization: Bearer $KUGELAUDIO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Postgres runs our product analytics.",
    "voice_id": 1071,
    "language": "en",
    "project_id": 42,
    "dictionary_ids": [7]
  }' \
  --output output.pcm

For raw streaming-input sessions, set both fields once in the sticky session config; the selection then applies to every turn:

{
  "voice_id": 123,
  "language": "en",
  "project_id": 42,
  "dictionary_ids": [7, 9]
}

Dictionaries per end customer

If you serve many end customers, give each one its own project and its own API key. Each customer’s dictionaries then live in their project, and every synthesis request made with that customer’s key applies them without a project_id. The Projects API creates the projects and issues the keys, and walks through onboarding a customer end to end.

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.

Python SDK

Create dictionaries, add entries, and run idempotent 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 bulk replace method: client.dictionaries.entries.replace_all(...) in Python, client.dictionaries.entries.replaceAll(...) in JavaScript, client.dictionaries().entries().replaceAll(...) in Java, or PUT /v1/dictionaries/{id}/entries on the raw API. It upserts every entry in the payload and deletes entries currently in the dictionary whose word is omitted. Repeating the same complete payload is idempotent.

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, synthesis requests made with a key of its project apply it; with a key of another project, send its project_id. Dictionaries apply whether or not normalize is on.

JavaScript

const audio = await client.tts.generate({
  text: 'Postgres runs our product analytics.',
  modelId: 'kugel-3.5',
  voiceId: 1071,
  language: 'en',
  normalize: true,
  projectId: 42,
});

Next steps

Pronunciation & IPA

Inline IPA and when to use a dictionary instead

Text normalization

How numbers, dates and currencies are read

Dictionaries API

Raw HTTP contract for dictionary and entry CRUD

Generate speech

Generation parameters and examples

Get started

Build a voice agent

Generate audio

Voices

Enhance audio

Hosting and deployment

SDK Reference

API Reference

How Dictionaries Work

Choose Dictionaries Per Request

Dictionaries per end customer

Example Entries

Manage Dictionaries

Python SDK

JavaScript SDK

Java SDK

Dictionaries API

Bulk Sync

Generate Audio

Next steps

Pronunciation & IPA

Text normalization

Dictionaries API

Generate speech

​How Dictionaries Work

​Choose Dictionaries Per Request

​Dictionaries per end customer

​Example Entries

​Manage Dictionaries

Python SDK

JavaScript SDK

Java SDK

Dictionaries API

​Bulk Sync

​Generate Audio

​Next steps

Pronunciation & IPA

Text normalization

Dictionaries API

Generate speech

How Dictionaries Work

Choose Dictionaries Per Request

Dictionaries per end customer

Example Entries

Manage Dictionaries

Bulk Sync

Generate Audio

Next steps