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:
"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.
audio = client.tts.generate(
text="Willkommen bei /ˈkuːɡl̩/ Audio.",
voice_id=1071,
language="de",
)const audio = await client.tts.generate({
text: 'Willkommen bei /ˈkuːɡl̩/ Audio.',
voiceId: 1071,
language: 'de',
});curl -X POST https://api.kugelaudio.com/v1/tts/generate \
-H "Authorization: Bearer $KUGELAUDIO_API_KEY" \
-H "Content-Type: application/json; charset=utf-8" \
-d '{
"text": "Willkommen bei /ˈkuːɡl̩/ Audio.",
"voice_id": 1071,
"language": "de"
}' --output output.pcmInline 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.
{
"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
| Problem | Tool |
|---|---|
| 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 request | Inline IPA, or just write the spoken form ("Koogel Audio") |
| Text should be spelled character-by-character (codes, emails) | <spell> tags |
| Numbers/dates/currency read wrong | Set 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:
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.