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.
/ws/ttsimport 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())const API_KEY = 'YOUR_API_KEY';
const WS_URL = 'wss://api.kugelaudio.com';
function streamTTS(text, voiceId = 1071) {
return new Promise((resolve, reject) => {
const ws = new WebSocket(`${WS_URL}/ws/tts?api_key=${API_KEY}`);
const audioChunks = [];
ws.onopen = () => {
ws.send(JSON.stringify({
text,
model_id: 'kugel-3.5',
voice_id: voiceId,
cfg_scale: 2.0,
}));
};
ws.onmessage = (event) => {
const data = JSON.parse(event.data);
if (data.error) { reject(new Error(data.error)); return; }
if (data.audio) {
const binary = atob(data.audio);
const bytes = new Uint8Array(binary.length);
for (let i = 0; i < binary.length; i++) bytes[i] = binary.charCodeAt(i);
audioChunks.push(bytes);
console.log(`Chunk ${data.idx}: ${data.samples} samples`);
}
if (data.final) {
console.log(`Complete: ${data.dur_ms}ms audio in ${data.gen_ms}ms`);
// Per-request usage: audio time + actual charge (EUR cents, null if unavailable)
console.log('Usage:', data.usage);
ws.close();
resolve(audioChunks);
}
};
ws.onerror = () => reject(new Error('WebSocket error'));
});
}
streamTTS('Hello, this is streaming audio.')
.then(chunks => console.log(`Received ${chunks.length} chunks`))
.catch(console.error);# Install wscat: npm install -g wscat
wscat -c "wss://api.kugelaudio.com/ws/tts?api_key=YOUR_API_KEY"
# Once connected, send:
> {"text": "Hello, this is streaming audio.", "model_id": "kugel-3.5", "voice_id": 1071, "cfg_scale": 2.0}Connection
Connect with your API key:
wss://api.kugelaudio.com/ws/tts?api_key=YOUR_API_KEYRequest Message
Send a JSON message to start generation. Fields share the meaning and defaults of the Generate Speech parameters:
{
"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_timestampsfalseEnable word-level timestamp alignment. When enabled, a word_timestamps message is sent after the audio chunks with per-word timing data.
speed1.0Playback speed multiplier. Range: 0.8 (20% slower) to 1.2 (20% faster). Uses pitch-preserving WSOLA.
dictionary_idsPer-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.
{
"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)
{
"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
{
"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)
{
"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):
{
"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:
{
"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.)
{
"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"
}
}| Field | Type | Description |
|---|---|---|
final | boolean | Indicates generation complete |
chunks | integer | Number of chunks generated |
total_samples | integer | Total audio samples generated |
dur_ms | number | Total audio duration in ms |
gen_ms | number | Total generation time in ms |
rtf | number | Real-time factor (gen_ms / dur_ms) |
debug | object | Request diagnostics: original_text, nullable ttfa_ms, and effective speed |
usage | object | Billing/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:
| Field | Description |
|---|---|
audio_seconds | Audio generated for this request (the unit we bill on) |
characters | Input characters submitted |
cost_cents | Actual amount charged, in EUR cents. null (with cost_unavailable: true) if the charge could not be determined, never a misleading 0 |
currency | Currency of cost_cents ("eur"); present only when cost_cents is set |
cost_unavailable | true 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_id | Model that produced the audio |
Errors
WebSocket error frames use the same JSON error shape as HTTP responses:
{
"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.