TokenLab

音訊與即時

即時 WebSocket

透過 WebSocket 連線至即時語音工作階段

GET
/v1/realtime

概觀

使用此端點進行即時語音工作階段。一般的 GET 請求會傳回端點中繼資料,且不需要 API key。帶有 ?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 工作階段 API。

請將長效 API key 保留在您的伺服器端。此端點不會為瀏覽器或行動應用程式核發短效 client secrets。

即時工作階段會使用 API key 或 Workspace 的傳遞選項。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。

錯誤

在 socket 開啟前,若憑證未指定可用的 API key,將會被拒絕並傳回 HTTP 401、403、429 或 503 以及 JSON 錯誤主體。

在 socket 開啟後,遭到拒絕的工作階段會傳送一則 JSON 訊息,然後關閉 socket:

{
  "type": "error",
  "status": 400,
  "error": {
    "message": "model query parameter is required",
    "type": "invalid_request_error",
    "code": "missing_model"
  }
}
error.code原因
missing_modelmodel 查詢參數為空
unsupported_operation該模型未發布供 Realtime API 使用
model_not_allowed, insufficient_balance, quota_exceeded此金鑰無法使用該模型,或是餘額與金鑰額度不足以支付工作階段預留費用。請參閱處理 API 錯誤

針對這些拒絕情況,服務將以代碼 1008 關閉 socket。其他關閉代碼包括:訊息過大時為 1009、訊息積壓時為 1013,以及服務無法路由或轉發工作階段時為 1011。請根據 code 而非 message 來處理錯誤。

計費與關閉

工作階段費用會從您的 API key 餘額中扣除。TokenLab 會在開始時預留預估費用,並在結束時結算實際用量並退還差額。模型會依據 token 或工作階段時間進行計費,具體取決於其模型詳細資料。

工作階段結束時,請關閉客戶端 socket。若服務先行關閉工作階段,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 金鑰。

位置: header

查詢參數

model?string

即時模型 ID。WebSocket 升級請求必填;一般 HTTP 中繼資料檢查則為選填。

回應

application/json

application/json

application/json

application/json

application/json