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

> Hubungkan sesi suara dan multimodal realtime melalui WebSocket

## Ikhtisar

Endpoint ini digunakan untuk pengenalan suara, sintesis suara, terjemahan suara, atau model multimodal realtime. Permintaan `GET` biasa mengembalikan metadata; upgrade WebSocket diproksikan ke sesi upstream realtime yang dirutekan.

## Permukaan yang didukung

Endpoint ini adalah proxy WebSocket realtime TokenLab. Endpoint ini mendukung pengecekan metadata `GET /v1/realtime` biasa dan upgrade WebSocket pada path yang sama. Endpoint ini tidak menyediakan endpoint helper REST OpenAI Realtime seperti `POST /v1/realtime/client_secrets`, `POST /v1/realtime/translations/client_secrets`, Realtime Calls (`accept`, `hangup`, `refer`, `reject`), atau pembuatan legacy beta REST session / transcription-session.

Untuk aplikasi browser atau mobile, simpan API key jangka panjang di server Anda. Endpoint ini tidak menerbitkan Realtime client secret berumur pendek.

<Note>Agent sebaiknya menemukan model yang mendukung realtime melalui `/v1/models` sebelum membuka socket.</Note>

## Koneksi

<ParamField query="model" type="string" required>
  ID model realtime. Gunakan model yang detail modelnya mencantumkan dukungan realtime.
</ParamField>

<ParamField header="Authorization" type="string" required>
  API key Bearer. Client WebSocket harus mengirim `Authorization: Bearer sk-your-api-key` saat upgrade request.
</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>

## Pesan

TokenLab meneruskan pesan WebSocket antara client dan penyedia realtime yang dirutekan. Pertahankan bentuk event resmi model yang dipilih dan kirim `model` di query string.

## Penagihan dan penutupan

Sesi realtime memakai saldo API key yang sama. TokenLab melakukan pre-deduct kecil saat socket dibuka, lalu melakukan settlement atau refund saat sesi ditutup.

Tutup socket client saat sesi selesai. Jika upstream menutup lebih dulu, TokenLab meneruskan close code bila memungkinkan.

## Contoh respons

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

## Field penting

<ResponseField name="type" type="string">Tipe event atau message yang dikembalikan API.</ResponseField>
<ResponseField name="session.id" type="string">Identifier yang dikirim provider realtime; sertakan di log dukungan, bukan sebagai REST session URL.</ResponseField>