{
"type": "start",
"request": {
"model": "higgs-tts-3",
"voice": "default",
"normalize": true,
"language": "eng"
}
}{
"type": "text",
"text": "Sure thing. I can move "
}{
"type": "flush"
}{
"type": "stop"
}{
"type": "cancel"
}{
"type": "audio",
"data": "<base64-encoded PCM audio>"
}{
"type": "timestamps",
"entries": [
{
"index": 0,
"text": "Hi",
"start_ms": 0,
"end_ms": 240,
"start_idx": 0,
"end_idx": 2,
"normalized": []
},
{
"index": 1,
"text": "there",
"start_ms": 240,
"end_ms": null,
"start_idx": 3,
"end_idx": 8,
"normalized": []
}
]
}{
"type": "flushed"
}{
"type": "cancelled"
}{
"type": "finish"
}{
"type": "error",
"code": "session_not_started",
"message": "the first message must be start"
}Speech WebSocket
Send text as it arrives and receive PCM speech while you are still sending, over one WebSocket connection.
type field, processed in the order they are sent. Ignore event types you don’t recognize: new ones may be added.
For a complete client, errors, close codes, and limits, see Streaming TTS.
/v1/realtime). Its events, error shape, and close codes are different.{
"type": "start",
"request": {
"model": "higgs-tts-3",
"voice": "default",
"normalize": true,
"language": "eng"
}
}{
"type": "text",
"text": "Sure thing. I can move "
}{
"type": "flush"
}{
"type": "stop"
}{
"type": "cancel"
}{
"type": "audio",
"data": "<base64-encoded PCM audio>"
}{
"type": "timestamps",
"entries": [
{
"index": 0,
"text": "Hi",
"start_ms": 0,
"end_ms": 240,
"start_idx": 0,
"end_idx": 2,
"normalized": []
},
{
"index": 1,
"text": "there",
"start_ms": 240,
"end_ms": null,
"start_idx": 3,
"end_idx": 8,
"normalized": []
}
]
}{
"type": "flushed"
}{
"type": "cancelled"
}{
"type": "finish"
}{
"type": "error",
"code": "session_not_started",
"message": "the first message must be start"
}Your Boson API key, sent as Authorization: Bearer <API key> on the WebSocket handshake. An invalid key doesn't fail the handshake: the connection opens, then the server sends an error event and closes with 1008. See Authentication.
Opens the session with its speech settings. It must be the first message, and it is sent once. An accepted start gets no reply: the next thing the server sends is audio. A refused start gets an error, and the connection closes with 1008. A second start gets an error (session_already_started), and the session goes on.
Adds text to speak. It can be sent at any time, even while audio is playing, and can be any size, from a single token to a paragraph. Text may wait for more input before it is spoken. flush or stop speaks everything received so far.
Ends a turn and speaks everything received so far. Once that audio has been sent, the server sends flushed. The session stays open for the next turn. Send it at the end of every reply, since text without a natural ending waits for more text.
Ends the session. The server speaks whatever is left, sends finish, and closes the connection with 1000. Any message sent after stop gets an error (session_stopping), and the stop still completes. Closing the connection yourself without stop drops any text not yet spoken.
Drops all text not yet spoken, and any pending flush, and stops the audio being generated, for example when the user interrupts. The server answers with cancelled. No audio for the dropped text is sent after it. The session stays open.
A piece of speech. Decode the data of every audio event and join them in order to get the full audio: the same PCM as a streamed POST /v1/audio/speech response.
With timestamps: true in start.request: the timing of the tokens spoken so far, sent after the audio event they came with. Entries count per turn: a turn is the text sent before a flush, and the next turn starts after each flush or cancel.
All audio for the turn ended by a flush has been sent.
The cancel is done. Every audio event after it belongs to text sent after the cancel.
Everything has been spoken after a stop. The server closes the connection next, with code 1000.
Something went wrong. Depending on the code, either the session goes on, or the server closes the connection right after this event. See Errors for every code and close code.