> ## 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.

# 即時 WebSocket

> 透過 WebSocket 連線即時語音與多模態會話

## 概覽

此端點用於即時語音辨識、語音合成、語音翻譯或即時多模態模型等會話。一般 `GET` 請求會回傳端點資訊；WebSocket 升級請求會代理到路由後的即時上游會話。

## 支援範圍

此端點是 TokenLab 的即時 WebSocket 代理。它支援一般 `GET /v1/realtime` 端點資訊檢查，也支援在同一路徑發起 WebSocket 升級。它不提供 OpenAI Realtime 的 REST 輔助端點，例如 `POST /v1/realtime/client_secrets`、`POST /v1/realtime/translations/client_secrets`、Realtime Calls（`accept`、`hangup`、`refer`、`reject`），也不提供 legacy beta REST session / transcription-session 建立。

瀏覽器或行動端應把長期 API Key 保留在服務端。此端點不會簽發短期 Realtime client secret。

<Note>Agent 應先透過 `/v1/models` 找到支援 realtime 的模型，再開啟 socket。</Note>

## 連線

<ParamField query="model" type="string" required>
  即時模型 ID。請選擇対応状況中包含 realtime 支援的模型。
</ParamField>

<ParamField header="Authorization" type="string" required>
  Bearer API Key。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 Key 餘額。TokenLab 會在 socket 開啟時預扣小額估算費用，並在會話關閉時計費或退款。

會話完成後關閉用戶端 socket。若上游先關閉，TokenLab 會盡可能把關閉碼轉發給用戶端。

## 回應範例

<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 返回的事件或訊息類型。</ResponseField>
<ResponseField name="session.id" type="string">即時提供方回傳的標識符；可用於日誌和支援排障，不是 REST session URL。</ResponseField>