Synthesize speech (WebSocket)

You open a persistent WebSocket connection and send text messages. The server streams audio chunks back over the same connection — no per-request overhead, no repeated handshakes. This gives you the lowest possible latency.

Best for voice agents and interactive applications that send multiple synthesis requests in a session, where avoiding connection setup on every call makes a measurable difference.

Message pipelining

Messages on a connection are processed in order, so you don't need to wait for the contextCreated acknowledgment before sending text. For the lowest latency, send each message as soon as it is ready — waiting for the acknowledgment adds a full network round trip before the first audio chunk arrives. If you omit contextId, messages are automatically routed to the connection's auto-created context.

Choose when speech generation starts

Choose a mode based on how text arrives in your application:

A context holds the settings and text for a speech-generation session within the WebSocket connection. The buffer holds text waiting to be synthesized. To flush is to request synthesis of the buffered text, even if it has no final punctuation. Complete any markup tags before flushing.

Set autoMode and autoModeStrategy in the create message when creating a context. Leave the buffering safeguards at their defaults for normal use.

Manual flushing

Use autoMode: false when you have a complete reply or want to decide how to batch text. Send text with sendText, then call flushContext to request speech generation. If you have no more text for this context, use closeContext instead.

To synthesize buffered text and keep the context open for more text, send:

ws.send(JSON.stringify({contextId: "reply-1", flushContext: {}}));

Use flushContext between batches you want to control yourself. When finished, close the context to release any remaining text and finish receiving audio.

autoModeStrategy is ignored in this mode. See the runnable manual-flushing guide, which also covers interruptions and keeping LLM history aligned with what the user heard.

Client-segmented streaming

Use autoMode: true with autoModeStrategy: "CLIENT_SEGMENTED" when your app already splits text into sentences or phrases. Send each complete segment as it becomes available. The server controls flushing and can combine queued segments while earlier audio is streaming.

See the runnable client-side sentence-splitting guide.

Server sentence-boundary streaming

Use autoMode: true with autoModeStrategy: "SENTENCE_BOUNDARY" to send text as your LLM produces it. The server buffers incoming fragments and detects sentence boundaries and complete break tags.

The tail is the remaining buffered text that has not reached a confirmed boundary. When your text source finishes, close the context to release this remaining text. If you need to release the tail and continue using the same context, you can call flushContext instead. Auto mode does not use the buffer delay timer.

See the runnable LLM token-streaming guide.

Stream incremental text

This example uses an already connected, authenticated WebSocket. Each ws.send sends one message. In your application, send each fragment as your LLM produces it.

ws.send(JSON.stringify({
  contextId: "reply-1",
  create: {
    voiceId: "Ashley",
    modelId: "inworld-tts-2",
    autoMode: true,
    autoModeStrategy: "SENTENCE_BOUNDARY"
  }
}));

for (const text of ["Hello from ", "sentence boundary streaming.", " Next we will finish this thought"]) {
  ws.send(JSON.stringify({contextId: "reply-1", sendText: {text}}));
}

// The LLM has finished: synthesize remaining text and close this context.
ws.send(JSON.stringify({contextId: "reply-1", closeContext: {}}));
// Keep receiving audio until the server sends contextClosed.

Here is how the buffer changes as those messages arrive:

A confirmed sentence is ready to be synthesized, but may be combined with other ready text while earlier audio is streaming.

Close a context in any mode

In all three modes, send closeContext when you have no more text for this context. It requests synthesis of any remaining buffered text and closes the context after the response finishes. You cannot send more text to that context after requesting close.

ws.send(JSON.stringify({contextId: "reply-1", closeContext: {}}));

Advanced: synthesis batches and timestamps

The server can combine ready sentences while earlier audio is streaming, including when a flush or close releases the remaining text. Do not expect one audio response or flushCompleted event per sendText message or detected sentence.

flushCompleted marks the end of a synthesis batch (a flush). Alignment timestamps reset for the next flush.

Markup and unfinished input

With SENTENCE_BOUNDARY, a supported markup tag can span multiple sendText messages:

First message:   "[whis"
Second message:  "per] Hello."
Combined text:   "[whisper] Hello."

• An incomplete tag stays buffered; the server does not send a partial tag to synthesis.
• Instructions stay with the speech that follows them. See Voice steering for model-specific instruction support.
• Finish every markup tag before flushing or closing. Incomplete markup at end of input returns INVALID_ARGUMENT.
• Ordinary text does not need final punctuation: an explicit flush or close releases it.

Text limits

For optional bufferCharThreshold and maxBufferDelayMs settings, see the API reference.

Have one large block of text? The Streaming API accepts up to 4,000 characters per request. For connection and concurrency limits, see Rate limits.

Timestamp transport strategy

When using timestamp alignment, you can choose how timestamps are delivered alongside audio using timestampTransportStrategy:

• SYNC (default): Each chunk contains both audio and timestamps together.
• ASYNC: Audio chunks arrive first, with timestamps following in separate trailing messages. This reduces time-to-first-audio.

See Timestamps for details on how each mode works.

Code examples

API reference

Next steps