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

TTS em Streaming via WebSocket

Aula 9 de 14 Atualizada a 3 de novembro de 2026 Intermediario
Nesta página
  1. Por que o streaming muda a experiência
  2. Abrir a ligação
  3. O protocolo de mensagens
  4. Uma implementação completa
  5. Limites a conhecer
  6. HTTP ou WebSocket
  7. Pontos-chave

Atualizado a 3 de novembro de 2026, com base na página Text to Speech da xAI. Fonte: Text to Speech.

Por que o streaming muda a experiência

No modo HTTP, o TTS só devolve o controlo depois de todo o áudio ser gerado. Para uma notificação de duas frases, ninguém nota a espera. Para um artigo de blogue, um capítulo de livro ou um feed de notícias com deslocamento contínuo, essa espera torna-se o maior defeito do seu produto: os utilizadores clicam e ficam a olhar para um indicador de carregamento durante vários segundos.

O modo WebSocket elimina essa espera, enviando o áudio à medida que este é sintetizado. A reprodução começa nas primeiras palavras, antes mesmo de o final do texto ser processado. É a diferença entre uma página que parece congelada e um áudio que toca imediatamente.

Abrir a ligação

A ligação estabelece-se em wss://api.x.ai/v1/tts, e toda a configuração vai na cadeia de consulta (query string) do URL, e não numa mensagem de inicialização.

const ws = new WebSocket(
  "wss://api.x.ai/v1/tts?language=en&voice=ara&codec=mp3&sample_rate=24000",
  {
    headers: {
      "Authorization": "Bearer " + XAI_API_KEY
    }
  }
);

Estes são os parâmetros aceites:

  • language (obrigatório): um código BCP-47 ou auto
  • voice (opcional, predefinição: eve): o ID da voz
  • codec (opcional, predefinição: mp3): o formato de áudio de saída
  • sample_rate (opcional, predefinição: 24000): a taxa de amostragem em Hz
  • bit_rate (opcional, predefinição: 128000): a taxa de bits em bps (apenas MP3)

Estas definições aplicam-se a toda a sessão: não pode alterar a voz ou o codec no meio do processo. Se a sua aplicação precisar de alternar entre dois narradores, abra duas ligações.

O protocolo de mensagens

Do lado do envio, apenas precisa de duas mensagens para conduzir a síntese. A primeira envia um fragmento de texto; a segunda anuncia que o texto terminou.

{ "type": "text.delta", "delta": "Hello and welcome " }
{ "type": "text.done" }

Pode enviar quantas mensagens text.delta forem necessárias, cada uma com até 60.000 carateres. Ainda assim, é melhor não atingir esse limite: dividir o texto em blocos de algumas frases faz com que o primeiro fragmento de áudio chegue muito mais depressa, que é exatamente o objetivo do streaming. Um único delta com vários milhares de carateres devolve-o ao comportamento do modo HTTP.

Do lado da receção, cada audio.delta transporta um fragmento de áudio codificado em base64, no codec que definiu ao estabelecer a ligação. Descodifique-o e anexe-o ao seu buffer de reprodução.

{ "type": "audio.delta", "delta": "<base64 audio>" }
{ "type": "audio.done", "trace_id": "trace-uuid" }

O evento audio.done marca o fim da síntese. O seu trace_id é o identificador a fornecer ao suporte ou a registar nos seus logs quando uma geração apresentar problemas. Se o texto for inválido ou se excedeu a sua quota, receberá uma mensagem de erro em vez disso.

{ "type": "error", "message": "description of the error" }

Uma implementação completa

O exemplo abaixo divide um texto longo em parágrafos, envia-os todos e, em seguida, monta os fragmentos de áudio recebidos num ficheiro MP3.

const WebSocket = require("ws");
const fs = require("fs");

const ws = new WebSocket(
  "wss://api.x.ai/v1/tts?language=en&voice=rex&codec=mp3",
  { headers: { "Authorization": "Bearer " + process.env.XAI_API_KEY } }
);

const audioChunks = [];

ws.on("open", () => {
  const paragraphs = longText.split("\n\n");
  for (const para of paragraphs) {
    ws.send(JSON.stringify({
      type: "text.delta",
      delta: para + " "
    }));
  }
  ws.send(JSON.stringify({ type: "text.done" }));
});

ws.on("message", (data) => {
  const msg = JSON.parse(data);
  if (msg.type === "audio.delta") {
    audioChunks.push(Buffer.from(msg.delta, "base64"));
  } else if (msg.type === "audio.done") {
    fs.writeFileSync("output.mp3", Buffer.concat(audioChunks));
    ws.close();
  }
});

Note o para + " ": sem esse espaço, o fim de um parágrafo cola-se ao início do seguinte, e o motor lê as duas palavras juntas, sem pausa para respirar.

Limites a conhecer

MétricaValor
Texto por deltaMáximo de 60.000 carateres
Texto totalIlimitado
Sessões simultâneas50 por equipa
Permissão de sessão600 segundos
Tempo limite de ligaçãoNenhum

A página da xAI indica que a ligação não tem tempo limite e menciona separadamente uma “permissão de sessão” de 600 segundos, sem explicar o que acontece quando esta expira. Por precaução, estabeleça a ligação apenas quando tiver texto para enviar, e não quando a página carregar, e planeie a reconexão. Planeie também em torno do limite de 50 sessões simultâneas por equipa: uma biblioteca de áudio que converta o seu catálogo em segundo plano deve colocar as suas tarefas numa fila, em vez de abrir duzentas ligações em paralelo.

HTTP ou WebSocket

O modo HTTP continua a ser a escolha certa para textos curtos, gerações pontuais e sempre que a simplicidade de integração for prioritária: um pedido, uma resposta, sem estado para gerir. O WebSocket é o caminho a seguir quando o texto é longo, quando o áudio deve tocar enquanto está a ser produzido, ou quando o próprio conteúdo chega como um fluxo, tipicamente a saída de um modelo de linguagem que vai narrando à medida que gera.

Pontos-chave

  • O TTS via WebSocket permite receber áudio em streaming sem esperar pelo fim da geração
  • Os parâmetros de configuração vão na cadeia de consulta do URL de ligação
  • O protocolo é simples: text.delta para enviar texto, audio.delta para receber áudio
  • As sessões WebSocket estão limitadas a 50 simultâneas por equipa; planeie a reconexão
  • Prefira o WebSocket para textos longos e experiências de escuta em tempo real