Áudio e tempo real

WebSocket em tempo real

Conecte-se a sessões de voz em tempo real via WebSocket

GET
/v1/realtime

Visão geral

Use este endpoint para sessões de voz em tempo real. Uma requisição GET simples retorna metadados do endpoint e não requer chave de API. Uma requisição de upgrade de WebSocket com ?model={model} abre uma sessão com o modelo selecionado.

Apenas modelos cujos detalhes listam a operação realtime podem abrir uma sessão. Consulte supported_operations em GET /v1/models/{model} antes de se conectar. Os mesmos detalhes do modelo listam os eventos e campos que uma sessão aceita, como session.update ou response.create.

Superfície suportada

O GET /v1/realtime é um subconjunto de WebSocket. O TokenLab retransmite os eventos em tempo real do modelo selecionado. Ele não fornece os helpers REST do OpenAI Realtime: criação de sessão, client_secrets, Calls ou APIs legadas de sessão beta.

Mantenha chaves de API de longa duração em seu servidor. Este endpoint não emite client secrets de curta duração para navegadores ou aplicativos móveis.

Sessões em tempo real usam a opção de entrega da chave de API ou do Workspace. Um cabeçalho X-TokenLab-Delivery-Policy ou query string não a substitui.

Conexão

modelstringqueryobrigatório

ID do modelo de realtime. Obrigatório para um upgrade de WebSocket.

Authorizationstringheaderobrigatório

Bearer sk-your-api-key, enviado com a requisição de upgrade. x-api-key também é aceito. Uma chave na query string não é aceita.

Requisição

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()));

Mensagens

O TokenLab retransmite mensagens WebSocket entre o seu cliente e o modelo. Use o formato de evento desse modelo e inclua model na query string, não em cada evento. Uma mensagem pode ter no máximo 32 MiB.

Erros

Antes da abertura do socket, uma credencial que não indica nenhuma chave de API utilizável é recusada com um HTTP 401, 403, 429 ou 503 e um corpo de erro em JSON.

Após a abertura do socket, uma sessão rejeitada envia uma mensagem JSON e, em seguida, fecha o socket:

{
  "type": "error",
  "status": 400,
  "error": {
    "message": "model query parameter is required",
    "type": "invalid_request_error",
    "code": "missing_model"
  }
}
error.codeCausa
missing_modelO parâmetro de consulta model está vazio
unsupported_operationO modelo não está publicado para a Realtime API
model_not_allowed, insufficient_balance, quota_exceededA chave não pode usar este modelo, ou o saldo ou o limite da chave não pode cobrir a reserva da sessão. Consulte Tratar erros de API

O serviço fecha o socket com o código 1008 para essas rejeições. Outros códigos de fechamento: 1009 quando uma mensagem é muito grande, 1013 quando um acúmulo de mensagens se forma e 1011 quando o serviço não consegue rotear ou retransmitir a sessão. Trate o erro pelo code, não pela message.

Faturamento e encerramento

As sessões são cobradas no saldo da sua chave de API. O TokenLab reserva uma estimativa no início, depois liquida o uso real no final e reembolsa a diferença. Os modelos são cobrados por token ou por tempo de sessão, conforme indicado nos detalhes do modelo.

Feche o socket do cliente quando a sessão for concluída. Se o serviço fechar a sessão primeiro, o TokenLab enviará um código de fechamento para o seu cliente, quando possível.

Exemplo de resposta

O JSON abaixo é a resposta para um HTTP GET comum. Não é um evento de sessão.

Resposta

HTTP GET
{
  "object": "realtime.endpoint",
  "websocket_url": "/v1/realtime?model={model}",
  "protocol": "tokenlab_realtime_proxy"
}

Campos importantes

objectstring
realtime.endpoint (em requisições HTTP GET).
websocket_urlstring
/v1/realtime?model={model} (em requisições HTTP GET).
protocolstring
tokenlab_realtime_proxy (em requisições HTTP GET).

Autorização

BearerAuth
AuthorizationBearer <token>

Autenticação por Chave de API. Crie ou gerencie chaves de API em Dashboard > API > API Keys.

Local: header

Parâmetros de consulta

model?string

ID do modelo em tempo real. Obrigatório para requisições de upgrade de WebSocket; opcional para verificações de metadados HTTP simples.

Resposta

application/json

application/json

application/json

application/json

application/json