WebSocket reference

Connection

wss://api.waterr.ai/v1/realtime?model=ori-realtime-1.5


Subprotocol	`realtime` (recommended)
Auth (server-side)	`Authorization: Bearer wai_<your_key>` header
Auth (browser)	`?token=wai_<your_key>` query parameter
Model	`?model=ori-realtime-1.5` (optional — it’s the only model, and the default)

All events are JSON text frames. Binary frames are rejected.

Client → server events

Only two event types are accepted; anything else returns an error event (the connection stays open).

`session.update`

Send once after connecting, before audio. Can be sent again mid-session to change instructions.

{
  "type": "session.update",
  "session": {
    "voice": "anna",
    "instructions": {
      "type": "constant",
      "text": "You are a friendly, concise assistant.",
      "language": "en"
    }
  }
}

string

A preset voice id (see voices). Unknown values fall back to the default voice.

string

The system prompt — persona, task, tone.

string

BCP-47-style language hint. en is the supported value; others are experimental.

`input_audio_buffer.append`

Stream microphone audio continuously — including silence. The turn engine uses the audio stream itself to detect when the user has finished speaking.

{ "type": "input_audio_buffer.append", "audio": "<base64 Opus>" }

string

required

Base64-encoded Opus, 24 kHz mono. See audio.

Server → client events

Event	Payload	Meaning
`session.updated`	—	Session config confirmed.
`input_audio_buffer.speech_started`	—	The user started speaking. If the model was talking, it is being interrupted server-side — stop playback now for responsive barge-in.
`input_audio_buffer.speech_stopped`	—	The turn engine judged the user’s turn complete.
`conversation.item.input_audio_transcription.delta`	`{"delta": "word"}`	Live transcript of the user, word by word, naturally spaced.
`response.created`	—	The model started composing a reply.
`response.text.delta`	`{"delta": "word"}`	The model’s speech as streaming text, naturally spaced.
`response.text.done`	`{"text": "..."}`	Full text of the reply.
`response.audio.delta`	`{"delta": "<base64 Opus>"}`	Reply audio — decode and play as it arrives.
`response.audio.done`	—	Audio for this response finished. May fire between phrases within one reply, and is the practical end-of-turn signal.
`response.done`	—	The model’s turn is complete. Not guaranteed on every turn — treat “`response.audio.done` followed by quiet” as the turn boundary rather than waiting on this event.
`ori.interrupted_by_vad`	—	The user barged in and the model’s response was cut off server-side. Stop playback immediately.
`ori.*` (other)	varies	Experimental system events. Safe to ignore; names and payloads may change during the preview.
`error`	see below	Something went wrong; connection may close after.

Errors

Error events use one shape:

{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "code": "preview_access_required",
    "message": "..."
  }
}

Fatal errors are followed by a WebSocket close with a matching code:

Close code	Error code	Meaning
— (HTTP 401 at handshake)	—	Missing, malformed, revoked, or expired API key.
`4003`	`preview_access_required`	Key is valid but not enrolled in the research preview — request access.
`4000`	`model_not_found`	Unknown `?model=` value.
`4008`	`concurrent_session_limit`	Your key already has its maximum concurrent sessions open.
`4008`	`capacity_exceeded`	Preview capacity is fully utilized — retry with backoff.
`4009`	`session_time_limit`	The session hit the maximum duration — reconnect for a fresh session.
`1013`	`service_unavailable` / `upstream_unavailable`	The model service is down or restarting — retry shortly.

Non-fatal errors (unsupported_event, invalid_json, invalid_frame) leave the connection open.

Limits

Limit	Preview value
Concurrent sessions per key	2
Max session duration	30 minutes
Pricing	Free during preview (sessions are duration-metered)

Session semantics

Sessions are ephemeral. A reconnect is a brand-new conversation; the model does not remember previous sessions. Keep your own transcript (response.text.done + user transcription events) if you need continuity.
Interruption is server-side. There is no response.cancel. When input_audio_buffer.speech_started arrives while audio is playing, cut your playback — the model has already stopped generating.
Keep audio flowing. Send silence when the user isn’t speaking. Gaps in the stream degrade turn detection.
Heartbeats. The server pings every 30 seconds; standard WebSocket clients answer automatically. No action needed.

ORI-Realtime 1.5

ORI Utter

WebSocket reference

Connection

Client → server events

`session.update`

`input_audio_buffer.append`

Server → client events

Errors

Limits

Session semantics

​Connection

​Client → server events

​session.update

​input_audio_buffer.append

​Server → client events

​Errors

​Limits

​Session semantics

Connection

Client → server events

`session.update`

`input_audio_buffer.append`

Server → client events

Errors

Limits

Session semantics