Connection keepalive

Overview

In real-time Text-to-Speech, there may be periods when you are not sending any text — for example, while waiting on an upstream LLM, between turns in a conversational agent, or between streams on the same connection.

If the WebSocket stays idle for too long, the server will close the connection as inactive. To prevent this, send a keepalive control message:

{"keep_alive": true}

This is a lightweight signal that tells the server the client is still present and the connection should stay open.

When to use

Send a keepalive message whenever:

• You are not sending text for an extended period.
• You want to keep the WebSocket connection open between streams so you can start a new stream_id without reconnecting.

This ensures that:

• The connection stays open across idle gaps.
• You avoid the latency cost of reopening a WebSocket for the next stream.

You can also send them on a fixed interval even while sending text.

Key points

• The keepalive message does not trigger speech generation and has no server-side effect other than maintaining the connection.
• Send at least once every 20–30 seconds when the connection is idle to prevent timeouts.
• Keepalive applies to the whole WebSocket connection, not to a specific stream_id, one message keeps every stream on the connection alive.
• Keepalive works only after you start your first stream. Before that, send your config message with a valid API key within about 10 seconds of connecting, or the connection is closed.

Keepalive does not keep an unused connection open forever

Keepalive prevents idle timeouts, but a connection that generates no audio for more than 3 minutes is closed even if keepalives are still flowing. Keepalives keep the socket from looking idle, they do not count as work.

To keep a connection open across long gaps, generate audio at least once within every 3-minute window. If your application may go longer than that without speaking, let the connection close and open a new one when you have text to send.