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

> Kết nối phiên giọng nói và đa phương thức thời gian thực qua WebSocket

## Tổng quan

Endpoint này dùng cho nhận dạng giọng nói, tổng hợp giọng nói, dịch giọng nói hoặc mô hình đa phương thức thời gian thực. Yêu cầu `GET` thường trả về metadata; yêu cầu upgrade WebSocket sẽ được proxy tới phiên upstream đã định tuyến.

## Phạm vi hỗ trợ

Endpoint này là proxy WebSocket thời gian thực của TokenLab. Nó hỗ trợ kiểm tra metadata bằng `GET /v1/realtime` và upgrade WebSocket trên cùng đường dẫn. Nó không cung cấp các REST helper endpoint của OpenAI Realtime như `POST /v1/realtime/client_secrets`, `POST /v1/realtime/translations/client_secrets`, Realtime Calls (`accept`, `hangup`, `refer`, `reject`) hoặc tạo legacy beta REST session / transcription-session.

Với ứng dụng trình duyệt hoặc di động, hãy giữ API key dài hạn trên server của bạn. Endpoint này không phát hành Realtime client secret ngắn hạn.

<Note>Agent nên dùng `/v1/models` để tìm mô hình hỗ trợ realtime trước khi mở socket.</Note>

## Kết nối

<ParamField query="model" type="string" required>
  ID mô hình realtime. Chọn mô hình có chi tiết model liệt kê hỗ trợ realtime.
</ParamField>

<ParamField header="Authorization" type="string" required>
  API key Bearer. Client WebSocket nên gửi `Authorization: Bearer sk-your-api-key` trong yêu cầu upgrade.
</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>

## Tin nhắn

TokenLab chuyển tiếp tin nhắn WebSocket giữa client và nhà cung cấp realtime đã định tuyến. Giữ đúng dạng sự kiện chính thức của mô hình đã chọn và truyền `model` trong query string.

## Tính phí và đóng kết nối

Phiên realtime dùng cùng số dư API key. TokenLab trừ trước một ước tính nhỏ khi socket mở, rồi quyết toán hoặc hoàn tiền khi phiên đóng.

Đóng socket client khi phiên hoàn tất. Nếu upstream đóng trước, TokenLab sẽ chuyển tiếp close code khi có thể.

## Ví dụ phản hồi

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

## Trường quan trọng

<ResponseField name="type" type="string">Loại event hoặc message do API trả về.</ResponseField>
<ResponseField name="session.id" type="string">Mã định danh do provider realtime trả về; dùng trong log hỗ trợ, không phải REST session URL.</ResponseField>