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

Tokens efémeros e segurança

Aula 13 de 14 Atualizada a 3 de novembro de 2026 Intermediario
Nesta página
  1. O problema de ter uma chave de API no cliente
  2. Como funciona
  3. A arquitetura de ponta a ponta
  4. Regras que nunca deve quebrar
  5. Pontos-chave

Atualizado a 3 de novembro de 2026, com base na referência da API de Voz da xAI. Fontes: Tokens Efémeros · Referência da API de Voz · Retoma de Sessão.

O problema de ter uma chave de API no cliente

Uma aplicação de voz executada num navegador ou num telemóvel não pode incluir a sua chave de API. Qualquer visitante pode abrir as ferramentas de programador, ler a chave no pacote JavaScript ou num cabeçalho de pedido e, em seguida, utilizá-la na sua conta até esgotar a sua quota. Nenhuma quantidade de ofuscação protege um valor que o cliente precisa de ter para chamar a API.

A resposta da xAI são os tokens efémeros, também chamados segredos de cliente: um token de curta duração, gerado pelo seu servidor, que autoriza uma sessão de voz e nada mais.

600s
duração padrão
3600s
duração máxima
POST
/v1/realtime/client_secrets
valor
o token, com expires_at

Como funciona

O fluxo resume-se a cinco passos:

  1. O seu backend (um servidor seguro) chama POST /v1/realtime/client_secrets com a sua chave de API
  2. A API devolve um token temporário com uma duração limitada
  3. O seu backend envia esse token para o cliente (navegador ou aplicação móvel)
  4. O cliente utiliza o token para ligar ao WebSocket do Agente de Voz
  5. O token expira após a duração que escolheu (expires_after.seconds)

O que pode vazar no lado do cliente passa a ter muito menos valor: um token que expira em minutos e só pode abrir uma sessão de voz, não a sua chave de API. No servidor, gerar um requer apenas algumas linhas de código. Note que o handler começa por verificar o utilizador: sem essa verificação, o seu backend é apenas um distribuidor público de tokens.

// Backend Node.js (Express)
app.post("/api/voice-token", async (req, res) => {
  // Verificar se o utilizador está autenticado
  if (!req.user) return res.status(401).json({ error: "Unauthorized" });

  const response = await fetch(
    "https://api.x.ai/v1/realtime/client_secrets",
    {
      method: "POST",
      headers: {
        "Authorization": "Bearer " + process.env.XAI_API_KEY,
        "Content-Type": "application/json"
      },
      body: JSON.stringify({
        expires_after: { seconds: 600 }  // 10 minutos, o padrão
      })
    }
  );

  const data = await response.json();  // { value, expires_at }
  res.json({ token: data.value, expiresAt: data.expires_at });
});

O cliente só conhece a sua própria rota: pede um token e, em seguida, abre o WebSocket com ele.

// Frontend (navegador)
async function startVoiceSession() {
  // Pedir um token ao backend
  const tokenRes = await fetch("/api/voice-token", { method: "POST" });
  const { token } = await tokenRes.json();

  // O WebSocket do navegador não aceita cabeçalhos:
  // o token vai num subprotocolo, prefixado com "xai-client-secret."
  const ws = new WebSocket(
    "wss://api.x.ai/v1/realtime?model=grok-voice-latest",
    [`xai-client-secret.${token}`]
  );

  // ... configuração da sessão
}

A arquitetura de ponta a ponta

No conjunto, o fluxo começa com o utilizador a iniciar sessão na sua aplicação. O cliente pede então um token de voz ao seu backend, e o backend verifica a autenticação e as permissões antes de gerar o token efémero através da API da xAI. O token regressa ao cliente, que o utiliza para abrir a sessão do Agente de Voz, expirando automaticamente no fim da sua duração.

Essa verificação entre o pedido e a geração transforma um simples retransmissor num ponto de controlo, e é aí que residem as suas regras de negócio. Pode limitar o número de sessões de voz por utilizador por dia, para que uma única conta não consuma todo o seu orçamento mensal durante a noite. Pode reservar tokens para subscrições ativas, aplicando o seu modelo de negócio noutro local que não a interface. Pode limitar a taxa de pedidos, para que um cliente com erros ou malicioso não possa pedir mil tokens por minuto. E pode registar cada token que gera: é a sua única base fiável para monitorização, faturação interna e análise de incidentes.

Regras que nunca deve quebrar

A chave de API nunca vai para o cliente, sob nenhuma forma. Mantenha-a fora do JavaScript de front-end e fora de qualquer variável de ambiente exposta à compilação do navegador (variáveis prefixadas para serem injetadas no pacote tornam-se públicas). Mantenha-a também fora de URLs, registos e mensagens de erro mostradas aos utilizadores.

Em seguida, mantenha a duração o mais curta possível. De acordo com a referência da API, expires_after.seconds tem o padrão de 600 segundos e um máximo de 3.600; a documentação utiliza 300 nos seus exemplos. Acima de tudo, o token precisa de ser válido quando o cliente abre a ligação. Uma duração curta reduz a janela durante a qual um token intercetado pode ser utilizado.

A documentação não indica se um token que expira corta uma ligação que já está aberta. Se o seu cliente precisar de se religar, após uma queda de rede ou durante uma sessão muito longa, peça um novo token e utilize a retoma de sessão: ative resumption.enabled em session.update, guarde o ID que recebe em conversation.created e, em seguida, reabra o WebSocket com ?conversation_id=<id>. As trocas anteriores são repetidas e o modelo retoma onde parou.

async function reconnect(conversationId) {
  const { token } = await (await fetch("/api/voice-token", { method: "POST" })).json();
  const url = `wss://api.x.ai/v1/realtime?model=grok-voice-latest&conversation_id=${conversationId}`;
  const ws = new WebSocket(url, [`xai-client-secret.${token}`]);
  ws.onopen = () => ws.send(JSON.stringify({
    type: "session.update",
    session: { resumption: { enabled: true } },  // enviar novamente em cada ligação
  }));
  return ws;
}

Para TTS no modo HTTP, existe uma alternativa ainda mais simples aos tokens: um proxy. O cliente envia o seu texto para o seu backend, e o seu backend chama o TTS e devolve o áudio. A chave nunca sai do seu servidor e obtém um local natural para filtrar conteúdo e medir a utilização no processo.

Pontos-chave

  • Os tokens efémeros garantem o acesso ao Agente de Voz a partir de aplicações do lado do cliente
  • POST /v1/realtime/client_secrets devolve value e expires_at; expires_after.seconds tem o padrão de 600 e um máximo de 3.600
  • No navegador, o token vai no subprotocolo xai-client-secret.<token>
  • O seu backend deve verificar a autenticação e as permissões antes de gerar um token
  • Nunca exponha a sua chave de API no cliente, em URLs ou em registos
  • Para TTS HTTP, o uso de um proxy através do seu backend é uma alternativa válida aos tokens efémeros