OpenAI 分叉 Live 会话

分叉会话

post /live/sessions/{session_id}/fork

将已保存的 Live 会话分叉到新的 WebRTC 连接。

路径参数

• session_id: string

要分叉的已保存 Live 会话的 ID。

请求体参数

内容类型：application/json

• transport: object { sdp, type }

WebRTC 传输对象，包含用于连接分叉会话的新连接的 SDP 提议。

• sdp: string

WebRTC 连接的会话描述协议（SDP）消息。

minLength: 1

• type: "webrtc"

Live 会话使用的传输方式，固定为 webrtc。

• "webrtc"

• session: optional MediaSessionForkConfig

新 Live 会话的可选配置覆盖项。省略此对象或发送空对象时，继承已保存会话的设置。

• client: optional ClientConfig

仅在启动时设置的能力权限，适用于连接到统一 WebRTC 会话的不可信前端，不影响可信的旁路连接。

• data_channel: DataChannelConfig

WebRTC 前端数据通道的客户端与服务端事件权限。

• allowed_client_events: optional "all" or array of string

前端数据通道可发送的客户端事件类型。使用 'all' 允许所有客户端事件，空数组表示全部禁止。省略时保留原有的全部允许行为。

• "all"

• "all"

• array of string

maxItems: 256

• allowed_server_events: optional "all" or array of ServerEventSelector

可发送到前端数据通道的服务端事件。使用 'all' 允许所有服务端事件，空数组表示全部禁止。省略时保留原有的全部允许行为。Responses 事件通过包含 type 'response.event' 和 response_event 选择器的对象指定。

• "all"

• "all"

• array of ServerEventSelector

maxItems: 256

• type: string

外层 Live 服务端事件类型。对于 Responses 事件，使用 'response.event'。

minLength: 1, maxLength: 256

• response_event: optional string

内嵌的 Responses 事件类型。type 为 'response.event' 时必填；其他事件类型禁止使用此字段。

minLength: 1, maxLength: 256

• delegation: optional object { type, acknowledgement_delay_ms, responses }

更新现有 Live 会话的 Responses 后端，同时保留任务委派的处理方。

• type: "responses" (default: "responses")

委派任务的处理方。由 Responses API 处理任务时固定为 responses。

• "responses"

• acknowledgement_delay_ms: optional integer

从委派任务发出到请求自动语音确认的等待时长，单位为毫秒。模型仍可能在等待结束前发言。向会话追加任何说明（commentary）或思考（thinking）都会取消所有待处理的确认，包括其他委派任务的确认。Decisions 会话默认为 400，其他会话默认为 0，即立即请求。更新会话时省略此项会保留当前值；更新仅作用于后续委派。

minimum: 0, maximum: 800

• responses: optional ResponsesDelegationUpdateConfig

要更新的 Responses 后端设置。省略的设置保持原值。

• instructions: optional string or null

交给被委派的 Responses 模型的指令，与 Live 指令分开设置。参阅后端提示词。

• max_output_tokens: optional integer or null

每次委派响应的最大输出词元数。

minimum: 16

• model: optional string

后续委派请求使用的 Responses 后端模型。省略时保留当前后端模型。

• parallel_tool_calls: optional boolean or null

被委派的 Responses 模型能否在单次响应中请求多个工具调用。

• reasoning: optional object { effort, summary } or null

传给每次委派 Responses 请求的推理配置。

• effort: optional "none" or "minimal" or "low" or 3 more or null

被委派的 Responses 模型使用的推理强度。支持的值取决于后端模型。

• "none"

• "minimal"

• "low"

• "medium"

• "high"

• "xhigh"

• summary: optional "concise" or "detailed" or "auto" or null

向被委派的 Responses 模型请求的推理摘要类型，须模型支持。

• "concise"

• "detailed"

• "auto"

• service_tier: optional "auto" or "default" or "fast_tier_temp_pilot" or 3 more or null

委派 Responses 请求使用的服务层级。

• "auto"

• "default"

• "fast_tier_temp_pilot"

• "flex"

• "priority"

• "ultrafast"

• text: optional object { verbosity } or null

传给每次委派 Responses 请求的文本生成配置。

• verbosity: optional "low" or "medium" or "high" or null

Responses 后端生成文本的详细程度，此项不配置 Live 模型的口头表达方式。

• "low"

• "medium"

• "high"

• tool_choice: optional "auto" or "none" or "required" or Function { name, type } or Mcp { server_label, type, name } or 11 more

控制 Responses 后端在处理 Live 模型委派的任务时使用哪个工具。

• LiveToolChoiceEnum = "auto" or "none" or "required"

• "auto"

• "none"

• "required"

• Function object { name, type }

• name: string

要调用的函数工具名称。

• type: "function" (default: "function")

要调用的工具，固定为 function。

• "function"

• Mcp object { server_label, type, name }

• server_label: string

要调用的 MCP 服务器标签。

• type: "mcp" (default: "mcp")

要调用的工具，固定为 mcp。

• "mcp"

• name: optional string or null

要调用的 MCP 工具名称。省略时，服务器可选择默认工具。

• FileSearch object { type }

• type: "file_search" (default: "file_search")

要调用的工具，固定为 file_search。

• "file_search"

• WebSearch object { type }

• type: "web_search" (default: "web_search")

要调用的工具，固定为 web_search。

• "web_search"

• WebSearchPreview object { type }

• type: "web_search_preview" (default: "web_search_preview")

要调用的工具，固定为 web_search_preview。

• "web_search_preview"

• ImageGeneration object { type }

• type: "image_generation" (default: "image_generation")

要调用的工具，固定为 image_generation。

• "image_generation"

• Computer object { type }

• type: "computer" (default: "computer")

要调用的工具，固定为 computer。

• "computer"

• CodeInterpreter object { type }

• type: "code_interpreter" (default: "code_interpreter")

要调用的工具，固定为 code_interpreter。

• "code_interpreter"

• ProgrammaticToolCalling object { type }

• type: "programmatic_tool_calling" (default: "programmatic_tool_calling")

要调用的工具，固定为 programmatic_tool_calling。

• "programmatic_tool_calling"

• Shell object { type }

需要调用工具时，强制模型调用 shell 工具。

• type: "shell" (default: "shell")

要调用的工具，固定为 shell。

• "shell"

• Custom object { name, type }

• name: string

要调用的自定义工具名称。

• type: "custom" (default: "custom")

要调用的工具，固定为 custom。

• "custom"

• ApplyPatch object { type }

执行工具调用时，强制模型调用 apply_patch 工具。

• type: "apply_patch" (default: "apply_patch")

要调用的工具，固定为 apply_patch。

• "apply_patch"

• LiveAllowedToolsChoiceParam object { tools, type, mode }

• tools: array of Function { name, type } or Mcp { server_label, type, name } or FileSearch { type } or 9 more

被委派的 Responses 模型可以调用的工具。

minItems: 1, maxItems: 128

• Function object { name, type }

• name: string

要调用的函数工具名称。

• type: "function" (default: "function")

要调用的工具，固定为 function。

• "function"

• Mcp object { server_label, type, name }

• server_label: string

要调用的 MCP 服务器标签。

• type: "mcp" (default: "mcp")

要调用的工具，固定为 mcp。

• "mcp"

• name: optional string or null

要调用的 MCP 工具名称。省略时，服务器可选择默认工具。

• FileSearch object { type }

• type: "file_search" (default: "file_search")

要调用的工具，固定为 file_search。

• "file_search"

• WebSearch object { type }

• type: "web_search" (default: "web_search")

要调用的工具，固定为 web_search。

• "web_search"

• WebSearchPreview object { type }

• type: "web_search_preview" (default: "web_search_preview")

要调用的工具，固定为 web_search_preview。

• "web_search_preview"

• ImageGeneration object { type }

• type: "image_generation" (default: "image_generation")

要调用的工具，固定为 image_generation。

• "image_generation"

• Computer object { type }

• type: "computer" (default: "computer")

要调用的工具，固定为 computer。

• "computer"

• CodeInterpreter object { type }

• type: "code_interpreter" (default: "code_interpreter")

要调用的工具，固定为 code_interpreter。

• "code_interpreter"

• ProgrammaticToolCalling object { type }

• type: "programmatic_tool_calling" (default: "programmatic_tool_calling")

要调用的工具，固定为 programmatic_tool_calling。

• "programmatic_tool_calling"

• Shell object { type }

需要调用工具时，强制模型调用 shell 工具。

• type: "shell" (default: "shell")

要调用的工具，固定为 shell。

• "shell"

• Custom object { name, type }

• name: string

要调用的自定义工具名称。

• type: "custom" (default: "custom")

要调用的工具，固定为 custom。

• "custom"

• ApplyPatch object { type }

执行工具调用时，强制模型调用 apply_patch 工具。

• type: "apply_patch" (default: "apply_patch")

要调用的工具，固定为 apply_patch。

• "apply_patch"

• type: "allowed_tools" (default: "allowed_tools")

工具选择类型，固定为 allowed_tools。

• "allowed_tools"

• mode: optional "none" or "auto" or "required" or null

从允许的工具集合中选择工具的方式。

• "none"

• "auto"

• "required"

• tools: optional array of FunctionTool or WebSearch { type } or FileSearch { type } or 10 more

Responses 后端处理 Live 模型委派的任务时可用的工具。

• FunctionTool object { name, type, description, 2 more }

Live 模型委派任务时，Responses 后端可用的函数工具。

• name: string

被委派的 Responses 模型调用此函数时使用的名称。

• type: "function" (default: "function")

工具类型，固定为 function。

• "function"

• description: optional string or null

函数的用途，以及被委派的 Responses 模型应在何时调用它。

• parameters: optional map[unknown] or null

描述函数可接受参数的 JSON Schema 对象。

• strict: optional boolean or null

被委派的 Responses 模型是否必须严格遵循函数的参数模式。

• WebSearch object { type }

Live 会话的 Responses 后端可用的网页搜索工具。

• type: "web_search" (default: "web_search")

工具类型，固定为 web_search。

• "web_search"

• FileSearch object { type }

• type: "file_search" (default: "file_search")

• "file_search"

• CodeInterpreter object { type }

• type: "code_interpreter" (default: "code_interpreter")

• "code_interpreter"

• Shell object { type, environment }

Responses shell 工具。可使用托管容器，或通过 response.item.create 返回本地 shell 执行结果。不支持域名密钥（domain secrets）。

• type: "shell" (default: "shell")

• "shell"

• environment: optional ContainerAuto { type, file_ids, memory_limit, 2 more } or ContainerReference { container_id, type } or Local { type, skills } or null

• ContainerAuto object { type, file_ids, memory_limit, 2 more }

• type: "container_auto" (default: "container_auto")

为此请求自动创建容器。

• "container_auto"

• file_ids: optional array of string or null

可选的已上传文件列表，这些文件将提供给代码使用。

maxItems: 50

• memory_limit: optional "1g" or "4g" or "16g" or "64g" or null

容器的内存上限。

• "1g"

• "4g"

• "16g"

• "64g"

• network_policy: optional Disabled { type } or Allowlist { allowed_domains, type } or null

容器的网络访问策略。

• Disabled object { type }

• type: "disabled" (default: "disabled")

禁用出站网络访问，固定为 disabled。

• "disabled"

• Allowlist object { allowed_domains, type }

• allowed_domains: array of string

type 为 allowlist 时允许访问的域名列表。

minItems: 1

• type: "allowlist" (default: "allowlist")

仅允许对指定域名发起出站网络访问，固定为 allowlist。

• "allowlist"

• skills: optional array of SkillReference { skill_id, type, version } or Inline { description, name, source, type } or null

可选的技能列表，通过 ID 或内联数据引用技能。

maxItems: 200

• SkillReference object { skill_id, type, version }

• skill_id: string

引用的技能 ID。

minLength: 1, maxLength: 64

• type: "skill_reference" (default: "skill_reference")

引用通过 /v1/skills 接口创建的技能。

• "skill_reference"

• version: optional string or null

可选的技能版本。使用正整数或 'latest'，省略时使用默认版本。

• Inline object { description, name, source, type }

• description: string

技能描述。

• name: string

技能名称。

• source: object { data, media_type, type }

内联技能载荷。

• data: string

采用 Base64 编码的技能 ZIP 包。

minLength: 1, maxLength: 70254592

• media_type: "application/zip" (default: "application/zip")

内联技能载荷的媒体类型，必须为 application/zip。

• "application/zip"

• type: "base64" (default: "base64")

内联技能来源的类型，必须为 base64。

• "base64"

• type: "inline" (default: "inline")

为此请求定义内联技能。

• "inline"

• ContainerReference object { container_id, type }

• container_id: string

引用的容器 ID。

• type: "container_reference" (default: "container_reference")

引用通过 /v1/containers 接口创建的容器。

• "container_reference"

• Local object { type, skills }

• type: "local" (default: "local")

使用本地计算机环境。

• "local"

• skills: optional array of object { description, name, path } or null

可选的技能列表。

maxItems: 200

• description: string

技能描述。

• name: string

技能名称。

• path: string

包含该技能的目录路径。

• ImageGeneration object { type }

• type: "image_generation" (default: "image_generation")

• "image_generation"

• Mcp object { type }

• type: "mcp" (default: "mcp")

• "mcp"

• Custom object { type }

• type: "custom" (default: "custom")

• "custom"

• Namespace object { type }

• type: "namespace" (default: "namespace")

• "namespace"

• ToolSearch object { type }

• type: "tool_search" (default: "tool_search")

• "tool_search"

• ProgrammaticToolCalling object { type }

• type: "programmatic_tool_calling" (default: "programmatic_tool_calling")

• "programmatic_tool_calling"

• Computer object { type }

• type: "computer" (default: "computer")

• "computer"

• ApplyPatch object { type }

• type: "apply_patch" (default: "apply_patch")

• "apply_patch"

• store: optional boolean

是否保存分叉后的会话。省略时继承已保存会话的设置。

返回值

• session: object { id }

新创建的 Live 会话。使用其 ID 控制会话或建立旁路连接。

• id: string

不透明的会话标识。须原样保留返回值，包括其前缀。

• transport: object { sdp, type }

WebRTC 传输对象，包含 SDP 应答。

• sdp: string

WebRTC 连接的会话描述协议（SDP）消息。

minLength: 1

• type: "webrtc"

Live 会话使用的传输方式，固定为 webrtc。

• "webrtc"

示例

## 设置 OPENAI_API_KEY，并替换会话 ID、SDP 与中继凭据；SDP 须使用实际协商内容。
curl https://api.openai.com/v1/live/sessions/$SESSION_ID/fork \
    -H 'Content-Type: application/json' \
    -H "Authorization: Bearer $OPENAI_API_KEY" \
    -d '{
          "transport": {
            "sdp": "x",
            "type": "webrtc"
          }
        }'

201：示例

{
  "session": {
    "id": "id"
  },
  "transport": {
    "sdp": "x",
    "type": "webrtc"
  }
}

示例

## 设置 OPENAI_API_KEY，并替换会话 ID、SDP 与中继凭据；SDP 须使用实际协商内容。
curl https://api.openai.com/v1/live/sessions/live_123/fork \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"session":{},"transport":{"type":"webrtc","sdp":"<SDP 提议>"}}'