音频与实时
实时 WebSocket
通过 WebSocket 连接实时语音和多模态会话
通过 WebSocket 使用实时语音、翻译和多模态模型。普通 GET 请求返回接口信息；WebSocket 升级请求会开启实时会话。
支持范围
该接口是 OpenAI Realtime 的 WebSocket 子集，支持实时模型的 WebSocket 事件，不提供其 REST 辅助接口，例如 client_secrets、Calls API 或 legacy beta session API。
不要把长期 API 密钥写进浏览器或移动端应用。该接口目前不签发短期 Realtime client secret。
从
/v1/models 选择当前实时模型，查询 /v1/models/{model} 确认后设置 TOKENLAB_REALTIME_MODEL。会话事件与配置以模型为准。下方 JSON 示例是普通 HTTP GET 的返回，不是 WebSocket 会话事件。连接
modelstringquery必填
实时模型 ID。请选择模型说明中包含 realtime 支持的模型。
Authorizationstringheader必填
Bearer API Key。WebSocket 客户端应在升级请求中发送 Authorization: Bearer sk-your-api-key。
请求
import WebSocket from 'ws';
const model = process.env.TOKENLAB_REALTIME_MODEL;
const apiKey = process.env.TOKENLAB_API_KEY;
if (!model || !apiKey) {
throw new Error('Set TOKENLAB_REALTIME_MODEL and TOKENLAB_API_KEY');
}
const url = new URL('wss://api.tokenlab.sh/v1/realtime');
url.searchParams.set('model', model);
const socket = new WebSocket(url, {
headers: { Authorization: `Bearer ${apiKey}` }
});
socket.on('open', () => {
console.log('Realtime connection open');
});
socket.on('message', (data) => {
console.log('realtime event', data.toString());
});
socket.on('error', (error) => console.error(error.message));
socket.on('close', (code) => console.log('Realtime connection closed', code));消息
事件格式以所选模型为准。model 放在连接 URL 的查询字符串中，不需要写进每条事件。
计费与关闭
会话按实际用量计费，费用会计入所用 API 密钥。
会话结束后关闭连接。服务端结束会话时，客户端会收到关闭事件或状态码。
响应
{
"object": "realtime.endpoint",
"websocket_url": "/v1/realtime?model={model}",
"protocol": "tokenlab_realtime_proxy"
}重要字段
objectstring
普通 HTTP GET 响应的对象类型，固定为
realtime.endpoint。websocket_urlstring
普通 HTTP GET 返回的 WebSocket 相对连接路径：
/v1/realtime?model={model}。将 {model} 替换为所选模型的 ID。protocolstring
普通 HTTP GET 返回的协议标识，固定为
tokenlab_realtime_proxy。typestring
API 返回的事件或消息类型。
session.idstring
实时会话 ID，可用于日志和问题排查。
授权
BearerAuth AuthorizationBearer <token>
API Key 身份验证。在 Dashboard > API > API Keys 中创建或管理 API Key。
位置: header
查询参数
model?string
用于路由 WebSocket 会话的实时模型 ID。WebSocket 升级请求必需；普通 HTTP 元数据检查可选。
响应
application/json
application/json
application/json
application/json
application/json
application/json