TTS em Streaming via WebSocket
Nesta página
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étrica | Valor |
|---|---|
| Texto por delta | Máximo de 60.000 carateres |
| Texto total | Ilimitado |
| Sessões simultâneas | 50 por equipa |
| Permissão de sessão | 600 segundos |
| Tempo limite de ligação | Nenhum |
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.deltapara enviar texto,audio.deltapara 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