音频与实时
实时 WebSocket
通过 WebSocket 连接实时语音会话
概述
该端点用于实时语音会话。普通 GET 请求返回端点信息,不需要 API 密钥。携带 ?model={model} 的 WebSocket 升级请求则为所选模型开启会话。
只有模型详情中列出 realtime 操作的模型才能开启会话。连接前请读取 GET /v1/models/{model} 的 supported_operations。会话接受的事件和字段(例如 session.update、response.create)同样在该模型详情中列出。
支持范围
GET /v1/realtime 是 WebSocket 子集。TokenLab 转发所选模型的实时事件,不提供 OpenAI Realtime 的 REST 辅助接口:创建会话、client_secrets、Calls 或旧版 beta session API。
请把长期 API 密钥保存在你的服务端。该端点不为浏览器或移动端签发短期 client secret。
实时会话使用 API 密钥或工作区设置的交付选项。X-TokenLab-Delivery-Policy 请求头和查询字符串都不会覆盖它。
连接
实时模型 ID。WebSocket 升级必填。
升级请求中发送 Bearer sk-your-api-key。也接受 x-api-key。不接受放在查询字符串里的密钥。
请求
import WebSocket from 'ws';
const url = new URL('wss://api.tokenlab.sh/v1/realtime');
url.searchParams.set('model', 'grok-voice-latest');
const socket = new WebSocket(url, {
headers: { Authorization: `Bearer ${process.env.TOKENLAB_API_KEY}` }
});
socket.on('open', () => console.log('Realtime connection open'));
socket.on('message', (data) => {
const event = JSON.parse(data.toString());
if (event.type === 'error') {
console.error('Realtime error', event.status, event.error.code);
return;
}
console.log('realtime event', event.type);
});
socket.on('close', (code, reason) => console.log('closed', code, reason.toString()));消息
TokenLab 在你的客户端与模型之间转发 WebSocket 消息。请使用该模型的事件格式,并把 model 放在查询字符串中,不要放进每个事件。单条消息最大 32 MiB。
错误
连接建立前,凭据没有指向可用 API 密钥时,会以 HTTP 401、403、429 或 503 加 JSON 错误体拒绝。
连接建立后,被拒绝的会话会先发送一条 JSON 消息,再关闭连接:
{
"type": "error",
"status": 400,
"error": {
"message": "model query parameter is required",
"type": "invalid_request_error",
"code": "missing_model"
}
}error.code | 原因 |
|---|---|
missing_model | model 查询参数为空 |
unsupported_operation | 该模型未开放实时 API |
model_not_allowed、insufficient_balance、quota_exceeded | 密钥不能使用该模型,或余额、密钥额度不足以覆盖会话预留。见处理 API 错误 |
这些拒绝都以关闭码 1008 关闭连接。其他关闭码:消息过大为 1009,消息积压为 1013,服务无法路由或转发会话为 1011。请按 code 处理错误,不要依赖 message。
计费与关闭
会话按 API 密钥余额计费。TokenLab 在开始时预留一个估算额度,结束时按实际用量结算并退回差额。模型按 token 或按会话时长计费,以模型详情为准。
会话结束后请关闭客户端连接。如果服务端先关闭会话,TokenLab 会尽量向你的客户端发送关闭码。
响应示例
下面的 JSON 是普通 HTTP GET 的响应,不是会话事件。
响应
{
"object": "realtime.endpoint",
"websocket_url": "/v1/realtime?model={model}",
"protocol": "tokenlab_realtime_proxy"
}重要字段
realtime.endpoint(HTTP GET)。/v1/realtime?model={model}(HTTP GET)。tokenlab_realtime_proxy(HTTP GET)。授权
BearerAuth API Key 身份验证。在 Dashboard > API > API Keys 中创建或管理 API Key。
位置: header
查询参数
实时模型 ID。WebSocket 升级请求必需;普通 HTTP 元数据检查可选。
响应
application/json
application/json
application/json
application/json
application/json