Áudio e tempo real
WebSocket em tempo real
Conecte-se a sessões de voz em tempo real via WebSocket
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
ID do modelo de realtime. Obrigatório para um upgrade de WebSocket.
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.code | Causa |
|---|---|
missing_model | O parâmetro de consulta model está vazio |
unsupported_operation | O modelo não está publicado para a Realtime API |
model_not_allowed, insufficient_balance, quota_exceeded | A 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
{
"object": "realtime.endpoint",
"websocket_url": "/v1/realtime?model={model}",
"protocol": "tokenlab_realtime_proxy"
}Campos importantes
realtime.endpoint (em requisições HTTP GET)./v1/realtime?model={model} (em requisições HTTP GET).tokenlab_realtime_proxy (em requisições HTTP GET).Autorização
BearerAuth Autenticação por Chave de API. Crie ou gerencie chaves de API em Dashboard > API > API Keys.
Local: header
Parâmetros de consulta
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