创建 Live 会话
POSThttps://api.knox.chat/v1/live/sessions
用 SDP offer 创建 Live WebRTC 会话,或发起外呼 SIP。Knox 使用通道密钥把请求转发到 OpenAI。
会话初始化后返回 201 Created。WebRTC 响应包含 SDP answer。SIP 响应不会等待被叫接听;请用 session.id 挂 sideband 观察进度。
媒体走向 OpenAI。Knox 会挂自己的 sideband,因此语音时长和嵌套后端用量仍会计费。WebRTC/SIP 创建会预收 15 秒语音费用,之后从累计时长中抵扣。
不要在 WebRTC 数据通道上再次发送 session.start。不要发送 audio.format(编解码器在媒体传输上协商)。创建时不要发送 session.type。
见 GPT-Live 指南和 OpenAI 的 Create session。
请求
发送 JSON 或原始 SDP。不接受 multipart/form-data。
请求头
| 名称 | 类型 | 必填 | 描述 |
|---|---|---|---|
| Authorization | String | 是 | Bearer sk-… 或 Bearer ek_knox_…。 |
| Content-Type | String | 是 | application/json,或原始 WebRTC offer 的 application/sdp / text/plain。 |
相同路由也挂载在 /api/v1 下。
JSON 请求体(application/json)
| 名称 | 类型 | 必填 | 描述 |
|---|---|---|---|
| session | Object | 否 | Live 会话配置。Knox 把 model 固定为 gpt-live-1。 |
| session.model | String | 否 | 若设置必须是 gpt-live-1。 |
| session.audio.output.voice | String | 否 | 音色名(上游默认 marin)。启动后不可改。 |
| session.instructions | String | 否 | 对话提示。省略则使用 OpenAI 服务端默认值。 |
| session.delegation | Object 或 null | 否 | 省略 / null = client 模式。否则为 responses 或 decisions。 |
| session.store | Boolean | 否 | true 以保留会话,供分叉和录音下载。 |
| session.input | Array | 否 | 先前文本消息。 |
| transport.type | String | 否 | webrtc(默认)或 sip。 |
| transport.sdp | String | WebRTC 时 | WebRTC offer SDP。 |
| transport.destination | String | SIP 时 | E.164 被叫号码。 |
| transport.trunk | Object | SIP 时 | SIP 中继凭证(见 OpenAI 电话文档)。 |
原始 SDP 请求体(application/sdp)
请求体是 offer SDP 文本。会话配置随后使用 Knox/OpenAI 默认值(gpt-live-1,client 模式委派)。
cURL 示例
WebRTC JSON
curl -s https://api.knox.chat/v1/live/sessions \
-H "Authorization: Bearer $KNOXCHAT_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"session": {
"model": "gpt-live-1",
"audio": { "output": { "voice": "marin" } },
"delegation": {
"type": "responses",
"responses": {
"model": "gpt-6-luna",
"tools": [{ "type": "web_search" }]
}
}
},
"transport": { "type": "webrtc", "sdp": "v=0\r\n…" }
}'
原始 SDP
curl -s https://api.knox.chat/v1/live/sessions \
-H "Authorization: Bearer $KNOXCHAT_API_KEY" \
-H "Content-Type: application/sdp" \
--data-binary @offer.sdp
原始 SDP 成功为 201 Created,Content-Type: application/sdp,Location: /v1/live/sessions/{id},以及 X-Live-Session-Id。
外呼 SIP
curl -s https://api.knox.chat/v1/live/sessions \
-H "Authorization: Bearer $KNOXCHAT_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"session": { "model": "gpt-live-1" },
"transport": {
"type": "sip",
"destination": "+15555550100",
"trunk": {}
}
}'
每次 SIP 请求都会创建新呼叫。若请求超时,重试需谨慎:原请求可能已经成功。振铃上限 3 分钟,接通后上限 2 小时。
响应
JSON 成功时,Knox 返回上游响应体(session 对象,WebRTC 另含 transport.sdp)。把 answer SDP 接到你的 RTCPeerConnection。此后音频与 OpenAI 点对点;控制事件仍走 WebRTC 数据通道。
错误响应
| 状态 | 何时 |
|---|---|
400 | JSON 无效、缺少 SDP、不支持的 transport.type,或无效 session(错误模型、非法后端模型)。 |
401 | 缺少或无效的 Knox API key。 |
402 | 账户余额不大于 $0.01。 |
403 | Token 白名单不包含 gpt-live-1。 |
502 | Failed to connect to Live provider / 缺少 session.id 或 SDP answer。 |