Audio & temps réel
WebSocket en temps réel
Connectez-vous à des sessions vocales en temps réel via WebSocket
Aperçu
Utilisez ce point de terminaison pour les sessions vocales en temps réel. Une simple requête GET renvoie les métadonnées du point de terminaison et ne nécessite aucune clé API. Une requête de mise à niveau WebSocket avec ?model={model} ouvre une session avec le modèle sélectionné.
Seuls les modèles dont les détails indiquent l'opération realtime peuvent ouvrir une session. Consultez supported_operations dans GET /v1/models/{model} avant de vous connecter. Ces mêmes détails de modèle répertorient les événements et les champs acceptés par une session, tels que session.update ou response.create.
Périmètre pris en charge
GET /v1/realtime est un sous-ensemble WebSocket. TokenLab relaie les événements en temps réel du modèle sélectionné. Il ne fournit pas les assistants REST OpenAI Realtime : création de session, client_secrets, Calls ou les API de session bêta héritées.
Conservez les clés API à longue durée de vie sur votre serveur. Ce point de terminaison ne délivre pas de secrets client à courte durée de vie pour les navigateurs ou les applications mobiles.
Les sessions en temps réel utilisent l'option de distribution de la clé API ou du Workspace. Un en-tête ou une chaîne de requête X-TokenLab-Delivery-Policy ne la remplace pas.
Connexion
ID du modèle en temps réel. Requis pour une mise à niveau WebSocket.
Bearer sk-your-api-key, envoyé avec la requête de mise à niveau. x-api-key est également accepté. Une clé dans la chaîne de requête n'est pas acceptée.
Requête
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()));Messages
TokenLab relaie les messages WebSocket entre votre client et le modèle. Utilisez le format d'événement de ce modèle, et placez model dans la chaîne de requête, et non dans chaque événement. Un message ne peut pas dépasser 32 MiB.
Erreurs
Avant l'ouverture du socket, un identifiant qui ne désigne aucune clé API utilisable est refusé avec une erreur HTTP 401, 403, 429 ou 503 et un corps d'erreur JSON.
Après l'ouverture du socket, une session rejetée envoie un message JSON puis ferme le socket :
{
"type": "error",
"status": 400,
"error": {
"message": "model query parameter is required",
"type": "invalid_request_error",
"code": "missing_model"
}
}error.code | Cause |
|---|---|
missing_model | Le paramètre de requête model est vide |
unsupported_operation | Le modèle n'est pas publié pour l'API Realtime |
model_not_allowed, insufficient_balance, quota_exceeded | La clé ne peut pas utiliser ce modèle, ou le solde ou la limite de la clé ne peut pas couvrir la réservation de la session. Voir Gérer les erreurs d'API |
Le service ferme le socket avec le code 1008 pour ces rejets. Autres codes de fermeture : 1009 lorsqu'un message est trop volumineux, 1013 lorsqu'un arriéré de messages s'accumule, et 1011 lorsque le service ne peut pas acheminer ou relayer la session. Gérez l'erreur par code, et non par message.
Facturation et fermeture
Les sessions sont facturées sur le solde de votre clé API. TokenLab réserve une estimation au début, puis règle l'utilisation réelle à la fin et rembourse la différence. Les modèles sont facturés au token ou à la durée de la session, comme l'indiquent les détails du modèle.
Fermez le socket client lorsque la session est terminée. Si le service ferme la session en premier, TokenLab envoie un code de fermeture à votre client dans la mesure du possible.
Exemple de réponse
Le JSON ci-dessous est la réponse à un GET HTTP standard. Il ne s'agit pas d'un événement de session.
Réponse
{
"object": "realtime.endpoint",
"websocket_url": "/v1/realtime?model={model}",
"protocol": "tokenlab_realtime_proxy"
}Champs importants
realtime.endpoint (GET HTTP)./v1/realtime?model={model} (GET HTTP).tokenlab_realtime_proxy (GET HTTP).Autorisation
BearerAuth Authentification par clé API. Créez ou gérez vos clés API dans Dashboard > API > API Keys.
Emplacement: header
Paramètres de requête
ID du modèle en temps réel. Requis pour les requêtes de mise à niveau WebSocket ; facultatif pour les vérifications de métadonnées HTTP simples.
Réponse
application/json
application/json
application/json
application/json
application/json