Live API 现身 OpenAI SDK：gpt-live-1、WebRTC/WebSocket 双通道与 SIP 通话控制解读

2026-09-10 傍晚，OpenAI 两个官方 SDK 又发了一对功能版本：openai-python v3.12.0（17:28 UTC）与 openai-node v7.14.0（17:29 UTC），release notes 的 Features 一栏写着同一句话——"Add Live API"。这个版本把一个全新的实时会话接口写进了两包：client.live 命名空间，入口 /live/sessions，自带 WebRTC 与 WebSocket 两条接入通道、一整套 SIP 语义的通话控制端点，以及一个此前从未出现过的模型字面量 gpt-live-1。

本文的写法沿用本站 SDK 情报文的纪律：只陈述能在 SDK 源码里逐字指出的东西。所有引用来自 2026-09-11 当日重抓的 GitHub release notes 与 v3.12.0 / v3.13.0 tag 源码（清单见文末 officialReferences）；OpenAI 官方文档域当日对本站 403，涉及官方公告侧的状态一律日期锚定、不做超出核验的断言。

1. 概述：这批更新能确认什么

Live API 是 2026-09-10 起 OpenAI 官方 SDK 类型层出现的实时会话接口，覆盖四个能力面：

对"❓"这一行，本文统一不推断。SDK 类型是自动生成的（源码头注释写着 generated from our OpenAPI spec），它证明"spec 里有"，不证明"已对外提供服务"。

2. 首次出现核验：上一版确实没有

按本站的"首次出现必须对照上一版本 tag"纪律，2026-09-11 用 GitHub tag 树做了对照：

• openai-python v3.11.0 树里没有任何 resources/live 路径，也没有 types/live 目录；v3.12.0 起两者出现
• openai-node v7.13.0 树里没有 src/resources/live；v7.14.0 起出现（live.ts + live/ 目录）
• v3.11.0 的 ChatModel 枚举里没有 gpt-live 任何字样；gpt-6-astra 当时已在（2026-09-03 落地）

一个前置信号值得记录：v3.11.0 里已经存在 types/webhooks/live_call_incoming_webhook_event.py——"来电"事件的 webhook 类型先于 Live 资源面一步出现。这说明 Live API 的类型落地是分批的，盯 webhook 目录有时能比盯资源目录更早看到信号。

3. 两条接入通道：WebRTC 建会话，WebSocket 直连

3.1 WebRTC：POST /live/sessions

client.live.create() 对应 POST /live/sessions，参数结构（LiveCreateParams）：

class LiveCreateParams(TypedDict, total=False):
    session: Required[MediaSessionConfigParam]   # Live 会话的启动配置
    transport: Required[Transport]               # WebRTC 传输

class Transport(TypedDict, total=False):
    sdp: Required[str]         # WebRTC 连接的 SDP 消息
    type: Required[Literal["webrtc"]]   # 传输类型，SDK 注明 Always webrtc

返回 LiveCreateResponse 的类注释给了完整握手语义：把 transport.sdp 设为 peer 的 remote answer，然后在 data channel 上等 session.started 事件，之后才发命令。返回的 session.id 是后续所有控制端点的句柄，SDK 原文特别提醒"保持原样、包括前缀"。

from openai import OpenAI

client = OpenAI()

resp = client.live.create(
    session={"model": "gpt-live-1", "instructions": "…"},  # 启动配置
    transport={"type": "webrtc", "sdp": local_offer},      # 浏览器侧生成的 SDP offer
)
print(resp.session.id)        # 会话 ID，用于 accept/fork/录音等控制端点
print(resp.transport.sdp)     # SDP answer，设为 remote answer

（代码为 SDK 类型核对版：字段与类型逐项对照 v3.13.0 的 LiveCreateParams，未在真实 key 下实跑。）

3.2 WebSocket：client.live.connect()

connect() 不带查询参数直接建 WebSocket 连接（SDK 内部把 base URL 换成 ws scheme 拼到 /live/sessions），返回 LiveConnectionManager。docstring 原文的时序约定：先发 session.start（带模型与会话配置），等 session.started 回来再继续。连接管理器自带重连参数（默认 max_retries=5、initial_delay=0.5、max_delay=8.0）——实时语音场景对断线重连的刚需，SDK 在类型层直接内置了。

4. SIP 通话控制：accept / reject / hangup / refer

sessions 子资源的六个端点里，四个的 docstring 明确写着 SIP 语义（以下均为 SDK 原文转译，引文可逐字对上）：

这套端点组合（接听 / 拒接 / 挂断 / 转接 + 来电 webhook）指向的是电话呼入场景：你的后端收到 live.call.incoming webhook（v3.11.0 已有的 webhook 事件，事件名字面量经类型文件核对）后，决定 accept 还是 reject，通话中可以 refer 转接到别的坐席或号码。这与本站此前拆过的 Realtime API 电话客服用法（《Realtime Voice Agent 实战：电话客服 / 语音助手场景的 Realtime API + function calling》）在场景上重叠——但 SDK 类型层没有任何"Live 取代 Realtime"的表述，两者在 v3.13.0 里是并存的两个资源面，选型以官方公告为准。

另外两个端点：

• fork：POST /live/sessions/{id}/fork——把已存储的 Live 会话分叉到新的 WebRTC 连接；transport 传新连接的 SDP offer，session 覆盖项可省略（省略或空对象 = 继承原会话配置）。forks 子资源另有 WebSocket 版 forks.connect()，SDK 原文注明"模型继承"（The model is inherited）。
• download_recording：GET /live/sessions/{id}/content——下载开启了存储的会话内容；SDK 原文要求用"会话启动且存储开启时返回的 session ID"。

sideband 子资源提供 attach（附着到既有 Live 会话，走独立的 WebSocket 连接）——类型注释的用意是给旁路观察/控制通道留口子，例如主连接跑音频、sideband 跑监听与控制。

5. gpt-live-1：只出现在会话配置里的模型字面量

会话配置类型（types/live/session_config.py）里 model 字段的定义是：

model: Union[str, Literal["gpt-live-1"]]

注意两个边界：

1. 它没有进入 ChatModel 枚举。v3.13.0 的枚举首位仍是 gpt-6-astra，其后是 gpt-5.6-sol / terra / luna（2026-09-11 核对）。gpt-6-astra 当日是"进了枚举但未官宣"；gpt-live-1 连枚举都没进，只挂在 Live 会话配置下——信息量比 gpt-6-astra 更少。
2. 类型层没有它的任何定价、能力、上下文窗口描述。命名里的 live 与 2026-08-26 转写迁移公告里的 gpt-live-transcribe 前缀相同，但两者是不同的 ID，SDK 里没有把它们关联起来的任何注释——不推断。

已官宣的语音旗舰仍是 GPT-Realtime-2.1（2026-07-06 发布）；gpt-live-1 是否与之相关、是否是下一代语音模型，截至 2026-09-11 均无官方信息。

6. 事件模型与配套辅助库

types/live 目录定义了完整的双向事件类型（ClientEvent / ServerEvent 两族）。事件名（type 字面量，2026-09-11 逐文件核对）统一带 session. 前缀：

• 会话生命周期：session.start / session.started、session.update / session.updated、session.close
• 音频：session.input_audio.append、session.input_audio.mute / session.input_audio.muted、session.output_audio.delta
• 生成过程：session.instructions.append / session.instructions.appended、session.commentary.append、session.thinking.append、response.create、session.usage.updated、session.delegation.created、error
• 传输与电话（服务端事件）：transport.ringing、transport.answered、transport.dtmf.received、transport.dtmf.send、transport.failed、call_error——ringing / answered / DTMF（双音多频按键）这组事件把第 4 节的 SIP 语义又坐实了一层

配套的 openai.lib.live 辅助库带了 transcript grouper（转写分组器，把增量 delta 事件聚成可读段落）与 listeners 工具，examples 目录有 audio_transcript.py / transcript_grouper.py 两个示例。这套"事件 + 分组器"的组合是 Realtime API 时代踩过坑的方向（增量转写流需要客户端自己聚合），SDK 这次直接内置了参考实现。

7. 常见错误与排查

• 把 SDK 资源面出现当成开放调用：client.live 存在 ≠ Live API 已 GA。是否可用、哪个项目能用，以官方 changelog / 文档为准；截至 2026-09-11 官方文档域对本站 403，本站无法核对。
• 生产代码硬编码 gpt-live-1：未经官宣的模型字面量随时可能变化。要实验，放 feature flag 后面并处理 model_not_found 类错误。
• accept 时传了 audio.format：SDK 原文明确 SIP 媒体格式是协商出来的，accept 场景省略 audio.format——照抄 create 场景的音频配置会在协商语义下出错。
• reject 忘传状态码：status_code 是必填，且取值范围 300-699（SIP 语义），传 200 之类的值类型层就过不去。
• 对 Live 与 Realtime 做非此即彼的架构押注：两个资源面并存、官方无定位说明。现有 Realtime 管线（GPT-Realtime-2.1）按 world 记录仍是现役方案，不要因为新资源面出现就启动迁移。

8. 下一步

• 《Realtime Voice 完全指南：gpt-realtime 与 Voice Mode》：现役语音旗舰 GPT-Realtime-2.1 的完整机制——理解 Live API 前先把这条基线搞清楚。
• 《Agents API 现身 OpenAI SDK（beta）：/agents CRUD、environments、sessions 与 vaults 全景》：同日晚间（19:37 UTC）两包落地的另一个全新 API 面。
• 《gpt-6-astra 现身 OpenAI SDK：ChatModel 枚举新模型 ID 与 Safety Alerts API 解读》：09-03 那批 SDK 类型层情报的方法论与边界处理，本文沿用同一纪律。
• 《openai-python 3.9 / 3.10 与 openai-node 7.11 / 7.12 更新解读：prompt cache 诊断、API key 过期与 GPT Image 2.5》：本批之前两天的六版 SDK 更新解读，含 v3.12.0 / v3.13.0 的版本总表。
• 《OpenAI 模型更新日志（2026 持续更新）》：全时间线视角，Live API 的官宣（若发生）会在这里跟进。