Overview

REST and WebSocket reference for the realtime voice API. All routes are prefixed with /v1/realtime. For a guided walkthrough, see Speech to Speech.

WebSocket connection

WebSocket endpoint

wss://api.boson.ai/v1/realtime

Establishes a realtime voice session. The connection upgrades from HTTP GET (status 101) and then exchanges JSON events for session configuration, audio streaming, and responses.Query parameters

Parameter	Purpose
`model`	Optional; the session model (`higgs-realtime`). Used when `session.update` omits `session.model`; an explicit `session.model` overrides it.

Subprotocols

Value	Purpose
`realtime`	Optional; echoed back as the negotiated subprotocol if offered.
`bai-client-secret.<key>`	Client-side auth with an ephemeral key.

AuthenticationEither an Authorization: Bearer <API_KEY> header (server-side), or an ephemeral key (bai-eph-…) passed via subprotocol (client-side). Ephemeral keys are minted with POST /v1/realtime/client_secrets.WebSocket close codes

Code	Meaning
`1000`	Normal closure — including session-limit closes (idle timeout, max session duration), which are preceded by their server event and carry the reason in the close frame.
`1013`	Max concurrency exceeded — retry later.
`3000`	Invalid API key or invalid/expired ephemeral key.
`4009`	Session already active (duplicate).
`4429`	Billing entitlement refused (quota exhausted, spending cap, contract ended). Always preceded by an `error` event carrying the upstream message.

WebRTC

WebRTC transport support is in progress. WebSocket is the supported transport today.

Realtime API

Text-to-Speech API

Avatar API

WebSocket connection

WebRTC

​WebSocket connection

​WebRTC

WebSocket connection

WebRTC