Ir al contenido principal
Español— Elegir un idioma
Menú

Mensajes WebSocket: texto y audio

Lección 10 de 14 Actualizado el 3 de noviembre de 2026 Desarrollador
En esta página
  1. El protocolo de mensajes TTS
  2. Mensajes de cliente a servidor
  3. Mensajes de servidor a cliente
  4. El flujo completo de comunicación
  5. Implementación completa en Python
  6. Implementación en JavaScript (Node.js)
  7. Gestión de múltiples deltas
  8. Puntos clave

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) y session.update (tabla replace)
  • Cinco mensajes de servidor: audio.delta (un fragmento de audio), audio.done (fin), audio.clear (cancelación confirmada), session.updated y error
  • 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