API Reference

Copy Markdown

Open in Claude

Open in ChatGPT

Open in Cursor

---

Copy Markdown

View as Markdown

Live

Connect

live.connect()

Function

Create session

live.create(LiveCreateParams**kwargs) -> LiveCreateResponse

POST/live/sessions

ModelsExpand Collapse

AudioFormat

Audio encoding and sample rate for audio sent and received over a Live WebSocket connection. WebRTC and SIP negotiate their media format separately.

Literal["alloy", "ash", "ballad", 19 more]

A built-in voice available for Live speech.

class ClientConfig: …

Startup-only capabilities for an untrusted frontend attached to a unified WebRTC session. Trusted sideband connections are unaffected.

class ClientDelegation: …

Delegate tasks to your application. The Live session emits delegation events that your backend handles.

ClientEvent

Client events for Live. Initialize a primary WebSocket with session.start and wait for session.started. WebRTC creation already starts the session. Audio append is primary WebSocket-only. See the Live prompting guide before writing frontend instructions and delegation policies.

class CommentaryAppendEvent: …

Provide context the Live model can communicate to the user, optionally for an existing client delegation.

class CommentaryAppendedEvent: …

Returned when a session.commentary.append command is accepted into the Live session timeline. Acknowledges the added commentary without guaranteeing exact wording or completed audio playback.

class CustomVoice: …

class DataChannelConfig: …

Control which Live events an untrusted WebRTC frontend can send and receive over its data channel. These restrictions do not apply to trusted sideband connections.

class DelegationCreatedEvent: …

Returned when the Live model delegates work to your application or a Responses backend. Contains delegation metadata and the position on the session timeline where the work was delegated.

class Error: …

Details of an error encountered by the Live session, including the affected parameter or client command when available.

class ErrorEvent: …

Reports an error in the Live session, such as an invalid client command. Use error.client_event_id, when present, to identify the command that caused the error.

class ForkSessionConfig: …

Overrides for a stored session after connecting to the fork WebSocket. An empty object inherits the stored configuration; do not supply a new model. audio.format applies only to the new WebSocket connection. client overrides are only supported for WebRTC forks.

class ForkSessionStartEvent: …

Start a Live session after connecting to a stored session’s fork WebSocket. Send an empty session object to use the stored configuration.

class FunctionTool: …

A function tool available to the Responses backend when the Live model delegates a task.

class InfoEvent: …

An informational notice about the Live session, such as the event permissions applied to a frontend data channel.

InitialItem

A developer, user, or assistant message supplied as text history before the Live session starts.

class InputAudioAppendEvent: …

Send audio to a Live session over its primary WebSocket. WebRTC and SIP sessions send audio over their media transport.

class InputAudioMuteEvent: …

Mute audio input to the Live model without closing the session. The server acknowledges with session.input_audio.muted.

class InputAudioMutedEvent: …

Returned when a session.input_audio.mute command is accepted. Input audio is no longer sent to the model; sideband audio reflection continues.

class InputAudioUnmuteEvent: …

Resume audio input to a Live model after muting it. The server acknowledges with session.input_audio.unmuted.

class InputAudioUnmutedEvent: …

Returned when a session.input_audio.unmute command is accepted. Input audio is sent to the model again.

class InputTranscriptDeltaEvent: …

A transcript fragment for user input audio in the Live session. Accumulate fragments in delivery order; these events do not define complete turns or include a transcript-done event.

class InstructionsAppendEvent: …

Append instructions to the Live conversation while it is running, optionally associating them with an existing client delegation.

class InstructionsAppendedEvent: …

Returned when a session.instructions.append command is accepted into the Live session timeline. Acknowledges the appended instructions without guaranteeing that the model has acted on them.

class LiveCreateResponse: …

The created Live session identifier and WebRTC answer. Apply transport.sdp as the peer’s remote answer and wait for session.started on the data channel before sending commands.

class MediaSessionConfig: …

Startup configuration for a Live media session. Follow the Live prompting guide when writing frontend instructions and the backend prompt under delegation.responses.instructions.

class MediaSessionForkConfig: …

Optional overrides for a stored Live session. Omitted settings are inherited. The model, voice, frontend instructions, and prior conversation come from the stored session. WebRTC negotiates its audio format; audio.format is only supported on WebSocket forks.

class OutputAudioDeltaEvent: …

An audio chunk generated by the Live model. Decode and play primary WebSocket chunks in delivery order using the configured session audio format. Sideband connections receive reflected output audio with timestamps.

class OutputTranscriptDeltaEvent: …

A transcript fragment for assistant output audio in the Live session. Accumulate fragments in delivery order; these events do not define complete turns or include a transcript-done event.

class ResponseCreateEvent: …

Request a response from the Live session’s Responses backend, or continue a delegated response waiting for tool results. Requires Responses delegation.

class ResponseEvent: …

A streaming Responses API event from a backend delegated to by the Live session. Use the outer delegation_id to associate the nested stream with its Live delegation.

class ResponseItemCreateEvent: …

Add an input item to the Live session’s Responses backend. Requires Responses delegation; use response.create to request a response.

class ResponsesDelegationConfig: …

Model, prompt, and tool settings for tasks delegated by the Live session to a Responses backend.

class ResponsesDelegationUpdateConfig: …

Updates to the Responses backend of an existing Live session. Omitted settings retain their current values.

ServerEvent

Server events for Live. Response lifecycle events are wrapped inside response.event; dispatch the nested event by its full type and tolerate new response event types. Follow the Live prompting guide when designing the conversation and delegation policy.

class ServerEventSelector: …

A Live server event selector for the WebRTC frontend data channel.

class SessionCloseEvent: …

Request that the Live session close. The terminal session.closed event contains the close reason and final usage.

class SessionClosedEvent: …

Returned after the Live session finishes finalizing, with the close reason, final session snapshot, and cumulative audio usage. A connection closing without this event does not confirm successful finalization.

class SessionConfig: …

Initial configuration for a Live session, including its model, conversation instructions, audio, and delegated task handling.

class SessionResource: …

The resolved Live session configuration and server-assigned session metadata.

class SessionStartEvent: …

Start a Live session on a primary WebSocket. Send this event before other commands and wait for session.started.

class SessionStartedEvent: …

Returned when a Live session has started. Contains the resolved session configuration, including server defaults.

class SessionUpdateConfig: …

Changes to an active Live session. Only delegation backend settings can be updated after startup.

class SessionUpdateEvent: …

Update the delegation settings of an active Live session. The server acknowledges accepted changes with session.updated.

class SessionUpdatedEvent: …

Returned when a Live session update is accepted. Contains the resolved session configuration after the update.

class SessionUsage: …

Cumulative audio duration for a Live session. Values are totals for the session, not increments to sum across usage events.

class SessionUsageUpdatedEvent: …

Reports cumulative Live audio usage and, when available, the most recent context-window usage. Delegated Responses token usage is reported separately in response.event events.

class ThinkingAppendEvent: …

Provide silent reasoning or progress context to the Live model, optionally for an existing client delegation.

class ThinkingAppendedEvent: …

Returned when a session.thinking.append command is accepted into the Live session timeline. Acknowledges the added reasoning context without guaranteeing any spoken output.

LiveForks

Connect

live.forks.connect()

Function

ModelsExpand Collapse

ForkClientEvent

Client events for a Live fork WebSocket. First send session.start with an overrides object (which may be empty), then wait for session.started before sending other commands. The model and conversation are inherited from the stored session.

ForkServerEvent

Server events for Live. Response lifecycle events are wrapped inside response.event; dispatch the nested event by its full type and tolerate new response event types. Follow the Live prompting guide when designing the conversation and delegation policy.

LiveSessions

Accept call

live.sessions.accept(strsession_id, SessionAcceptParams**kwargs)

POST/live/sessions/{session_id}/accept

Download recording

live.sessions.download_recording(strsession_id) -> BinaryResponseContent

GET/live/sessions/{session_id}/content

Fork session

live.sessions.fork(strsession_id, SessionForkParams**kwargs) -> SessionForkResponse

POST/live/sessions/{session_id}/fork

Hang up session

live.sessions.hangup(strsession_id)

POST/live/sessions/{session_id}/hangup

Transfer call

live.sessions.refer(strsession_id, SessionReferParams**kwargs)

POST/live/sessions/{session_id}/refer

Reject call

live.sessions.reject(strsession_id, SessionRejectParams**kwargs)

POST/live/sessions/{session_id}/reject

ModelsExpand Collapse

class SessionForkResponse: …

The created Live session identifier and WebRTC answer. Apply transport.sdp as the peer’s remote answer and wait for session.started on the data channel before sending commands.

LiveSideband

Connect

live.sideband.connect(SidebandConnectParams**kwargs)

Function

ModelsExpand Collapse

ConnectClientEvent

Client events accepted by an attached Live sideband WebSocket. The session is already started; send audio over the primary connection.

ConnectServerEvent

Server events received by an attached Live sideband WebSocket. Audio deltas are delivered over the primary connection.