Mensajes WebSocket: texto y audio
En esta página
Actualizado el 3 de noviembre de 2026, según la página Text to Speech de xAI: deltas de hasta 60.000 caracteres, cancelación (
text.clear,audio.clear) y tabla de pronunciación (session.update,session.updated). Fuente: Text to Speech.
El protocolo de mensajes TTS
Una vez establecida la conexión WebSocket, la comunicación funciona mediante el intercambio de mensajes JSON. Tú envías texto y el servidor responde con audio codificado en base64. Comprender este protocolo es esencial para implementar correctamente la transmisión (streaming) de TTS.
Mensajes de cliente a servidor
Tu aplicación envía cuatro tipos de mensajes al servidor: text.delta y text.done para el texto, text.clear para cancelar y session.update para configurar.
text.delta: enviar un fragmento de texto
El mensaje text.delta envía un fragmento de texto para convertir. Puedes enviar el texto en trozos sucesivos:
{"type": "text.delta", "delta": "Hello, and welcome to "}
{"type": "text.delta", "delta": "our presentation on speech synthesis."}
Cada delta puede contener hasta 60.000 caracteres, y el texto total no tiene límite. El servidor comienza a generar audio en cuanto dispone de contexto suficiente para producir una pronunciación natural.
text.done: indicar el final del texto
El mensaje text.done informa al servidor de que has terminado de enviar texto para esta secuencia:
{"type": "text.done"}
Una vez recibido este mensaje, el servidor termina de generar el audio y envía un mensaje audio.done. A partir de ese momento, puedes empezar a enviar nuevos deltas para una secuencia diferente.
text.clear: cancelar la secuencia actual
text.clear cancela la secuencia actual: el servidor deja de generar audio, descarta lo que tenía en memoria y responde con audio.clear. La conexión queda lista inmediatamente para la siguiente secuencia, sin necesidad de un nuevo handshake de WebSocket; xAI estima un ahorro de unos 600 ms para un cliente remoto. Este es el mecanismo de interrupción («barge-in») para cuando el usuario interviene.
{"type": "text.clear"}
session.update: corregir la pronunciación
session.update instala o reemplaza la tabla replace de la conexión: cada frase encontrada en el texto se sustituye por su forma hablada antes de la síntesis, sin modificar el texto que envías ni el número de caracteres por los que se te factura. Envíalo antes del primer text.delta para que cubra toda la conexión; una actualización recibida a mitad de una secuencia solo se aplicará a partir de la siguiente.
{"type": "session.update", "replace": {"kubectl": "kube cuttle"}}
Mensajes de servidor a cliente
El servidor responde con cinco tipos de mensajes: audio.delta, audio.done y error, detallados a continuación, además de audio.clear, que confirma una cancelación, y session.updated, que devuelve la tabla replace en vigor.
audio.delta: un fragmento de audio
El mensaje audio.delta contiene un fragmento de audio codificado en base64:
{
"type": "audio.delta",
"delta": "SUQzBAAAAAAAI1RTU0UAAAAPAAADTGF2ZjU4Ljc2..."
}
Cada delta es un fragmento de audio válido que puedes decodificar y reproducir de inmediato. Los deltas llegan a medida que avanza la generación.
audio.done: generación finalizada
El mensaje audio.done indica que se ha generado todo el audio correspondiente a la secuencia de texto que enviaste:
{
"type": "audio.done",
"trace_id": "550e8400-e29b-41d4-a716-446655440000"
}
El trace_id es un identificador único para la secuencia, útil para la depuración y el seguimiento.
error: se ha producido un error
Si algo sale mal, el servidor envía un mensaje de error:
{
"type": "error",
"message": "Invalid text encoding"
}
El flujo completo de comunicación
Así es como transcurre una sesión 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 ----------------|
El servidor puede empezar a enviar mensajes audio.delta antes incluso de que hayas enviado text.done. Esa es la idea central de la transmisión: la generación comienza lo antes posible.
Implementación completa en 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 el texto en trozos de 2.000 caracteres
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
}))
# Indicar el final del texto
await ws.send(json.dumps({"type": "text.done"}))
# Recibir los fragmentos de audio
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"Generación finalizada (trace: {data['trace_id']})")
break
elif data["type"] == "error":
raise Exception(f"Error de TTS: {data['message']}")
# Ensamblar el audio completo
return b"".join(audio_chunks)
Implementación en 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 el 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);
});
}
Gestión de múltiples deltas
Para texto generado progresivamente (la salida de un LLM, por ejemplo), envía cada token directamente al 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 arquitectura de «transmisión de LLM a transmisión de TTS» ofrece la menor latencia posible: el usuario oye la respuesta mientras el LLM aún está generando.
Puntos clave
- Cuatro mensajes de cliente:
text.delta(enviar texto),text.done(fin del texto),text.clear(cancelar) ysession.update(tablareplace) - Cinco mensajes de servidor:
audio.delta(un fragmento de audio),audio.done(fin),audio.clear(cancelación confirmada),session.updatedyerror - El audio va codificado en base64 en los mensajes
audio.delta - El servidor empieza a generar antes de recibir
text.done - Cada delta de texto tiene un límite de 60.000 caracteres
- Encadenar un LLM en streaming con un TTS en streaming proporciona la menor latencia