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.

Dictionaries also teach speech to text your spelling: the written word of every entry is used as custom vocabulary when the project's audio is transcribed, chosen by the same rules. The pronunciation plays no part in 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.

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.

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

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

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

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

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.

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.

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.

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