Mensagens WebSocket: texto e áudio
Nesta página
Atualizado a 3 de novembro de 2026, com base na página Text to Speech da xAI: deltas de até 60.000 carateres, cancelamento (
text.clear,audio.clear) e tabela de pronúncia (session.update,session.updated). Fonte: Text to Speech.
O protocolo de mensagens TTS
Assim que a ligação WebSocket estiver estabelecida, a comunicação funciona através da troca de mensagens JSON. O seu cliente envia texto e o servidor responde com áudio codificado em base64. Compreender este protocolo é essencial para implementar corretamente o streaming de TTS.
Mensagens do cliente para o servidor
A sua aplicação envia quatro tipos de mensagens para o servidor: text.delta e text.done para o texto, text.clear para cancelar e session.update para configurar.
text.delta: enviar um fragmento de texto
A mensagem text.delta envia um fragmento de texto para conversão. Pode enviar o texto em partes sucessivas:
{"type": "text.delta", "delta": "Hello, and welcome to "}
{"type": "text.delta", "delta": "our presentation on speech synthesis."}
Cada delta pode conter até 60.000 carateres, e o texto total não tem limite. O servidor começa a gerar áudio assim que tiver contexto suficiente para produzir uma pronúncia natural.
text.done: sinalizar o fim do texto
A mensagem text.done informa o servidor de que terminou o envio de texto para esta sequência:
{"type": "text.done"}
Assim que recebe esta mensagem, o servidor conclui a geração do áudio e envia uma mensagem audio.done. Pode então começar a enviar novos deltas para uma nova sequência.
text.clear: cancelar a sequência atual
text.clear cancela a sequência atual: o servidor para de gerar áudio, descarta o que tinha na memória e responde com audio.clear. A ligação fica imediatamente pronta para a próxima sequência, sem necessidade de novo handshake WebSocket; a xAI estima uma poupança de cerca de 600 ms para um cliente remoto. Este é o mecanismo de interrupção («barge-in») para quando o utilizador intervém.
{"type": "text.clear"}
session.update: corrigir a pronúncia
session.update instala ou substitui a tabela replace da ligação: cada frase encontrada no texto é trocada pela sua forma falada antes da síntese, sem alterar o texto que envia nem o número de carateres faturados. Envie-a antes do primeiro text.delta para que cubra toda a ligação; uma atualização recebida a meio de uma sequência só se aplica a partir da sequência seguinte.
{"type": "session.update", "replace": {"kubectl": "kube cuttle"}}
Mensagens do servidor para o cliente
O servidor responde com cinco tipos de mensagens: audio.delta, audio.done e error, detalhados abaixo, além de audio.clear, que confirma um cancelamento, e session.updated, que devolve a tabela replace em vigor.
audio.delta: um fragmento de áudio
A mensagem audio.delta contém um fragmento de áudio codificado em base64:
{
"type": "audio.delta",
"delta": "SUQzBAAAAAAAI1RTU0UAAAAPAAADTGF2ZjU4Ljc2..."
}
Cada delta é um pedaço de áudio válido que pode descodificar e reproduzir de imediato. Os deltas chegam à medida que a geração progride.
audio.done: geração concluída
A mensagem audio.done sinaliza que todo o áudio para a sequência de texto que enviou foi gerado:
{
"type": "audio.done",
"trace_id": "550e8400-e29b-41d4-a716-446655440000"
}
O trace_id é um ID único para a sequência, útil para depuração e rastreio.
error: ocorreu um erro
Se algo correr mal, o servidor envia uma mensagem de erro:
{
"type": "error",
"message": "Invalid text encoding"
}
O fluxo completo de comunicação
Eis como decorre uma sessão típica:
Client Server
| |
|-- text.delta ("Hello, ") ----->|
|-- text.delta ("how are ") ---->|
|-- text.delta ("you?") -------->|
|<-- audio.delta (chunk 1) -----|
|<-- audio.delta (chunk 2) -----|
|-- text.done ----------------->|
|<-- audio.delta (chunk 3) -----|
|<-- audio.done ----------------|
O servidor pode começar a enviar mensagens audio.delta antes mesmo de ter recebido text.done. Essa é exatamente a ideia do streaming: a geração começa o mais cedo possível.
Implementação completa em Python
import asyncio
import websockets
import json
import base64
async def stream_tts(api_key, text, voice="eve", language="en"):
uri = f"wss://api.x.ai/v1/tts?language={language}&voice={voice}&codec=mp3"
headers = {"Authorization": f"Bearer {api_key}"}
audio_chunks = []
async with websockets.connect(uri, additional_headers=headers) as ws:
# Enviar o texto em pedaços de 2.000 carateres
chunk_size = 2000
for i in range(0, len(text), chunk_size):
chunk = text[i:i + chunk_size]
await ws.send(json.dumps({
"type": "text.delta",
"delta": chunk
}))
# Sinalizar o fim do texto
await ws.send(json.dumps({"type": "text.done"}))
# Receber os pedaços de áudio
async for message in ws:
data = json.loads(message)
if data["type"] == "audio.delta":
audio_bytes = base64.b64decode(data["delta"])
audio_chunks.append(audio_bytes)
elif data["type"] == "audio.done":
print(f"Generation finished (trace: {data['trace_id']})")
break
elif data["type"] == "error":
raise Exception(f"TTS error: {data['message']}")
# Montar o áudio completo
return b"".join(audio_chunks)
Implementação em JavaScript (Node.js)
const WebSocket = require("ws");
function streamTTS(apiKey, text, voice = "eve", language = "en") {
return new Promise((resolve, reject) => {
const ws = new WebSocket(
`wss://api.x.ai/v1/tts?language=${language}&voice=${voice}&codec=mp3`,
{ headers: { Authorization: `Bearer ${apiKey}` } }
);
const audioChunks = [];
ws.on("open", () => {
// Enviar o texto
ws.send(JSON.stringify({ type: "text.delta", delta: text }));
ws.send(JSON.stringify({ type: "text.done" }));
});
ws.on("message", (raw) => {
const data = JSON.parse(raw);
if (data.type === "audio.delta") {
audioChunks.push(Buffer.from(data.delta, "base64"));
} else if (data.type === "audio.done") {
ws.close();
resolve(Buffer.concat(audioChunks));
} else if (data.type === "error") {
ws.close();
reject(new Error(data.message));
}
});
ws.on("error", reject);
});
}
Gestão de múltiplos deltas
Para texto gerado progressivamente (a saída de um LLM, por exemplo), envie cada token diretamente para o WebSocket de TTS:
async def llm_to_speech(ws_tts, llm_stream):
async for token in llm_stream:
await ws_tts.send(json.dumps({
"type": "text.delta",
"delta": token
}))
await ws_tts.send(json.dumps({"type": "text.done"}))
Esta arquitetura de «streaming de LLM para streaming de TTS» oferece a latência mais baixa possível: o utilizador ouve a resposta enquanto o LLM ainda está a gerar.
Pontos-chave
- Quatro mensagens do cliente:
text.delta(enviar texto),text.done(fim do texto),text.clear(cancelar) esession.update(tabelareplace) - Cinco mensagens do servidor:
audio.delta(um pedaço de áudio),audio.done(fim),audio.clear(cancelamento confirmado),session.updatedeerror - O áudio é codificado em base64 nas mensagens
audio.delta - O servidor começa a gerar antes de receber
text.done - Cada delta de texto está limitado a 60.000 carateres
- Encadear um LLM em streaming num TTS em streaming proporciona a menor latência