音訊與即時
即時 WebSocket
透過 WebSocket 連線至即時語音工作階段
概觀
使用此端點進行即時語音工作階段。一般的 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 標頭或查詢字串無法將其覆寫。
連線
即時模型 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。
錯誤
在 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_model | model 查詢參數為空 |
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 的回應,並非工作階段事件。
回應
{
"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 金鑰。
位置: header
查詢參數
即時模型 ID。WebSocket 升級請求必填;一般 HTTP 中繼資料檢查則為選填。
回應
application/json
application/json
application/json
application/json
application/json