Skip to content
KugelAudioDocs

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.

speedEffectTypical use
0.820% slowerDictation, phone numbers, legal disclaimers
1.0Normal (default)General purpose
1.220% fasterNotifications, 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.

Python
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:

Python
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.

rateEffect
"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, rate overrides the global speed; outside, speed applies. Numeric span rates outside 0.8–1.2 are clamped to the nearest endpoint; unlike span rates, an out-of-range global speed is 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 rate is the only supported attribute (pitch / volume are 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 a 400.
  • Malformed tags fail loudly: an unclosed <prosody>, an unknown rate, or a stray </prosody> returns a 400 (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/tts and 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:

Python
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.

Next steps