Skip to content
KugelAudioDocs

Stream Speech

WebSocket reference for /ws/tts: send one text-to-speech request per turn, receive streamed audio chunks and a final message, cancel or update settings.

Stream audio chunks as they're generated for lower latency. One request per turn; the socket is reusable for further requests. For token-by-token text input, use Stream Input.

WSS/ws/tts
import asyncio
import websockets
import json
import base64

async def stream_tts():
    uri = "wss://api.kugelaudio.com/ws/tts?api_key=YOUR_API_KEY"
    audio_chunks = []

    async with websockets.connect(uri) as ws:
        # Send request
        await ws.send(json.dumps({
            "text": "Hello, this is streaming audio.",
            "model_id": "kugel-3.5",
            "voice_id": 1071,
            "cfg_scale": 2.0,
        }))

        # Receive chunks
        async for message in ws:
            data = json.loads(message)

            if "error" in data:
                # Error frames end the request without a final; the socket stays open
                raise RuntimeError(data)

            if "audio" in data:
                audio_chunks.append(base64.b64decode(data["audio"]))
                print(f"Chunk {data['idx']}: {data['samples']} samples")

            if data.get("final"):
                print(f"Complete: {data['dur_ms']}ms audio in {data['gen_ms']}ms")
                usage = data.get("usage", {})
                # cost_cents is the actual charge (EUR cents); None if unavailable
                print(f"Usage: {usage.get('audio_seconds')}s, {usage.get('cost_cents')} ct")
                break

asyncio.run(stream_tts())

Connection

Connect with your API key:

Text
wss://api.kugelaudio.com/ws/tts?api_key=YOUR_API_KEY

Request Message

Send a JSON message to start generation. Fields share the meaning and defaults of the Generate Speech parameters:

JSON
{
  "text": "Hello, this is streaming audio.",
  "model_id": "kugel-3.5",
  "voice_id": 1071,
  "cfg_scale": 2.0,
  "normalize": true,
  "language": "en",
  "speed": 1.0
}
word_timestamps
boolean
bodydefault: false

Enable word-level timestamp alignment. When enabled, a word_timestamps message is sent after the audio chunks with per-word timing data.

speed
number
bodydefault: 1.0

Playback speed multiplier. Range: 0.8 (20% slower) to 1.2 (20% faster). Uses pitch-preserving WSOLA.

dictionary_ids
integer[]
body

Per-request dictionary selection. Omission applies all active dictionaries of the request's project (project_id, or the API key's own project when project_id is omitted), filtered by language; a caller without a project loads none. [] opts out. A non-empty list needs that project and applies exactly those project dictionaries (including inactive ones), bypassing the language filter. project_id itself is described under Generate Speech. Also accepted in the config of /ws/tts/stream and /ws/tts/multi, where both fields are sticky for the session.

Update Settings Message

This socket is reusable across requests. Send an update_settings message to set sticky generation-parameter defaults that fill any field a later request omits; a per-request value still wins. The server replies with settings_updated.

JSON
{
  "update_settings": {
    "cfg_scale": 1.5,
    "temperature": 0.3,
    "speed": 1.1,
    "max_new_tokens": 2048,
    "language": "de",
    "normalize": true
  }
}

Only those six generation parameters are updatable; every field is optional. Identity, project, dictionary, and audio-format fields (voice_id, model_id, sample_rate, output_format, project_id, dictionary_ids) are not; include one and the message is rejected with a VALIDATION_ERROR frame (the socket stays open).

Cancel Message (barge-in)

JSON
{
  "cancel": true
}

Abandons the request that is currently generating: no further audio frames are emitted for it and no final; the server acknowledges with interrupted instead. The socket stays open, so the next request can be sent immediately. A cancel with nothing in flight is acknowledged the same way. See Barge-in.

Response Messages

Audio Chunk

JSON
{
  "audio": "base64_encoded_pcm16_data",
  "enc": "pcm_s16le",
  "idx": 0,
  "sr": 24000,
  "samples": 4800,
  "chunk_id": 0
}

Field-by-field reference: Audio formats.

Word Timestamps (when word_timestamps: true)

JSON
{
  "word_timestamps": [
    {"word": "Hello", "start_ms": 0, "end_ms": 320, "char_start": 0, "char_end": 5, "original_char_start": 0, "original_char_end": 5, "score": 1.0}
  ],
  "chunk_id": 0,
  "text": "Hello world.",
  "original_text": "Hello world."
}

char_* offsets index text, the spoken text; original_char_* offsets index original_text, the text you sent. See Word timestamps for every field.

Settings Updated

Acknowledges an update_settings message; settings holds all sticky generation-parameter defaults now in effect (here, after the update_settings message shown above):

JSON
{
  "settings_updated": true,
  "settings": {
    "cfg_scale": 1.5,
    "temperature": 0.3,
    "speed": 1.1,
    "max_new_tokens": 2048,
    "language": "de",
    "normalize": true
  }
}

Interrupted

Acknowledges a cancel. It replaces final for that request; a cancelled request never finalizes:

JSON
{
  "interrupted": true
}

Final Message

On this endpoint, final is the request-complete message and carries the request's stats and usage. (The streaming endpoints emit a lighter end-of-audio final without usage, followed by session_closed. See Turn lifecycle.)

JSON
{
  "final": true,
  "chunks": 10,
  "total_samples": 48000,
  "dur_ms": 2000,
  "gen_ms": 150,
  "rtf": 0.075,
  "debug": {
    "original_text": "Hello, this is streaming audio.",
    "ttfa_ms": 42.1,
    "speed": 1.0
  },
  "usage": {
    "audio_seconds": 2.0,
    "characters": 31,
    "cost_cents": 0.18,
    "currency": "eur",
    "model_id": "kugel-3.5"
  }
}
FieldTypeDescription
finalbooleanIndicates generation complete
chunksintegerNumber of chunks generated
total_samplesintegerTotal audio samples generated
dur_msnumberTotal audio duration in ms
gen_msnumberTotal generation time in ms
rtfnumberReal-time factor (gen_ms / dur_ms)
debugobjectRequest diagnostics: original_text, nullable ttfa_ms, and effective speed
usageobjectBilling/consumption fields below; present for organization-backed requests

The usage object reports what this request consumed and what it was charged, so you can bill your own customers per request:

FieldDescription
audio_secondsAudio generated for this request (the unit we bill on)
charactersInput characters submitted
cost_centsActual amount charged, in EUR cents. null (with cost_unavailable: true) if the charge could not be determined, never a misleading 0
currencyCurrency of cost_cents ("eur"); present only when cost_cents is set
cost_unavailabletrue when cost_cents could not be determined, including when billing takes longer than about two seconds to confirm (final is not held back; the request is still billed once); otherwise absent
model_idModel that produced the audio

Errors

WebSocket error frames use the same JSON error shape as HTTP responses:

JSON
{
  "error": "Rate limit exceeded",
  "error_code": "RATE_LIMITED",
  "code": 429
}

A refused connection (bad key, connection limit) is an HTTP status on the upgrade, not a close code. See Error Codes for the full lookup table.