API Reference

Client events

Commands sent from your WebSocket client to the gateway.

Event	Required fields	Contract
`session.update`	`event_id, session`	Update supported instructions, voice, turn detection, modalities, and public audio format.
`input_audio_buffer.append`	`event_id, audio`	Append one aligned base64 raw PCM16LE frame. Maximum public frame size is 98,304 bytes.
`input_audio_buffer.commit`	`event_id`	Commit a manual turn boundary after manual turn detection has been negotiated.
`input_audio_buffer.clear`	`event_id`	Discard pending input audio that has not been committed.
`response.create`	`event_id`	Request a response when using manual response control.
`response.cancel`	`event_id`	Cancel the current response and suppress stale output after an interruption.

Server events

Lifecycle, VAD, response output, usage, and bounded protocol errors.

Event	Required fields	Contract
`session.created`	`event_id, session`	First event after a successful connection; contains the public session resource.
`conversation.created`	`event_id, conversation_id`	Conversation scope is ready for input audio.
`session.updated`	`event_id, session`	Acknowledges a supported session update.
`input_audio_buffer.speech_started`	`event_id`	Server VAD detected the start of a speech turn.
`input_audio_buffer.speech_stopped`	`event_id`	Server VAD detected the end of a speech turn.
`input_audio_buffer.committed`	`event_id`	Acknowledges a manual input turn boundary.
`input_audio_buffer.cleared`	`event_id`	Acknowledges that pending input audio was discarded.
`response.created`	`event_id, response_id`	A response generation has started.
`response.output_item.added`	`event_id, response_id, item_id`	A response output item has been added before its audio content arrives.
`response.output_audio.delta`	`event_id, response_id, item_id, output_index, content_index, delta`	One base64 output audio delta to play immediately.
`response.output_audio.done`	`event_id, response_id, item_id`	All audio deltas for the current output content are complete.
`response.output_item.done`	`event_id, response_id, item_id`	The response output item is complete.
`response.done`terminal	`event_id, response_id, usage`	Terminal response event. Usage is normalized for settlement and support.
`error`	`event_id, error`	A bounded protocol error using the same logical error shape as HTTP.

Server events are emitted by the gateway. Clients should not synthesize lifecycle events.

Normal response order

Audio deltas can be zero or more; response.done is the terminal response signal.

session.createdconversation.createdsession.updatedresponse.createdresponse.output_item.addedresponse.output_audio.delta × Nresponse.output_audio.doneresponse.output_item.doneresponse.done

{
  "type": "response.output_audio.delta",
  "event_id": "evt_EXAMPLE",
  "response_id": "resp_EXAMPLE",
  "item_id": "item_EXAMPLE",
  "output_index": 0,
  "content_index": 0,
  "delta": "BASE64_PCM16LE_OUTPUT"
}

Audio event rules

The audio field is base64 of raw PCM16LE, never a WAV or provider-specific frame.

Send 20–100 ms frames in normal clients; each frame must be aligned to two-byte samples.
Play each response.output_audio.delta immediately instead of waiting for the whole response.
Ignore or suppress stale output after a response generation has been cancelled.
Use response.done.usage as the normalized terminal usage record.