Real-time Streaming

Connection

wss://api.lokutor.com/ws/tts?api_key=your-api-key

/ws/tts and /ws are equivalent (same handler, two paths). The handshake also accepts an X-API-Key: sk_... header — preferred outside the browser, since it keeps the key out of the URL (see Authentication).

Request

Send a JSON message after connecting. You can send multiple requests over the same connection — each is a fresh synthesis job.

{
  "text": "Hello, how can I help you today?",
  "voice": "M1",
  "language": "en",
  "speed": 1.0,
  "steps": 4,
  "visemes": false
}

Parameter	Type	Default	Description
`text`	string	—	Text to synthesize. Max 5000 characters.
`voice`	string	none	Voice ID. See Voices. If omitted, the server uses a default for the language (English `en_m5`, Spanish `es_f3`, otherwise that language’s first voice, since 2026-10-02) — pass one explicitly for a stable result. (The JS/Python SDKs’ `TTSClient` default to `F1` client-side if you don’t pass one, so an SDK call keeps `F1`; that default lives in the SDK, not the server.)
`language`	string	none (language-agnostic)	ISO language code. See Languages. If omitted, synthesis proceeds without a specific language hint — pass one explicitly for predictable results. The older `lang` name is still accepted as a deprecated alias.
`speed`	float	`1.0`	Accepted for compatibility, but has no effect — the current model has no rate control.
`steps`	int	`4`	Denoising steps (`nfe` server-side). Accepted, but has no effect: the current voice model runs a fixed `4` on every endpoint.
`visemes`	bool	`false`	Enable lip-sync data. Produces nothing on the current speech model — see Visemes.
`version`	string	server’s default model	Selects a specific loaded TTS model version — see `GET /models` for what’s available.

Response

Binary messages: Raw Int16 PCM audio chunks (44.1 kHz, mono). Large chunks are split into ≤512KB WebSocket frames.
Text message "EOS": Synthesis complete for this request — the connection stays open for further requests.
JSON visemes: A bare JSON array of { v, c, t, id } objects (not wrapped in a {"type":...} envelope) — sent only if visemes: true and only when the model actually produced viseme data for that chunk.
JSON timing (optional, streaming mode only): { "type": "timing", "timing": { ... RTF, IsFirst, ... }, "ttfb_ms"?: number } — internal performance telemetry sent alongside some chunks; ttfb_ms is only present on the first chunk. Treat this as informational, not part of the audio contract.
JSON error: { "type": "error", "data": { "code": "...", "message": "...", "detail": "...", "retryable": true|false } } — same structured shape as every other Lokutor error; see the Error Catalog. This is not a bare {"type":"error","message":"..."} — the payload is under data, and it’s the full structured object.

Best practices

Keep the WebSocket open for multiple requests to avoid handshake latency
The stream runs at the current voice model’s fixed 4 denoising steps, as REST POST /tts/synthesize does
Validate inputs against GET /config before sending
Pass voice and language explicitly: without a language the synthesis is language-agnostic, and the voice you get when you omit voice depends on the language (see the table above)

Languages

All nine supported languages are available.

Get Started

SDK

API Reference

Resources

Real-time Streaming

Connection

Request

Response

Best practices

Languages

​Connection

​Request

​Response

​Best practices

​Languages

Connection

Request

Response

Best practices

Languages