Text normalization

KugelAudio normalizes request text so it is spoken naturally: numbers, dates, times, and currencies become words before synthesis.

Text normalization converts numbers, dates, times, and other non-verbal text into spoken words:

“I have 3 apples” → “I have three apples”
“The meeting is at 2:30 PM” → “The meeting is at two thirty PM”
“€50.99” → “fifty euros and ninety-nine cents”

Normalization is on by default (normalize=True in Python, normalize: true in JavaScript and JSON). It runs in the request language. If you omit language, the voice’s primary language (the first entry of its supported_languages) is used, and English if the voice has none. The language is never detected from the text, so German text sent to an English-primary voice without language is normalized as English.

Python
JavaScript
Java
cURL

# With explicit language (recommended)
audio = client.tts.generate(
    text="I bought 3 items for €50.99 on 01/15/2024.",
    voice_id=1071,
    normalize=True,
    language="en",
)

# Without language: normalized in the voice's primary language
audio2 = client.tts.generate(
    text="Ich habe 3 Artikel für 50,99€ gekauft.",
    voice_id=1071,
    normalize=True,
)

// With explicit language (recommended)
const audio = await client.tts.generate({
  text: 'I bought 3 items for €50.99 on 01/15/2024.',
  voiceId: 1071,
  normalize: true,
  language: 'en',
});

// Without language: normalized in the voice's primary language
const audio2 = await client.tts.generate({
  text: 'Ich habe 3 Artikel für 50,99€ gekauft.',
  voiceId: 1071,
  normalize: true,
});

// With explicit language (recommended)
AudioResponse audio = client.tts().generate(
    GenerateRequest.builder("I bought 3 items for €50.99 on 01/15/2024.")
        .voiceId(1071)
        .normalize(true)
        .language("en")
        .build()
);

// Without language: normalized in the voice's primary language
AudioResponse audio2 = client.tts().generate(
    GenerateRequest.builder("Ich habe 3 Artikel für 50,99€ gekauft.")
        .voiceId(1071)
        .normalize(true)
        .build()
);

# With explicit language (recommended)
curl -X POST https://api.kugelaudio.com/v1/tts/generate \
  -H "Authorization: Bearer $KUGELAUDIO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "I bought 3 items for €50.99 on 01/15/2024.",
    "voice_id": 1071,
    "normalize": true,
    "language": "en"
  }' \
  --output output.pcm

# Without language: normalized in the voice's primary language
curl -X POST https://api.kugelaudio.com/v1/tts/generate \
  -H "Authorization: Bearer $KUGELAUDIO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Ich habe 3 Artikel für 50,99€ gekauft.",
    "voice_id": 1071,
    "normalize": true
  }' \
  --output output.pcm

Always set language when the text is not in the voice’s primary language. Otherwise numbers, dates, and currencies are read with the wrong language’s words.

normalize: false does not turn normalization off: it skips the language-model pass, and basic expansion of numbers, dates, times, and currencies still runs on every request.

Supported Languages

Code	Language	Code	Language
`de`	German	`nl`	Dutch
`en`	English	`pl`	Polish
`fr`	French	`sv`	Swedish
`es`	Spanish	`da`	Danish
`it`	Italian	`no`	Norwegian
`pt`	Portuguese	`fi`	Finnish
`cs`	Czech	`hu`	Hungarian
`ro`	Romanian	`el`	Greek
`uk`	Ukrainian	`bg`	Bulgarian
`tr`	Turkish	`vi`	Vietnamese
`ar`	Arabic	`hi`	Hindi
`zh`	Chinese	`ja`	Japanese
`ko`	Korean	`sk`	Slovak
`sl`	Slovenian	`hr`	Croatian
`sr`	Serbian	`ru`	Russian
`he`	Hebrew	`fa`	Persian
`ur`	Urdu	`bn`	Bengali
`ta`	Tamil	`yue`	Cantonese
`th`	Thai	`id`	Indonesian
`ms`	Malay

Spell Tags

Content inside <spell> tags is read character by character and bypasses normalization; the surrounding text is still normalized. Syntax, grouping, and per-language symbol words are on Spell tags.

Custom Pronunciation Dictionaries

When normalization and <spell> tags aren’t enough (brand names, product names, acronyms the model gets wrong), use a per-project dictionary. It applies to requests that send the dictionary’s project_id, and a change takes effect on the next request. Manage dictionaries from the dashboard or the API:

Guide: Dictionaries, how pronunciation dictionaries work
API: /v1/dictionaries, full CRUD plus idempotent bulk replace
SDKs: client.dictionaries.* (Python, JavaScript, Java)

Next Steps

Generate Speech

Basic speech generation

Spell Tags

Read codes and emails character by character

Voice Agent Prompting

System prompt patterns for LLM-driven voice agents

Custom Dictionaries

Per-project pronunciation fixes for brand names and acronyms

Get started

Build a voice agent

Generate audio

Voices

Enhance audio

Hosting and deployment

SDK Reference

API Reference

Text normalization