Ir para o conteúdo principal
Português— Escolher um idioma
Menu

O endpoint WebSocket e a ligação em tempo real

Aula 1 de 16 Atualizada a 3 de novembro de 2026 Programador
Nesta página
  1. A API Voice Agent em tempo real
  2. Estabelecer a ligação WebSocket
  3. Ciclo de vida da sessão
  4. Pontos-chave

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.0 como 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.

Documentação da API Voice Agent

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.

WebSocket
Protocolo em tempo real
grok-voice-3.0
Modelo atual
10
Sessões simultâneas no nível inicial
$0.08/min
Preçário

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:

  1. Ligação: abrir o WebSocket com autenticação
  2. Configuração: enviar session.update com as suas definições
  3. Confirmação: receber session.updated do servidor
  4. Conversação: trocar eventos de áudio e texto
  5. 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.created aquando da ligação e aguarda o seu session.update para 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