Audio y tiempo real
WebSocket en tiempo real
Conéctese a sesiones de voz en tiempo real a través de WebSocket
Descripción general
Utilice este endpoint para sesiones de voz en tiempo real. Una solicitud GET simple devuelve metadatos del endpoint y no requiere una API key. Una solicitud de actualización a WebSocket con ?model={model} abre una sesión con el modelo seleccionado.
Solo los modelos cuyos detalles incluyan la operación realtime pueden abrir una sesión. Consulte supported_operations en GET /v1/models/{model} antes de conectarse. Esos mismos detalles del modelo enumeran los eventos y campos que acepta una sesión, como session.update o response.create.
Superficie compatible
GET /v1/realtime es un subconjunto de WebSocket. TokenLab retransmite los eventos en tiempo real del modelo seleccionado. No proporciona helpers REST de OpenAI Realtime: creación de sesiones, client_secrets, Calls ni APIs de sesión beta heredadas.
Mantenga las API keys de larga duración en su servidor. Este endpoint no emite secretos de cliente de corta duración para navegadores o aplicaciones móviles.
Las sesiones en tiempo real utilizan la opción de entrega de la API key o del Workspace. Un encabezado X-TokenLab-Delivery-Policy o un parámetro en la cadena de consulta no la anulan.
Conexión
ID del modelo en tiempo real. Obligatorio para una actualización a WebSocket.
Bearer sk-your-api-key, enviado con la solicitud de actualización. También se acepta x-api-key. No se acepta una clave en la cadena de consulta.
Solicitud
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()));Mensajes
TokenLab retransmite mensajes de WebSocket entre su cliente y el modelo. Utilice el formato de evento de ese modelo e incluya model en la cadena de consulta, no en cada evento. Un mensaje puede tener como máximo 32 MiB.
Errores
Antes de que se abra el socket, una credencial que no especifique una API key utilizable se rechaza con un código HTTP 401, 403, 429 o 503 y un cuerpo de error en formato JSON.
Después de que se abre el socket, una sesión rechazada envía un mensaje JSON y luego cierra el socket:
{
"type": "error",
"status": 400,
"error": {
"message": "model query parameter is required",
"type": "invalid_request_error",
"code": "missing_model"
}
}error.code | Causa |
|---|---|
missing_model | El parámetro de consulta model está vacío |
unsupported_operation | El modelo no está publicado para la Realtime API |
model_not_allowed, insufficient_balance, quota_exceeded | La clave no puede utilizar este modelo, o el saldo o límite de la clave no cubre la reserva de la sesión. Consulte Gestionar errores de la API |
El servicio cierra el socket con el código 1008 para estos rechazos. Otros códigos de cierre: 1009 cuando un mensaje es demasiado grande, 1013 cuando se acumula una cola de mensajes pendientes y 1011 cuando el servicio no puede enrutar o retransmitir la sesión. Gestione el error por code, no por message.
Facturación y cierre
Las sesiones se facturan contra el saldo de su API key. TokenLab reserva una estimación al inicio, liquida el uso real al finalizar y reembolsa la diferencia. Los modelos se facturan por token o por tiempo de sesión, según se indica en los detalles del modelo.
Cierre el socket del cliente cuando la sesión haya finalizado. Si el servicio cierra la sesión primero, TokenLab enviará un código de cierre a su cliente cuando sea posible.
Ejemplo de respuesta
El siguiente JSON es la respuesta a una solicitud HTTP GET ordinaria. No es un evento de sesión.
Respuesta
{
"object": "realtime.endpoint",
"websocket_url": "/v1/realtime?model={model}",
"protocol": "tokenlab_realtime_proxy"
}Campos importantes
realtime.endpoint (en solicitudes HTTP GET)./v1/realtime?model={model} (en solicitudes HTTP GET).tokenlab_realtime_proxy (en solicitudes HTTP GET).Autorización
BearerAuth Autenticación con API Key. Cree o gestione API keys en Dashboard > API > API Keys.
Ubicación: header
Parámetros de consulta
ID del modelo en tiempo real. Requerido para solicitudes de actualización de WebSocket; opcional para comprobaciones de metadatos HTTP simples.
Respuesta
application/json
application/json
application/json
application/json
application/json