Spell tags

Wrapping text in <spell> tags causes each character to be read out individually. Useful for email addresses, verification codes, acronyms, and serial numbers.

"Contact us at <spell>hello@kugelaudio.com</spell>"
→  "Contact us at H, E, L, L · O · at · K, U, G, E · L, A, U, D · I, O dot C, O, M"

Each · above is a 500 ms pause: spelled content is automatically grouped so a listener can follow it.

Content inside <spell> automatically bypasses text normalization. normalize: true still normalizes the surrounding prose. Always set language so special characters (@, ., -, _) use the correct language-specific spoken words.

Character translations by language

Character	English	German	French	Spanish
`@`	at	ät	arobase	arroba
`.`	dot	Punkt	point	punto
`-`	dash	Strich	tiret	guión
`_`	underscore	Unterstrich	underscore	guión bajo

Letters are spelled with their phonetic names, digits with their spoken names. Whitespace inside a spell block is read as the word “space” (or the language’s equivalent).

Grouping

Spelled content is grouped automatically: a 500 ms pause every four letters or digits, the way a human reads a code aloud.

"The VIN is <spell>1G1RC6E49BU123456</spell>"
→  "1, G, 1, R · C, 6, E, 4 · 9, B, U, 1 · 2, 3, 4, 5 · 6"

The counter restarts at every boundary — a space, a ., a -, or an @ — so each run of characters is grouped on its own. @ additionally gets a pause on both sides, keeping the two halves of an email address apart. Multi-word content is grouped word by word, and the space between words is still read as the word “space”:

"The name is <spell>Anastasiia Masaltseva</spell>"
→  "A, N, A, S · T, A, S, I · I, A space M, A, S, A · L, T, S, E · V, A"

Override the group size with group="N":

"Your code is <spell group="2">A4B9XZ</spell>"
→  "A, 4 · B, 9 · X, Z"

Use group="0" to switch grouping off and have the content read as one unbroken run.

Examples

Python
JavaScript
cURL

# Email address
audio = client.tts.generate(
    text="Email us at <spell>hello@kugelaudio.com</spell>",
    voice_id=1071,
    normalize=True,
    language="en",
)

# Verification code, grouped in pairs
audio = client.tts.generate(
    text='Your code is <spell group="2">A4B9XZ</spell>',
    voice_id=1071,
    normalize=True,
    language="en",
)

# Acronym with context
audio = client.tts.generate(
    text="We use <spell>TTS</spell>, text-to-speech, for audio output.",
    voice_id=1071,
    normalize=True,
    language="en",
)

// Email address
const audio = await client.tts.generate({
  text: 'Email us at <spell>hello@kugelaudio.com</spell>',
  voiceId: 1071,
  normalize: true,
  language: 'en',
});

// Verification code, grouped in pairs
const audio2 = await client.tts.generate({
  text: 'Your code is <spell group="2">A4B9XZ</spell>',
  voiceId: 1071,
  normalize: true,
  language: 'en',
});

curl -X POST https://api.kugelaudio.com/v1/tts/generate \
  -H "Authorization: Bearer $KUGELAUDIO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Your code is <spell group=\"2\">A4B9XZ</spell>",
    "voice_id": 1071,
    "normalize": true,
    "language": "en"
  }' --output output.pcm

Pitfalls

Keep sentence-ending punctuation outside the tag. <spell>D8239014.</spell> reads the trailing period as the literal word “Dot” (or “Punkt” in German) and runs it into the next sentence. Write <spell>D8239014</spell>. instead.

No nesting. A <spell> tag inside another spell block is read as literal characters.
No break tags inside spell blocks — use grouping for pacing instead.

Spell tags in streaming

When streaming text token-by-token, spell tags that span multiple chunks are handled automatically: the server buffers text until the closing </spell> arrives before generating audio, and auto-closes incomplete tags if the stream ends unexpectedly. See Streaming overview.

When spelling isn’t enough

If a brand name or domain term is pronounced wrong (rather than needing to be spelled out), use a pronunciation dictionary instead — it rewrites or IPA-annotates the word without changing your request text.

Get started

Build a voice agent

Generate audio

Voices

Deploy

SDK Reference

API Reference

Character translations by language

Grouping

Examples

Pitfalls

Spell tags in streaming

When spelling isn’t enough

​Character translations by language

​Grouping

​Examples

​Pitfalls

​Spell tags in streaming

​When spelling isn’t enough

Character translations by language

Grouping

Examples

Pitfalls

Spell tags in streaming

When spelling isn’t enough