> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tokenlab.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# Realtime WebSocket

> Conecta sesiones de voz y multimodales en tiempo real por WebSocket

## Resumen

Este endpoint sirve para reconocimiento de voz, síntesis de voz, traducción de voz o modelos multimodales en tiempo real. Un `GET` normal devuelve metadatos; el upgrade WebSocket se proxifica a la sesión upstream enrutada.

## Superficie admitida

Este endpoint es el proxy WebSocket en tiempo real de TokenLab. Admite una comprobación de metadatos con `GET /v1/realtime` y upgrades WebSocket en la misma ruta. No expone endpoints auxiliares REST de OpenAI Realtime como `POST /v1/realtime/client_secrets`, `POST /v1/realtime/translations/client_secrets`, Realtime Calls (`accept`, `hangup`, `refer`, `reject`) ni creación de legacy beta REST session / transcription-session.

En apps web o móviles, mantén las claves API de larga duración en tu servidor. Este endpoint no emite Realtime client secrets de corta duración.

<Note>Los agentes deben descubrir modelos con soporte realtime en `/v1/models` antes de abrir el socket.</Note>

## Conexión

<ParamField query="model" type="string" required>
  ID del modelo en tiempo real. Usa un modelo cuyos detalles indiquen compatibilidad en tiempo real.
</ParamField>

<ParamField header="Authorization" type="string" required>
  Clave API Bearer. Los clientes WebSocket deben enviar `Authorization: Bearer sk-your-api-key` durante el upgrade.
</ParamField>

<RequestExample>
  ```javascript JavaScript theme={null}
  import WebSocket from 'ws';

  const socket = new WebSocket('wss://api.tokenlab.sh/v1/realtime?model=gpt-realtime', {
    headers: { Authorization: 'Bearer sk-your-api-key' }
  });

  socket.on('open', () => {
    socket.send(JSON.stringify({
      type: 'session.update',
      session: { modalities: ['text', 'audio'] }
    }));
  });

  socket.on('message', (data) => {
    console.log('realtime event', data.toString());
  });
  ```

  ```bash cURL theme={null}
  curl "https://api.tokenlab.sh/v1/realtime" \
    -H "Authorization: Bearer sk-your-api-key"
  ```
</RequestExample>

## Mensajes

TokenLab reenvía mensajes WebSocket entre tu cliente y el proveedor realtime enrutado. Conserva la forma oficial de eventos del modelo elegido y pasa `model` en la query string.

## Facturación y cierre

Las sesiones realtime usan el mismo saldo de la clave API. TokenLab predescuenta una pequeña estimación al abrir y liquida o reembolsa al cerrar.

Cierra el socket del cliente cuando termine la sesión. Si el upstream cierra primero, TokenLab reenvía el código de cierre cuando sea posible.

## Ejemplo de respuesta

<ResponseExample>
  ```json Connected theme={null}
  {
    "type": "session.created",
    "session": {
      "id": "sess_abc123",
      "model": "gpt-realtime",
      "modalities": ["text", "audio"]
    }
  }
  ```
</ResponseExample>

## Campos importantes

<ResponseField name="type" type="string">Tipo de evento o mensaje devuelto por la API.</ResponseField>
<ResponseField name="session.id" type="string">Identificador emitido por el proveedor realtime; inclúyelo en logs de soporte, no como URL de sesión REST.</ResponseField>