创建实时客户端密钥

POST 
https://api.knox.chat/v1/realtime/client_secrets

为浏览器 Realtime 客户端签发 Knox 临时密钥。响应不是 OpenAI 的 ek_ 密钥。请立即使用 value 在 Knox 上打开 /v1/realtime 或 /v1/realtime/calls，而不是 api.openai.com。

TTL 为 60 秒。密钥保存在签发它的 Knox 进程内存中：换到另一台副本、进程重启或等待过久都会使密钥失效。

请求

此端点需要一个 JSON 对象。空请求体可接受，将使用 Knox 默认值。

请求头

名称	类型	必填	描述
Authorization	String	是	Bearer 认证，格式为 Bearer sk-…。
Content-Type	String	是	必须为 application/json。

请求体

名称	类型	必填	描述
session	Object	否	附加到密钥的 Realtime 会话配置。省略时 Knox 应用默认会话（type realtime、模型 gpt-realtime-2.1、音频 PCM 24 kHz、音色 marin、reasoning.effort low）。
session.type	String	否	设置时必须为 realtime。缺失时 Knox 会补上。
session.model	String	否	gpt-realtime-2.1 或 gpt-realtime-2.1-mini。默认为 gpt-realtime-2.1。
session.audio	Object	否	输入/输出音频格式、VAD、音色。
session.reasoning	Object	否	省略时默认为 { "effort": "low" }。

也可以在 URL 上传递 ?model=。相同路由也挂载在 /api/v1 下。

cURL 示例

curl -s https://api.knox.chat/v1/realtime/client_secrets \
     -H "Authorization: Bearer $KNOXCHAT_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
  "session": {
    "type": "realtime",
    "model": "gpt-realtime-2.1",
    "audio": { "output": { "voice": "marin" } }
  }
}'

响应

成功响应（200）

{
  "value": "ek_knox_…",
  "expires_at": 1750000000,
  "session": {
    "type": "realtime",
    "model": "gpt-realtime-2.1"
  }
}

响应 Schema

名称	类型	描述
value	string	Knox 临时密钥（ek_knox_…）。下次连接 Realtime 时作为 Authorization: Bearer ek_knox_… 发送。
expires_at	integer	密钥过期的 Unix 时间戳（签发后约 60 秒）。
session	object	与密钥一起存储的会话配置，包含 Knox 默认值，以及启用时注入的托管 web_search。

错误响应

状态码	何时出现
400	JSON 请求体无效。
401	Knox API key 缺失或无效。
402	账户余额不大于 $0.01。
403	Token 的模型白名单不包含所请求的实时模型（gpt-realtime-2.1 或 gpt-realtime-2.1-mini）。
502	没有可用的 OpenAI 兼容 Realtime 通道。