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

TTS en streaming por WebSocket

Lección 9 de 14 Actualizado el 3 de noviembre de 2026 Intermedio
En esta página
  1. Por qué el streaming cambia la experiencia
  2. Abrir la conexión
  3. El protocolo de mensajes
  4. Una implementación completa
  5. Límites a tener en cuenta
  6. HTTP o WebSocket
  7. Puntos clave

Actualizado el 3 de noviembre de 2026, basado en la página Text to Speech de xAI. Fuente: Text to Speech.

Por qué el streaming cambia la experiencia

En modo HTTP, la síntesis de voz (TTS) solo devuelve el control una vez generado todo el audio. Para una notificación de dos frases, nadie nota la espera. Sin embargo, para una entrada de blog, un capítulo de libro o un feed de noticias con desplazamiento continuo, esa espera se convierte en el mayor defecto de tu producto: los usuarios hacen clic y se quedan mirando un indicador de carga durante varios segundos.

El modo WebSocket elimina esa espera enviando el audio a medida que se sintetiza. La reproducción comienza con las primeras palabras, antes de que se haya procesado el final del texto. Esa es la diferencia entre una página que parece bloqueada y un audio que se reproduce de inmediato.

Abrir la conexión

La conexión se establece en wss://api.x.ai/v1/tts, y toda la configuración se incluye en la cadena de consulta de la URL, no en un mensaje de inicialización.

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
    }
  }
);

Estos son los parámetros aceptados:

  • language (obligatorio): un código BCP-47 o auto
  • voice (opcional, predeterminado: eve): el ID de la voz
  • codec (opcional, predeterminado: mp3): el formato de audio de salida
  • sample_rate (opcional, predeterminado: 24000): la frecuencia de muestreo en Hz
  • bit_rate (opcional, predeterminado: 128000): la tasa de bits en bps (solo MP3)

Estos ajustes se aplican a toda la sesión: no puedes cambiar la voz ni el códec sobre la marcha. Si tu aplicación necesita alternar entre dos narradores, abre dos conexiones.

El protocolo de mensajes

En el lado del envío, solo necesitas dos mensajes para controlar la síntesis. El primero envía un fragmento de texto; el segundo anuncia que el texto ha terminado.

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

Puedes enviar tantos mensajes text.delta como necesites, cada uno de hasta 60.000 caracteres. Aun así, es mejor no alcanzar ese límite: dividir el texto en fragmentos de unas pocas frases hace que el primer fragmento de audio llegue mucho antes, que es justamente el objetivo del streaming. Un único delta de varios miles de caracteres te devuelve al comportamiento del modo HTTP.

En el lado de la recepción, cada audio.delta transporta un fragmento de audio codificado en base64, en el códec que configuraste al conectar. Decodifícalo y añádelo a tu búfer de reproducción.

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

El evento audio.done marca el final de la síntesis. Su trace_id es el identificador que debes proporcionar al soporte técnico o registrar en tus logs cuando una generación falla. Si el texto no es válido o has superado tu cuota, recibirás un mensaje de error en su lugar.

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

Una implementación completa

El siguiente ejemplo divide un texto largo en párrafos, los envía todos y luego ensambla los fragmentos de audio recibidos en un archivo 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();
  }
});

Observa el para + " ": sin ese espacio, el final de un párrafo se une al inicio del siguiente, y el motor lee las dos palabras juntas sin hacer una pausa.

Límites a tener en cuenta

MétricaValor
Texto por deltaMáximo 60.000 caracteres
Texto totalIlimitado
Sesiones simultáneas50 por equipo
Permiso de sesión600 segundos
Tiempo de espera de conexiónNinguno

La página de xAI indica que la conexión no tiene tiempo de espera y menciona por separado un «permiso de sesión» de 600 segundos sin explicar qué ocurre cuando este se agota. Por seguridad, conecta solo cuando tengas texto que enviar, no cuando se cargue la página, y planifica la reconexión. Gestiona el límite de 50 sesiones simultáneas por equipo de la misma manera: una biblioteca de audio que convierta su catálogo en segundo plano debería poner sus trabajos en cola en lugar de abrir doscientas conexiones en paralelo.

HTTP o WebSocket

El modo HTTP sigue siendo la opción correcta para textos cortos, generaciones puntuales y cualquier caso donde la simplicidad de integración sea lo más importante: una solicitud, una respuesta, sin estado que gestionar. WebSocket es el camino a seguir cuando el texto es largo, cuando el audio debe reproducirse mientras se genera o cuando el propio contenido llega como un flujo, típicamente la salida de un modelo de lenguaje que conviertes a voz a medida que se genera.

Puntos clave

  • El TTS por WebSocket te permite recibir audio en streaming sin esperar a que termine la generación
  • Los parámetros de configuración van en la cadena de consulta de la URL de conexión
  • El protocolo es sencillo: text.delta para enviar texto, audio.delta para recibir audio
  • Las sesiones WebSocket están limitadas a 50 simultáneas por equipo; planifica la reconexión
  • Prefiere WebSocket para textos largos y experiencias de escucha en tiempo real