Skip to main content

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.

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. You do not pass a dictionary ID to generation requests. Active dictionaries for the API key’s project are applied automatically to both generation and streaming requests.
Dictionary changes apply to the next synthesis request after the mutation finishes.

​
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-2.5",
    language="en",
    normalize=True,
)