Skip to content
KugelAudioDocs

Pronunciation & IPA

Fix how specific words are spoken with inline IPA in the request text, or replacement/IPA entries in pronunciation dictionaries.

On this page

When the model mispronounces a brand name, product, or domain term, you have two tools: write IPA directly in the request text, or set up a pronunciation dictionary that fixes the word in every request that selects it.

Inline IPA in the request text

Write the IPA transcription between slashes, directly where the word would be:

Text
"Willkommen bei /ˈkuːɡl̩/ Audio."

Use the slash form shown here and test it with the target voice and language. Text normalization leaves an IPA span between the slashes unchanged; numbers and dates around it are still expanded.

Python
audio = client.tts.generate(
    text="Willkommen bei /ˈkuːɡl̩/ Audio.",
    voice_id=1071,
    language="de",
)

Inline IPA is per-request. If the same word needs fixing everywhere, put it in a dictionary instead:

Pronunciation dictionaries

A dictionary is a per-project word list. It applies to a synthesis request only when that request sends the dictionary's project_id. Each entry maps a word to either:

  • a replacement spelling (write it how it sounds), or
  • an IPA transcription (exact phonetic control).

replacement is required on every entry; when ipa is also set, IPA wins.

JSON
{
  "word": "Kugel",
  "replacement": "Koogel",
  "ipa": "ˈkuːɡl̩"
}

Dictionaries are managed via the API or SDKs and applied server-side, so your request text stays clean. Send project_id on synthesis from the raw API, from every generation and session method in Python (project_id), Java and JavaScript (projectId), or from the LiveKit and Pipecat plugins. Full management guide: Dictionaries · API reference · SDK reference: Dictionaries (Python, TypeScript, Java).

Choosing the right tool

ProblemTool
Word pronounced wrong everywhere ("Kugel" read as English)Dictionary entry with replacement or ipa
Exact phonetics required (clinical terms, names)Dictionary entry with ipa, or inline /aɪ piː eɪ/
One-off pronunciation fix in a single requestInline IPA, or just write the spoken form ("Koogel Audio")
Text should be spelled character-by-character (codes, emails)<spell> tags
Numbers/dates/currency read wrongSet language + normalization
Migrating from SSML <phoneme alphabet="ipa">Remove the unsupported tag and replace it with inline /…/ IPA

Quick example

Send the dictionary's project ID on synthesis. With projectId set, the project's active dictionaries for the request language apply; use dictionaryIds when you need an exact selection:

TypeScript
const d = await client.dictionaries.create({ name: 'brand-terms', language: 'de' });
await client.dictionaries.entries.add(d.id, {
  word: 'Kugel',
  replacement: 'Koogel',
  ipa: 'ˈkuːɡl̩',
});

const audio = await client.tts.generate({
  text: 'Willkommen bei Kugel Audio.',
  voiceId: 1071,
  language: 'de',
  projectId: d.projectId,
});

See Dictionaries for the language filter, per-request selection, and bulk sync.

Next steps