音频与实时

实时 WebSocket

通过 WebSocket 连接实时语音会话

GET
/v1/realtime

概述

该端点用于实时语音会话。普通 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 请求头和查询字符串都不会覆盖它。

连接

modelstringquery必填

实时模型 ID。WebSocket 升级必填。

Authorizationstringheader必填

升级请求中发送 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_modelmodel 查询参数为空
unsupported_operation该模型未开放实时 API
model_not_allowed、insufficient_balance、quota_exceeded密钥不能使用该模型,或余额、密钥额度不足以覆盖会话预留。见处理 API 错误

这些拒绝都以关闭码 1008 关闭连接。其他关闭码:消息过大为 1009,消息积压为 1013,服务无法路由或转发会话为 1011。请按 code 处理错误,不要依赖 message。

计费与关闭

会话按 API 密钥余额计费。TokenLab 在开始时预留一个估算额度,结束时按实际用量结算并退回差额。模型按 token 或按会话时长计费,以模型详情为准。

会话结束后请关闭客户端连接。如果服务端先关闭会话,TokenLab 会尽量向你的客户端发送关闭码。

响应示例

下面的 JSON 是普通 HTTP GET 的响应,不是会话事件。

响应

HTTP GET
{
  "object": "realtime.endpoint",
  "websocket_url": "/v1/realtime?model={model}",
  "protocol": "tokenlab_realtime_proxy"
}

重要字段

objectstring
realtime.endpoint(HTTP GET)。
websocket_urlstring
/v1/realtime?model={model}(HTTP GET)。
protocolstring
tokenlab_realtime_proxy(HTTP GET)。

授权

BearerAuth
AuthorizationBearer <token>

API Key 身份验证。在 Dashboard > API > API Keys 中创建或管理 API Key。

位置: header

查询参数

model?string

实时模型 ID。WebSocket 升级请求必需;普通 HTTP 元数据检查可选。

响应

application/json

application/json

application/json

application/json

application/json