Ses ve gerçek zamanlı

Realtime WebSocket

WebSocket üzerinden gerçek zamanlı ses oturumlarına bağlanın

GET
/v1/realtime

Genel Bakış

Bu endpoint'i gerçek zamanlı ses oturumları için kullanın. Yalın bir GET isteği endpoint meta verilerini döndürür ve herhangi bir API key gerektirmez. ?model={model} içeren bir WebSocket upgrade isteği, seçilen modelle bir oturum açar.

Yalnızca ayrıntılarında realtime operasyonu listelenen modeller oturum açabilir. Bağlanmadan önce GET /v1/models/{model} içindeki supported_operations alanını inceleyin. Aynı model ayrıntıları, oturumun kabul ettiği session.update veya response.create gibi etkinlikleri ve alanları da listeler.

Desteklenen kapsam

GET /v1/realtime bir WebSocket alt kümesidir. TokenLab, seçilen modelin realtime etkinliklerini iletir. OpenAI Realtime REST yardımcılarını sağlamaz: oturum oluşturma, client_secrets, Calls veya eski beta oturum API'leri.

Uzun ömürlü API key'lerinizi sunucunuzda tutun. Bu endpoint, tarayıcılar veya mobil uygulamalar için kısa ömürlü client secret'lar üretmez.

Realtime oturumları, API key veya Workspace'in iletim seçeneğini (delivery option) kullanır. X-TokenLab-Delivery-Policy başlığı veya sorgu dizesi bunu geçersiz kılmaz.

Bağlantı

modelstringqueryzorunlu

Realtime model ID'si. WebSocket upgrade işlemi için zorunludur.

Authorizationstringheaderzorunlu

Upgrade isteğiyle birlikte gönderilen Bearer sk-your-api-key. x-api-key de kabul edilir. Sorgu dizesindeki bir anahtar kabul edilmez.

İstek

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

Mesajlar

TokenLab, istemciniz ile model arasındaki WebSocket mesajlarını iletir. İlgili modelin etkinlik formatını kullanın ve model parametresini her etkinliğin içine değil, sorgu dizesine ekleyin. Bir mesaj en fazla 32 MiB olabilir.

Hatalar

Soket açılmadan önce, kullanılabilir bir API key belirtmeyen kimlik bilgileri HTTP 401, 403, 429 veya 503 ve bir JSON hata gövdesi ile reddedilir.

Soket açıldıktan sonra, reddedilen bir oturum bir JSON mesajı gönderir ve ardından soketi kapatır:

{
  "type": "error",
  "status": 400,
  "error": {
    "message": "model query parameter is required",
    "type": "invalid_request_error",
    "code": "missing_model"
  }
}
error.codeNeden
missing_modelmodel sorgu parametresi boş
unsupported_operationModel, Realtime API için yayınlanmamış
model_not_allowed, insufficient_balance, quota_exceededAnahtar bu modeli kullanamıyor ya da bakiye veya anahtar limiti oturum rezervasyonunu karşılayamıyor. Bkz. API hatalarını yönetme

Servis, bu retler için soketi 1008 koduyla kapatır. Diğer kapatma kodları: mesaj çok büyük olduğunda 1009, mesaj birikmesi oluştuğunda 1013 ve servis oturumu yönlendiremediğinde veya iletemediğinde 1011. Hatayı message yerine code değerine göre ele alın.

Faturalandırma ve kapatma

Oturumlar API key bakiyenizden faturalandırılır. TokenLab başlangıçta tahmini bir tutarı rezerve eder, ardından sonlandığında fiili kullanımı mutabakat yaparak farkı iade eder. Modeller, model ayrıntılarında gösterildiği gibi token başına veya oturum süresine göre faturalandırılır.

Oturum tamamlandığında istemci soketini kapatın. Oturumu önce servis kapatırsa, TokenLab mümkün olduğunda istemcinize bir kapatma kodu gönderir.

Yanıt örneği

Aşağıdaki JSON, sıradan bir HTTP GET isteğinin yanıtıdır. Bir oturum etkinliği değildir.

Yanıt

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

Önemli alanlar

objectstring
realtime.endpoint (HTTP GET isteğinde).
websocket_urlstring
/v1/realtime?model={model} (HTTP GET isteğinde).
protocolstring
tokenlab_realtime_proxy (HTTP GET isteğinde).

Yetkilendirme

BearerAuth
AuthorizationBearer <token>

API Anahtarı kimlik doğrulaması. API anahtarlarını Dashboard > API > API Keys bölümünden oluşturun veya yönetin.

Konum: header

Sorgu parametreleri

model?string

Gerçek zamanlı model kimliği. WebSocket yükseltme istekleri için zorunludur; düz HTTP meta veri kontrolleri için isteğe bağlıdır.

Yanıt

application/json

application/json

application/json

application/json

application/json