Real-time Streaming

Connection

wss://api.lokutor.com/ws/tts

/ws/tts and /ws are the same endpoint. Authenticate the handshake with an Authorization: Bearer or X-API-Key header, or with ?api_key= where headers cannot be set (the browser WebSocket). In a browser, pass a short-lived wst_ ticket rather than your key (Authentication). The socket stays open: send as many requests as you like, one after another, and each is a separate synthesis.

Request

{
  "text": "Hello, how can I help you today?",
  "voice": "M1",
  "language": "en"
}

Parameter	Type	Default	Description
`text`	string	—	Text to synthesize. At most 5,000 characters (counted as characters, not bytes).
`voice`	string	see below	Voice slot (`F1`–`F5`, `M1`–`M5`) or one of your `clone_…` ids. See Voices.
`language`	string	none	ISO code from `GET /languages`. Pass it explicitly: it chooses the speaker behind the voice slot as well as the pronunciation.
`speed`	number	—	Must be 0.5–2.0, otherwise an error frame `validation.speed_out_of_range`. Accepted for compatibility; no effect on versa-2.0.
`steps`	int	—	Must be at most 128, otherwise an error frame `validation.steps_out_of_range`. Accepted for compatibility; no effect on versa-2.0.
`visemes`	bool	`false`	Lip-sync data. Not available on the current model: nothing is sent (Visemes).
`version`	string	—	Accepted and ignored. `versa-2.0` is the only model.
`pronunciation_dictionary_ids`	string[]	—	Pronunciation dictionaries to apply, on top of your default one. See Pronunciation.
`pronunciations`	array	—	Pronunciation entries for this request only; they win over every dictionary. A malformed entry is an error frame `validation.invalid_request_format`.
`temperature`	number	`0.3`	How varied the delivery is, `0.1`–`1.0`. Outside the range is an error frame `validation.invalid_request_format`.

The older lang name is accepted as an alias for language. The text may carry expression tags ([breath], [laugh], [sigh], and the emotions [happy], [sad], [angry], [surprised], [fearful], [disgusted], [excited], [anxious]) that the voice performs; each sound adds time to the audio. Default voice. When voice is omitted, the server uses M5 (Noah) for English, F3 (Emma) for Spanish, and otherwise the language’s first voice. Pass a voice explicitly for a stable result. The SDKs’ TTSClient always sends one (F1 unless you choose another).

Response

Frame	Meaning
Binary	Int16 PCM audio, 44.1 kHz, mono, little-endian. Large chunks are split into frames of at most 512 KB.
Text `EOS`	This request is complete. The socket stays open for the next one.
Text JSON `{"type": "error", "data": {"code", "message", "detail", "retryable"}}`	The request failed; `data` has the Error Catalog shape. A validation error is not followed by `EOS`; a synthesis failure (`tts.synthesis_failed`) is.

No other JSON messages are sent: there are no timing or progress frames.

Errors and billing

A message that fails validation (empty or too-long text, an unknown voice or language, speed or steps out of range) gets an error frame and is not billed.
A message whose synthesis fails on Lokutor’s side gets an error frame and is not billed either.
Successful messages are billed per character (rate card: tts_per_million_chars).
A balance below the minimum refuses the handshake with 402 (Billing errors).

Concurrency

Each open /ws/tts socket counts toward your account’s concurrent sessions (3 before the first top-up, 10 after; Limits). Past that limit the socket opens, sends an auth.rate_limited error frame, and closes. This differs from /ws/agent and /ws/stt, which refuse the handshake with 429. Close sockets you are not using.

Example (Node.js 22+)

// save as stream.mjs and run: node stream.mjs
const key = encodeURIComponent(process.env.LOKUTOR_API_KEY);
const ws = new WebSocket(`wss://api.lokutor.com/ws/tts?api_key=${key}`);
ws.binaryType = 'arraybuffer';
let bytes = 0;

ws.onopen = () => ws.send(JSON.stringify({ text: 'Hello from Lokutor.', voice: 'F1', language: 'en' }));
ws.onmessage = (event) => {
  if (event.data instanceof ArrayBuffer) {
    bytes += event.data.byteLength;          // play or store the PCM here
  } else if (event.data === 'EOS') {
    console.log(`done: ${bytes} bytes of audio`);
    ws.close();
  } else {
    console.error(JSON.parse(event.data));   // error frame
    ws.close();
  }
};

Best practices

Reuse one socket for several requests to avoid a new handshake each time.
Start playback on the first binary frame; do not wait for EOS.
Pass voice and language on every request.
All nine languages are available.

Get Started

SDK

API Reference

Resources

Real-time Streaming

Connection

Request

Response

Errors and billing

Concurrency

Example (Node.js 22+)

Best practices

​Connection

​Request

​Response

​Errors and billing

​Concurrency

​Example (Node.js 22+)

​Best practices

Connection

Request

Response

Errors and billing

Concurrency

Example (Node.js 22+)

Best practices