跳到主要内容

创建 Live 会话

POST 

https://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。

请求头​

名称类型必填描述
AuthorizationString是Bearer sk-… 或 Bearer ek_knox_…。
Content-TypeString是application/json,或原始 WebRTC offer 的 application/sdp / text/plain。

相同路由也挂载在 /api/v1 下。

JSON 请求体(application/json)​

名称类型必填描述
sessionObject否Live 会话配置。Knox 把 model 固定为 gpt-live-1。
session.modelString否若设置必须是 gpt-live-1。
session.audio.output.voiceString否音色名(上游默认 marin)。启动后不可改。
session.instructionsString否对话提示。省略则使用 OpenAI 服务端默认值。
session.delegationObject 或 null否省略 / null = client 模式。否则为 responses 或 decisions。
session.storeBoolean否true 以保留会话,供分叉和录音下载。
session.inputArray否先前文本消息。
transport.typeString否webrtc(默认)或 sip。
transport.sdpStringWebRTC 时WebRTC offer SDP。
transport.destinationStringSIP 时E.164 被叫号码。
transport.trunkObjectSIP 时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 数据通道。

错误响应​

状态何时
400JSON 无效、缺少 SDP、不支持的 transport.type,或无效 session(错误模型、非法后端模型)。
401缺少或无效的 Knox API key。
402账户余额不大于 $0.01。
403Token 白名单不包含 gpt-live-1。
502Failed to connect to Live provider / 缺少 session.id 或 SDP answer。