> ## 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

> Conecte sessões de voz e multimodais em tempo real via WebSocket

## Visão geral

Este endpoint é usado para reconhecimento de fala, síntese de fala, tradução de fala ou modelos multimodais em tempo real. Um `GET` comum retorna metadados; o upgrade WebSocket é proxificado para a sessão upstream roteada.

## Superfície compatível

Este endpoint é o proxy WebSocket em tempo real do TokenLab. Ele aceita uma verificação de metadados com `GET /v1/realtime` e upgrades WebSocket no mesmo caminho. Ele não expõe endpoints auxiliares REST do OpenAI Realtime, como `POST /v1/realtime/client_secrets`, `POST /v1/realtime/translations/client_secrets`, Realtime Calls (`accept`, `hangup`, `refer`, `reject`) nem criação de legacy beta REST session / transcription-session.

Em apps web ou móveis, mantenha chaves API de longa duração no seu servidor. Este endpoint não emite Realtime client secrets de curta duração.

<Note>Agentes devem descobrir modelos com suporte a realtime em `/v1/models` antes de abrir o socket.</Note>

## Conexão

<ParamField query="model" type="string" required>
  ID do modelo em tempo real. Use um modelo cujo detalhes do modelo liste suporte a realtime.
</ParamField>

<ParamField header="Authorization" type="string" required>
  Chave API Bearer. Clientes WebSocket devem enviar `Authorization: Bearer sk-your-api-key` na requisição de 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>

## Mensagens

TokenLab encaminha mensagens WebSocket entre o cliente e o provedor realtime roteado. Preserve os eventos oficiais do modelo selecionado e passe `model` na query string.

## Cobrança e encerramento

Sessões realtime usam o mesmo saldo da chave API. TokenLab pré-deduz uma pequena estimativa ao abrir e liquida ou reembolsa ao fechar.

Feche o socket do cliente quando a sessão terminar. Se o upstream fechar primeiro, TokenLab repassa o código de fechamento quando possível.

## Exemplo de resposta

<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 ou mensagem retornado pela API.</ResponseField>
<ResponseField name="session.id" type="string">Identificador emitido pelo provedor realtime; inclua-o em logs de suporte, não como URL de sessão REST.</ResponseField>