O endpoint WebSocket e a ligação em tempo real
Nesta página
Atualizado a 3 de novembro de 2026, com base nas páginas Speech to Speech, Pricing e Rate limits da xAI: 0,08 USD por minuto, sessões simultâneas por nível e
grok-voice-3.0como modelo atual. Fontes: Speech to Speech · Pricing · Rate limits.
A API Voice Agent em tempo real
A API Grok Voice Agent permite-lhe criar agentes de voz conversacionais que interagem com os seus utilizadores em tempo real. Ao contrário das APIs REST clássicas, que funcionam pedido a pedido, esta API utiliza o protocolo WebSocket para manter uma ligação bidirecional persistente entre a sua aplicação e os servidores da xAI.

Existe apenas um endpoint:
wss://api.x.ai/v1/realtime
Seleciona o modelo através do parâmetro de URL model, por exemplo wss://api.x.ai/v1/realtime?model=grok-voice-latest. O grok-voice-latest aponta para o grok-voice-3.0, o modelo atual, sendo também a predefinição. Em produção, a xAI recomenda fixar uma versão nomeada.
Este único endpoint gere todo o ciclo de vida de uma conversação por voz: receção de áudio, deteção de fala, geração da resposta e envio do áudio sintetizado.
Estabelecer a ligação WebSocket
Para se ligar, inclua a sua chave de API da xAI no cabeçalho de autorização. Eis um exemplo em JavaScript:
const ws = new WebSocket("wss://api.x.ai/v1/realtime", {
headers: {
"Authorization": "Bearer " + process.env.XAI_API_KEY
}
});
ws.on("open", () => {
console.log("Ligação WebSocket estabelecida");
});
ws.on("message", (data) => {
const event = JSON.parse(data);
console.log("Evento recebido:", event.type);
});
ws.on("close", (code, reason) => {
console.log("Ligação encerrada:", code, reason);
});
ws.on("error", (err) => {
console.error("Erro WebSocket:", err);
});
Em Python, pode utilizar a biblioteca websockets:
import asyncio
import websockets
import json
import os
async def connect():
uri = "wss://api.x.ai/v1/realtime"
headers = {
"Authorization": f"Bearer {os.environ['XAI_API_KEY']}"
}
async with websockets.connect(uri, additional_headers=headers) as ws:
async for message in ws:
event = json.loads(message)
print(f"Evento: {event['type']}")
asyncio.run(connect())
Ciclo de vida da sessão
Assim que a ligação WebSocket é estabelecida, o servidor envia um evento session.created a confirmar que a sessão está ativa. De seguida, envia um evento session.update para configurar a conversação (voz, instruções, ferramentas, deteção de turnos).
O ciclo típico decorre da seguinte forma:
- Ligação: abrir o WebSocket com autenticação
- Configuração: enviar
session.updatecom as suas definições - Confirmação: receber
session.updateddo servidor - Conversação: trocar eventos de áudio e texto
- Encerramento: fechar limpa e corretamente o WebSocket
Gerir erros de ligação
O servidor pode encerrar ou recusar a ligação por vários motivos: erro de autenticação, exceder o limite de sessões simultâneas do seu nível (10 no nível inicial, até 200 no mais elevado) ou um incidente. A documentação atual não define uma duração máxima para a sessão, e a retoma de sessão (lição 4) permite-lhe retomar uma conversação após uma queda. A sua aplicação deve incluir lógica de reconexão com espera exponencial (exponential backoff).
Preços verificados a 3 de novembro de 2026. Os preços alteram-se frequentemente: antes de efetuar qualquer orçamento, consulte as tarifas atuais na página oficial de preços da xAI.
Pontos-chave
- O endpoint WebSocket
wss://api.x.ai/v1/realtimeé o único ponto de entrada para todas as conversações por voz - A autenticação é feita através do cabeçalho
Authorization: Bearer {chave de API} - O número de sessões simultâneas depende do seu nível: 10 no nível inicial, até 200
- O servidor envia
session.createdaquando da ligação e aguarda o seusession.updatepara configurar a conversação - O preçário é de 0,08 USD por minuto, ou 4,80 USD por hora, acrescidos de 0,004 USD por entrada de texto