连接 Live 会话
GETwss://api.knox.chat/v1/live/sessions
打开一个按量计费的全双工 GPT-Live 会话。Knox 会验证您的 API key,选择上游 OpenAI Live 通道,并转发事件流。
这不是 POST /v1/chat/completions,也不是 GET /v1/realtime。客户端必须升级为 WebSocket。普通 HTTP GET 会返回 400。相同路由也挂载在 /api/v1 下。
接受的模型 ID:仅 gpt-live-1。把它写在 session.start 里。不要传 ?model=(若出现非 Live id,Knox 会拒绝)。会话配置、计费、委派、WebRTC 和 SIP 的完整说明见 GPT-Live 指南。
OpenAI 官方参考:GPT-Live 概览、Connect、WebSockets。
请求
请求头
| 名称 | 类型 | 必填 | 描述 |
|---|---|---|---|
| Authorization | String | 条件必填 | Bearer sk-… 或 Bearer ek_knox_…。除非密钥通过 WebSocket 子协议发送,或(仅 WebSocket 升级)作为 ?api_key= / ?authorization=,否则必填。 |
| x-api-key | String | 否 | Authorization 的 Anthropic 风格替代。 |
| Upgrade | String | 是 | 必须为 websocket。 |
浏览器原生 WebSocket 无法设置 HTTP 头。使用子协议形式:
const ws = new WebSocket(
"wss://api.knox.chat/v1/live/sessions",
["openai-insecure-api-key.sk-YOUR_KNOX_KEY"]
);
Knox 会哈希用户 ID 并向上游发送 OpenAI-Safety-Identifier;您无需自行设置。
第一条消息
第一条 JSON 文本帧必须是 session.start(超时 30 秒)。在发送音频之前等待 session.started。
{
"type": "session.start",
"event_id": "event_start",
"session": {
"model": "gpt-live-1",
"instructions": "Be concise. Delegate current-facts questions to the backend.",
"audio": {
"format": { "type": "audio/pcm", "rate": 24000 },
"output": { "voice": "marin" }
},
"delegation": {
"type": "responses",
"responses": {
"model": "gpt-6-luna",
"tools": [{ "type": "web_search" }],
"tool_choice": "auto"
}
}
}
}
Knox 会把 session.model 固定为 gpt-live-1,丢弃未知字段(包括 type),并保持省略的 instructions / delegation 未设置,以便 OpenAI 使用其默认值(client 模式委派)。若转发多余字段,上游会返回 unknown_parameter。
连接示例
import WebSocket from "ws";
const ws = new WebSocket("wss://api.knox.chat/v1/live/sessions", {
headers: { Authorization: "Bearer " + process.env.KNOX_API_KEY },
});
ws.on("open", () => {
ws.send(JSON.stringify({
type: "session.start",
session: {
model: "gpt-live-1",
audio: { format: { type: "audio/pcm", rate: 24000 } },
},
}));
});
ws.on("message", (data) => {
const event = JSON.parse(data.toString());
if (event.type === "session.started") {
ws.send(JSON.stringify({
type: "session.input_audio.append",
audio: "<base64 pcm16>",
}));
}
});
session.started 之后,发送 session.input_audio.append,内容为 base64 PCM16 单声道 24 kHz(或你配置的格式)。播放 session.output_audio.delta。用 session.close 结束,并等待 session.closed。
错误响应
| 状态 | 何时 |
|---|---|
400 | 请求不是 WebSocket 升级,或握手无效。 |
401 | 缺少或无效的 Knox API key(或过期的 ek_knox_…)。 |
402 | 账户余额不大于 $0.01。 |
403 | Token 的模型白名单不包含 gpt-live-1。 |
502 | 没有可用的 OpenAI 兼容 Live 通道,或上游连接失败。 |
升级成功后,失败也可能以 WebSocket error 事件到达(session_start_required、invalid_session、invalid_json)。