WebSocket streaming

Connect to:

wss://api.teenage.works/v1/audio/speech/stream-input/{voice_id}

The socket accepts pcm or mp3 through the response_format query parameter. output_sample_rate accepts 8000 through 48000 and defaults to 48000.

1. Authenticate and initialize

Send the bearer token in the connection headers. Browser clients that cannot set WebSocket headers can include api_key in the first message.

{
  "text": " ",
  "api_key": "tw_live_...",
  "language_code": "en",
  "quality": "fast",
  "temperature": 1.0,
  "generation_config": {
    "chunk_length_schedule": [120, 160, 250, 290]
  },
  "auto_mode": false
}

The first text value is one space. A chunk schedule accepts up to eight integers; the server clamps each target to 20–1000 characters.

2. Send text

{
  "text": "The next fragment of text.",
  "flush": false,
  "try_trigger_generation": false
}

• flush: true completes the current utterance.
• try_trigger_generation: true generates the pending buffer immediately.
• auto_mode: true buffers fragments until a sentence boundary, configured length threshold, or idle timeout.
• An empty text value ends input, drains audio, and closes the socket.
• Pending text is limited to 4096 characters.

3. Read audio

Audio messages contain a base64 chunk and an isFinal flag.

{
  "audio": "<base64>",
  "isFinal": false,
  "normalizedAlignment": {
    "chars": [],
    "charStartTimesMs": [],
    "charDurationsMs": []
  }
}

The final message is:

{"audio": null, "isFinal": true}

Alignment arrays are compatibility placeholders and do not currently contain timestamps.

Socket errors

Socket errors use an error object before the connection closes or continues:

{"error":{"code":"invalid_text","message":"text must be a string"}}

Common codes are invalid_api_key, invalid_request, invalid_text, text_too_long, and invalid_message.