オーディオとリアルタイム

Realtime 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、従来のベータセッションAPI)は提供しません。

長期有効なAPIキーはサーバー上に保持してください。このエンドポイントはブラウザやモバイルアプリ向けの一時的なclient secretを発行しません。

リアルタイムセッションは、APIキーまたは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です。

エラー

ソケットが開く前は、使用可能な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_modelmodel クエリパラメータが空です
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に対するレスポンスです。セッションイベントではありません。

レスポンス

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キー認証。Dashboard > API > API KeysでAPIキーを作成または管理します。

場所: header

クエリパラメータ

model?string

リアルタイムモデルの ID。WebSocket アップグレードリクエストには必須ですが、通常の HTTP メタデータチェックでは任意です。

レスポンス

application/json

application/json

application/json

application/json

application/json