Skip to main content
The realtime WebSocket: the messages you send (text, flush, cancel), the audio and events you receive, and close codes.
Realtime generates speech over a WebSocket. Send text as it’s written, get audio frames back. One socket carries up to 8 replies. For a complete file in one request, use Batch.

Open a Stream

Open a WebSocket. Send Authorization: Basic base64(<auth_id>:<auth_token>) on the upgrade request.

Arguments

No query parameters: one returns 422 invalid_request naming it, and the socket doesn’t open. Options go in the first text message of each reply. A plain GET on this URL, without a WebSocket upgrade, returns 426 with an Upgrade: websocket header.

Messages you send

All client messages are JSON text frames, up to 64 KiB.

text

string
required
text
string
required
Your ID for this reply. A new ID opens a new reply (max 8 open per socket). Each ID can be used once per connection: opening a reply with an ID already used on the socket returns an error event with invalid_request and param: context_id. Frames sent for a reply that has ended are ignored.
string
required
Text to add to the reply. Up to 5,000 characters per message.
boolean
default:"false"
true on the last text of the reply.
string
Required on the first message of a context.
boolean
default:"false"
Send timestamps events with character timings.
The first message of a context also accepts every batch option: language, output_format, pace, volume, pronunciations, lexicon_id, continuation, seed. Options are fixed when the reply opens. Later text messages for the same context take only type, context_id, text and finish. Any other field, such as voice_id or pace, returns an error event with invalid_request and param naming the field.

flush

Speak all text received so far for c1, including a sentence that hasn’t ended yet. The reply stays open for more text.
string
required
The reply to flush. A context_id that isn’t open returns an error event with invalid_request.
string
Your ID for this flush. When you send one, you get a flush_done event with the same flush_id. Without it, no flush_done is sent.

cancel

Stop c1 at once. Leave out context_id to cancel every open reply. Each canceled reply ends with a done event whose reason is cancelled. A context_id that isn’t open is ignored.

Messages you receive

Audio (binary)

Audio is in the output_format of that context.

timestamps

Sent when timestamps is on, once per sentence.
array
The characters of the text, one per entry, including spaces and punctuation.
array
When each character starts, in milliseconds from the start of the reply’s audio. Times keep counting across events: the next sentence’s first character starts where this one ends.
array
How long each character lasts, in milliseconds. Several characters can share one start time with a duration of 0.

flush_done

Sent after a flush that carried a flush_id, once the text up to that flush has been generated.

done

Sent once per reply when it ends: after its last audio frame, or when you cancel it.
string
complete when the reply was spoken in full, or cancelled after a cancel.
string
The text as spoken. For a canceled reply, only the part spoken before the cancel.
integer
Billed characters: all the text the reply received, including text not spoken because of a cancel.
integer
Characters spoken before the reply ended. Lower than characters when you cancel.
number
Seconds of audio sent for the reply.

warning

A non-fatal problem.

error

An error event doesn’t close the socket. It affects only the reply named in context_id, and other replies keep playing. context_id is left out when the error isn’t about one reply, for example a frame that isn’t a JSON object or an unknown type. See Errors for codes.

Close codes

A client that stops reading for 30 s is dropped.