オーディオとリアルタイム
Realtime 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、従来のベータセッションAPI)は提供しません。
長期有効なAPIキーはサーバー上に保持してください。このエンドポイントはブラウザやモバイルアプリ向けの一時的なclient secretを発行しません。
リアルタイムセッションは、APIキーまたは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です。
エラー
ソケットが開く前は、使用可能なAPIキーが指定されていない認証情報はHTTP 401、403、429、または 503 とJSON形式のエラーボディで拒否されます。
ソケットが開いた後、拒否されたセッションは1つの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 | モデルがRealtime API用に公開されていません |
model_not_allowed, insufficient_balance, quota_exceeded | キーがこのモデルを使用できないか、残高またはキーの制限がセッションの予約額をカバーできません。APIエラーの処理 を参照してください |
サービスはこれらの拒否に対してコード 1008 でソケットを切断します。その他の切断コードには、メッセージが大きすぎる場合の 1009、メッセージのバックログが蓄積した場合の 1013、サービスがセッションのルーティングや中継を行えない場合の 1011 があります。エラーの処理は message ではなく code で行ってください。
請求と切断
セッションの料金は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キー認証。Dashboard > API > API KeysでAPIキーを作成または管理します。
場所: header
クエリパラメータ
リアルタイムモデルの ID。WebSocket アップグレードリクエストには必須ですが、通常の HTTP メタデータチェックでは任意です。
レスポンス
application/json
application/json
application/json
application/json
application/json