> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tokenlab.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# Realtime WebSocket

> WebSocket でリアルタイム音声およびマルチモーダルセッションに接続します

## 概要

このエンドポイントは、リアルタイム音声認識、音声合成、音声翻訳、リアルタイムマルチモーダルモデルのセッションに使用します。通常の `GET` はメタデータを返し、WebSocket アップグレードは選択された上流セッションへプロキシされます。

## サポート範囲

このエンドポイントは TokenLab のリアルタイム WebSocket プロキシです。同じパスで通常の `GET /v1/realtime` メタデータ確認と WebSocket アップグレードをサポートします。`POST /v1/realtime/client_secrets`、`POST /v1/realtime/translations/client_secrets`、Realtime Calls（`accept`、`hangup`、`refer`、`reject`）、legacy beta REST session / transcription-session 作成などの OpenAI Realtime REST 補助エンドポイントは公開していません。

ブラウザやモバイルアプリでは、長期 API キーをサーバー側に保持してください。このエンドポイントは短期 Realtime client secret を発行しません。

<Note>エージェントは `/v1/models` で realtime 対応モデルを確認してから socket を開いてください。</Note>

## 接続

<ParamField query="model" type="string" required>
  リアルタイムモデル ID。対応状況で realtime をサポートするモデルを使用してください。
</ParamField>

<ParamField header="Authorization" type="string" required>
  Bearer API キー。WebSocket クライアントはアップグレード要求で `Authorization: Bearer sk-your-api-key` を送信します。
</ParamField>

<RequestExample>
  ```javascript JavaScript theme={null}
  import WebSocket from 'ws';

  const socket = new WebSocket('wss://api.tokenlab.sh/v1/realtime?model=gpt-realtime', {
    headers: { Authorization: 'Bearer sk-your-api-key' }
  });

  socket.on('open', () => {
    socket.send(JSON.stringify({
      type: 'session.update',
      session: { modalities: ['text', 'audio'] }
    }));
  });

  socket.on('message', (data) => {
    console.log('realtime event', data.toString());
  });
  ```

  ```bash cURL theme={null}
  curl "https://api.tokenlab.sh/v1/realtime" \
    -H "Authorization: Bearer sk-your-api-key"
  ```
</RequestExample>

## メッセージ

TokenLab はクライアントとルーティングされたリアルタイムプロバイダーの間で WebSocket メッセージを転送します。選択したモデルの公式イベント形式を使い、`model` はクエリ文字列で指定します。

## 課金と終了

リアルタイムセッションは同じ API キー残高を使用します。TokenLab は接続時に少額を事前控除し、終了時に精算または返金します。

セッション完了後はクライアント socket を閉じてください。上流が先に閉じた場合、TokenLab は可能な限り close code を転送します。

## レスポンス例

<ResponseExample>
  ```json Connected theme={null}
  {
    "type": "session.created",
    "session": {
      "id": "sess_abc123",
      "model": "gpt-realtime",
      "modalities": ["text", "audio"]
    }
  }
  ```
</ResponseExample>

## 重要フィールド

<ResponseField name="type" type="string">API が返す event または message type です。</ResponseField>
<ResponseField name="session.id" type="string">リアルタイム提供元が返す識別子です。サポート用ログに含めるためのもので、REST session URL ではありません。</ResponseField>