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.
Inline IPA in the request text
Write the IPA transcription between slashes, directly where the word would
be:
"Willkommen bei /ˈkuːɡl̩/ Audio."
[aˈleks]) are also recognized. The notation passes through
text normalization untouched — the normalizer is trained to copy IPA
notation verbatim — so it composes with normalize: true.
audio = client.tts.generate(
text="Willkommen bei /ˈkuːɡl̩/ Audio.",
language="de",
)
const audio = await client.tts.generate({
text: 'Willkommen bei /ˈkuːɡl̩/ Audio.',
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.",
"language": "de"
}' --output output.pcm
Use real IPA characters (the non-ASCII phonetic alphabet, e.g. ˈ, ː,
ɡ), not ASCII respellings, inside the slashes. A plain English word
between slashes is just read as text. SSML <phoneme> tags are not
supported — write the IPA inline instead.
Pronunciation dictionaries
A dictionary is a per-project word list applied automatically to every
request. Each entry maps a word to either:
- a replacement spelling (write it how it sounds), or
- an IPA transcription (exact phonetic control).
When both are set, IPA wins.
{
"word": "Kugel",
"replacement": "Koogel",
"ipa": "ˈkuːɡl̩"
}
| 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"> | Replace each tag with inline /…/ IPA (the tag itself is stripped) |
Quick example
By default, active dictionaries apply automatically to your project’s
requests (you can also select dictionaries per request
with dictionary_ids):
# Create a dictionary with an IPA entry
d = client.dictionaries.create(name="brand-terms", language="de")
client.dictionaries.entries.add(
d.id,
word="Kugel",
ipa="ˈkuːɡl̩",
)
# Applies automatically from the next request on
audio = client.tts.generate(
text="Willkommen bei Kugel Audio.",
language="de",
)
const d = await client.dictionaries.create({ name: 'brand-terms', language: 'de' });
await client.dictionaries.entries.add(d.id, {
word: 'Kugel',
ipa: 'ˈkuːɡl̩',
});
// Applies automatically from the next request on
const audio = await client.tts.generate({
text: 'Willkommen bei Kugel Audio.',
language: 'de',
});
