音訊與即時
即時 WebSocket
透過 WebSocket 連線即時語音與多模態會話
概覽
此端點用於即時工作階段，例如串流語音辨識、語音合成、語音翻譯或即時多模態模型。一般 GET 請求會回傳端點中繼資料，而 WebSocket 升級請求則會為所選模型開啟一個即時工作階段。
支援範圍
TokenLab 在 GET /v1/realtime 提供即時 WebSocket 端點，可用於端點資訊檢查與 WebSocket 升級。請把它理解為 WebSocket 子集（WebSocket subset）：它只轉發受支援即時模型的事件，不支援 OpenAI Realtime 的 REST 輔助面，例如建立工作階段、client_secrets、Calls 通話控制 API 或 legacy beta session API。
瀏覽器或行動端應把長期 API Key 保留在服務端。此端點不會簽發短期 Realtime client secret。
/v1/models 選擇目前即時模型，查詢 /v1/models/{model} 確認後設定 TOKENLAB_REALTIME_MODEL。工作階段事件與設定以模型為準。下方 JSON 範例是一般 HTTP GET 的回應，不是 WebSocket 工作階段事件。連線
即時模型 ID。請選擇模型詳情中包含 realtime 支援的模型。
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));訊息
TokenLab 會在你的用戶端與所選即時模型之間轉發 WebSocket 訊息。請使用該模型文件中說明的事件格式，並將 model 放在查詢字串中，而非放進每個事件裡。
計費與關閉
工作階段會以 API 金鑰餘額計費：TokenLab 會在開始時預估並預留額度，結束後依實際用量結算並退還差額。
工作階段完成後請關閉用戶端連線。若服務端先關閉工作階段，TokenLab 會在可能的情況下向你的用戶端傳送一個安全的關閉事件/代碼。
回應
{
"object": "realtime.endpoint",
"websocket_url": "/v1/realtime?model={model}",
"protocol": "tokenlab_realtime_proxy"
}重要欄位
realtime.endpoint。/v1/realtime?model={model}。將 {model} 替換為所選模型的 ID。tokenlab_realtime_proxy。授權
BearerAuth API Key 驗證。請在 Dashboard > API > API Keys 建立或管理 API 金鑰。
位置: header
查詢參數
用於路由 WebSocket 會話的 Realtime 模型 ID。WebSocket 升級請求為必填項；純 HTTP 元數據檢查則為選填項。
回應
application/json
application/json
application/json
application/json
application/json
application/json