Ses ve gerçek zamanlı
Realtime WebSocket
WebSocket üzerinden gerçek zamanlı ses oturumlarına bağlanın
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ı
Realtime model ID'si. WebSocket upgrade işlemi için zorunludur.
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.code | Neden |
|---|---|
missing_model | model sorgu parametresi boş |
unsupported_operation | Model, Realtime API için yayınlanmamış |
model_not_allowed, insufficient_balance, quota_exceeded | Anahtar 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
{
"object": "realtime.endpoint",
"websocket_url": "/v1/realtime?model={model}",
"protocol": "tokenlab_realtime_proxy"
}Önemli alanlar
realtime.endpoint (HTTP GET isteğinde)./v1/realtime?model={model} (HTTP GET isteğinde).tokenlab_realtime_proxy (HTTP GET isteğinde).Yetkilendirme
BearerAuth 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
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