Audio & realtime

WebSocket Realtime

Terhubung ke sesi suara realtime melalui WebSocket

GET
/v1/realtime

Gambaran Umum

Gunakan endpoint ini untuk sesi suara realtime. Permintaan GET biasa mengembalikan metadata endpoint dan tidak memerlukan API key. Permintaan upgrade WebSocket dengan ?model={model} membuka sesi dengan model yang dipilih.

Hanya model yang detailnya mencantumkan operasi realtime yang dapat membuka sesi. Baca supported_operations di GET /v1/models/{model} sebelum Anda terhubung. Detail model yang sama mencantumkan event dan field yang diterima oleh sesi, seperti session.update atau response.create.

Fitur yang didukung

GET /v1/realtime adalah subset WebSocket. TokenLab meneruskan realtime event dari model yang dipilih. Ini tidak menyediakan helper REST OpenAI Realtime: pembuatan sesi, client_secrets, Calls, atau API sesi beta lama.

Simpan API key jangka panjang di server Anda. Endpoint ini tidak menerbitkan client secret berumur pendek untuk browser atau aplikasi seluler.

Sesi realtime menggunakan opsi pengiriman dari API key atau Workspace. Header X-TokenLab-Delivery-Policy atau query string tidak akan menimpanya.

Koneksi

modelstringquerywajib

ID model realtime. Diperlukan untuk upgrade WebSocket.

Authorizationstringheaderwajib

Bearer sk-your-api-key, dikirim bersama permintaan upgrade. x-api-key juga diterima. Key dalam query string tidak diterima.

Permintaan

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()));

Pesan

TokenLab meneruskan pesan WebSocket antara client Anda dan model. Gunakan format event model tersebut, dan sertakan model dalam query string, bukan di setiap event. Ukuran pesan maksimal adalah 32 MiB.

Error

Sebelum socket terbuka, kredensial yang tidak menyertakan API key yang dapat digunakan akan ditolak dengan HTTP 401, 403, 429, atau 503 beserta body error JSON.

Setelah socket terbuka, sesi yang ditolak akan mengirimkan satu pesan JSON kemudian menutup socket:

{
  "type": "error",
  "status": 400,
  "error": {
    "message": "model query parameter is required",
    "type": "invalid_request_error",
    "code": "missing_model"
  }
}
error.codePenyebab
missing_modelParameter query model kosong
unsupported_operationModel tidak dipublikasikan untuk Realtime API
model_not_allowed, insufficient_balance, quota_exceededKey tidak dapat menggunakan model ini, atau saldo maupun batas key tidak mencukupi untuk reservasi sesi. Lihat Menangani error API

Layanan akan menutup socket dengan kode 1008 untuk penolakan ini. Kode penutupan lainnya: 1009 saat pesan terlalu besar, 1013 saat terjadi penumpukan backlog pesan, dan 1011 saat layanan tidak dapat merutekan atau meneruskan sesi. Tangani error berdasarkan code, bukan berdasarkan message.

Penagihan dan penutupan

Sesi ditagihkan ke saldo API key Anda. TokenLab mencadangkan perkiraan biaya di awal, lalu menyelesaikan penggunaan aktual di akhir dan mengembalikan selisihnya. Model ditagihkan berdasarkan token atau berdasarkan durasi sesi, sebagaimana tercantum pada detail model.

Tutup socket client ketika sesi telah selesai. Jika layanan menutup sesi terlebih dahulu, TokenLab akan mengirimkan kode penutupan ke client Anda jika memungkinkan.

Contoh respons

JSON di bawah ini adalah respons terhadap HTTP GET biasa. Ini bukan sebuah event sesi.

Respons

HTTP GET
{
  "object": "realtime.endpoint",
  "websocket_url": "/v1/realtime?model={model}",
  "protocol": "tokenlab_realtime_proxy"
}

Field penting

objectstring
realtime.endpoint (pada permintaan HTTP GET).
websocket_urlstring
/v1/realtime?model={model} (pada permintaan HTTP GET).
protocolstring
tokenlab_realtime_proxy (pada permintaan HTTP GET).

Otorisasi

BearerAuth
AuthorizationBearer <token>

Autentikasi API Key. Buat atau kelola API key di Dashboard > API > API Keys.

Lokasi: header

Parameter query

model?string

ID model realtime. Diperlukan untuk permintaan upgrade WebSocket; opsional untuk pemeriksaan metadata HTTP biasa.

Respons

application/json

application/json

application/json

application/json

application/json