AI 原生开放教材

外观

OpenAI API 参考（字段级）官方文档·英文原文 ↗原件 ↓仓库 ↗

Sideband WebSocket ​

For the complete documentation index, see llms.txt. Markdown versions of documentation pages are available by appending .md to the page URL.

Attach your backend server to an existing Live session with your OpenAI API key. For example, when your frontend connects over WebRTC, use this WebSocket to handle events and control the session from your backend.

WS /v1/live/sessions/\{session_id\}/attach

Connection ​

wss://api.openai.com/v1/live/sessions/\{session_id\}/attach

Authenticate from your backend with your OpenAI API key in the Authorization: Bearer $OPENAI_API_KEY header. Keep the key on your server.

session_id (required path parameter): The ID of the existing session to attach to.

Attaching does not create a session or replay earlier events. Audio stays on the primary connection. Do not send session.start or session.input_audio.append on this WebSocket.

Inputs ​

For a session using Responses delegation, update its tool choice. The delegation type cannot change. There is no required first message after attaching.

Example client event: session.update ​

json
{
  "type": "session.update",
  "event_id": "update_1",
  "session": {
    "delegation": {
      "type": "responses",
      "responses": {
        "tool_choice": "required"
      }
    }
  }
}

All client events

Outputs ​

A configuration update is acknowledged with session.updated. You also receive subsequent session events; attaching alone does not trigger this event.

Example server event · excerpt: session.updated ​

json
{
  "type": "session.updated",
  "event_id": "event_updated_1",
  "client_event_id": "update_1",
  "session": {
    "id": "live_123",
    "expires_at": 1788307200,
    "status": "active",
    "model": "gpt-live-1"
  }
}

All server events

Need to start a session and stream audio from your backend? Use a primary WebSocket.

Client events ​

session.update ​

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

本篇目录 ​