Speed
Control speaking rate in KugelAudio text-to-speech with pitch-preserving speed, set globally via the speed parameter or per span with prosody rate tags.
On this page
The speed request parameter adjusts playback rate using pitch-preserving
time-stretching, so the voice stays natural at any rate. It applies
uniformly to all audio in the request, except inside
<prosody rate> spans, which override it.
speed | Effect | Typical use |
|---|---|---|
0.8 | 20% slower | Dictation, phone numbers, legal disclaimers |
1.0 | Normal (default) | General purpose |
1.2 | 20% faster | Notifications, fast-paced UI feedback |
When a request sets no speed, Turkish plays at 0.88, closer to the
pace of native Turkish speakers; every other language plays at 1.0. The
language is the request's language, or the voice's language when the
request sets none, on every TTS endpoint. An explicit speed, including
1.0, is always used as sent. On a streaming session, the
settings_updated acknowledgement reports this default for the session's
language. Time-stretching slows the whole read evenly; it does not add
pauses between phrases.
Values outside 0.8–1.2 are rejected (400 on REST or a validation
error frame on WebSocket). Choose a value inside the range.
audio = client.tts.generate(
text="This entire sentence is read 20% faster.",
voice_id=1071,
speed=1.2,
)Per-span speed with prosody rate
To change speed for part of a request, wrap that text in an
SSML-style <prosody rate="..."> tag:
audio = client.tts.generate(
text=(
'Unsere Rückrufnummer lautet '
'<prosody rate="slow">0800 5834552.</prosody> '
'Wir freuen uns auf Ihren Anruf.'
),
voice_id=1071,
)The text inside the span is synthesized at the span's rate; everything
outside keeps the request's global speed.
rate | Effect |
|---|---|
"slow" | 0.8× (20% slower) |
"medium" | 1.0× (normal) |
"fast" | 1.2× (20% faster) |
"0.8"–"1.2" | Any numeric rate in the supported range |
Rules:
- Inside a span,
rateoverrides the globalspeed; outside,speedapplies. Numeric span rates outside0.8–1.2are clamped to the nearest endpoint; unlike span rates, an out-of-range globalspeedis rejected. - Spans can cover anything from a few words to multiple sentences, and
<break>tags keep working inside them. - A span edge is a short pause. The text before, inside and after a span is spoken as separate phrases, so a span that starts or ends in the middle of a sentence adds a brief pause there. Place span edges at a natural break, or wrap the whole sentence, when the sentence should flow without one.
- Spans cannot be nested, and
rateis the only supported attribute (pitch/volumeare rejected). - A span must not start or end inside a
<spell>block: put the whole spell tag inside the span or outside it. A span boundary inside a spell block returns a400. - Malformed tags fail loudly: an unclosed
<prosody>, an unknown rate, or a stray</prosody>returns a400(REST) or an error frame (WebSocket) instead of being silently ignored. - On the streaming endpoints, a span must open and close within a single message.
- Spans are read on the native endpoints:
POST /v1/tts/generate,/ws/ttsand the multi-context WebSocket. The ElevenLabs-, Vapi-, Cognigy- and Azure-compatible endpoints do not read them.
Dates and times on the phone
On 8 kHz phone lines, callers catch proposed appointments more easily when each date and time is read slower and the options stand as separate sentences. Wrap only the appointment in the span so the rest of the turn keeps its normal pace:
audio = client.tts.generate(
text=(
'Ich kann Ihnen folgende Termine anbieten. '
'<prosody rate="slow">Am Montag, dem neunzehnten Oktober, um neun Uhr fünf.</prosody> '
'<prosody rate="slow">Oder am Mittwoch, dem einundzwanzigsten Oktober, um vierzehn Uhr zehn.</prosody> '
'Welcher Termin passt Ihnen besser?'
),
voice_id=1071,
output_format="pcm_8000",
)A <break> between two options gives the caller a
moment to note the first one before the next starts.