Integración de la API de Texto a Voz: streaming, procesamiento por lotes y reintentos

Integrar una API de Texto a Voz es sencillo… pero antes hay que tomar algunas decisiones: qué modo de transferencia usar, cómo elegir el modelo y el formato de salida, cómo hacer streaming, cómo gestionar grandes volúmenes sin superar el límite de concurrencia, cómo cachear y reintentar para no pagar dos veces por el mismo audio, y cómo comparar el tiempo hasta el primer byte con otro proveedor.

Para ayudarte con la integración de la API de Texto a Voz, hemos desglosado cada una de estas decisiones técnicas y qué hacer en cada caso. Esta guía te ayudará a integrar la API de Texto a Voz de ElevenLabs y escalar, con fragmentos de código listos para usar en producción.

Si quieres conocer los conceptos que mencionamos aquí, consulta nuestras guías sobre cómo funciona el streaming de audio, cómo optimizar la latencia y el resumen de modelos de ElevenLabs.

Resumen

• Hay una única ruta de API de Texto a Voz en ElevenLabs, a la que puedes acceder de tres formas: conversión por lotes, streaming HTTP y WebSocket con entrada por streaming.
• Por HTTP, cada petición en curso cuenta para tu límite de concurrencia, mientras que por WebSocket solo cuenta el tiempo en el que se está generando audio.
• Mantén el paralelismo justo por debajo del límite de tu plan y cachea un hash de cada parámetro que afecte al audio para no facturar dos veces el mismo texto.
• Reintenta los errores 429 y 5xx con backoff exponencial y jitter completo para evitar llegar al límite de concurrencia.

Tres formas de integrar la API de Texto a Voz

Solo hay una ruta de Texto a Voz, pero la forma en que la integres afecta a la latencia, la complejidad y el coste.

La misma llamada POST /v1/text-to-speech/{voice_id} funciona de tres maneras, cada una pensada para un caso distinto. Aquí tienes un resumen de las tres formas de integrar la API de Texto a Voz:

• Por lotes (convertir) es la integración más sencilla: Envías una petición y recibes una respuesta de audio. Es la opción más simple y la que más tarda en entregar el primer audio, porque se sintetiza el clip completo antes de devolver cualquier byte.
• El streaming HTTP (stream) mantiene la misma petición pero divide la respuesta en fragmentos: Añades /stream a la ruta, llamas al método de streaming y el audio llega en fragmentos. El código es casi igual y la latencia percibida es mucho menor.
• El WebSocket (stream-input) mantiene una conexión persistente: Envías el texto poco a poco y recibes fragmentos de audio a medida que se generan. Está pensado para agentes interactivos y para convertir la salida de un LLM en voz mientras se generan los tokens, antes de terminar la frase.

El streaming no hace que el modelo genere audio más rápido; el tiempo de inferencia es el mismo. Lo que cambia es cuándo recibes el primer fragmento: se envía antes de que termine el clip completo, así que la espera que percibe el usuario es menor aunque el trabajo total sea igual.

Tabla comparativa: procesamiento por lotes, streaming y WebSocket

Al elegir entre estos tres métodos, hay varios factores que debes tener en cuenta.

Como guía rápida: usa procesamiento por lotes para renderizado offline, streaming HTTP para texto conocido que espera un usuario y WebSocket para agentes y conversión en directo de LLM a voz.

La tabla siguiente resume las ventajas e inconvenientes de cada opción a gran escala.

Por HTTP, tanto en lotes como en streaming, cada petición en curso cuenta para el límite de concurrencia de tu plan durante toda su duración. Por WebSocket, solo cuenta el tiempo en el que el modelo está generando audio; una conexión abierta pero inactiva apenas consume recursos.

Para un agente de voz en cascada que mantiene la conexión abierta durante toda la conversación pero solo genera audio en los turnos del agente, esa diferencia es importante y es la principal razón para usar WebSockets al crear agentes. El protocolo completo está documentado en la guía de WebSocket de Texto a Voz en tiempo real.

Elegir modelo y formato de salida

Dos decisiones determinan el audio que recibes de tu integración con la API de Texto a Voz. Primero, el modelo, que define la calidad y la velocidad. Segundo, el formato de salida, que define el contenedor, el bitrate y la frecuencia de muestreo.

Elegir bien ambos desde el principio asegura que todo lo demás, como la latencia y la compatibilidad con telefonía, funcione correctamente.

Modelos

Ofrecemos varios modelos de Texto a Voz. No están ordenados de mejor a peor; cada uno tiene sus propios equilibrios.

El dato de ~75ms es el tiempo de inferencia del modelo en condiciones representativas, sin contar la latencia de red ni de la aplicación. Aumenta con entradas más largas y bajo carga. Mide siempre desde tu aplicación, no te fíes solo de los benchmarks.

Los modelos Flash son más pequeños y usan aproximaciones más agresivas para reducir el tiempo de inferencia. Eleven v3 y Multilingual v2 son modelos más grandes que dedican más tiempo por carácter para lograr un resultado más rico. No existe una configuración que te dé la calidad de Eleven v3 a la velocidad de Flash, porque esa calidad requiere más computación.

Para uso en tiempo real o con agentes, utiliza eleven_flash_v2_5; es la opción multilingüe con menor latencia. Para narración, audiolibros o locuciones de marketing, usa eleven_multilingual_v2 si buscas alta fidelidad estable, o eleven_v3 si necesitas máxima expresividad y rango emocional.

Cuando la pronunciación es importante, como en números de teléfono, fechas o monedas, normaliza tú mismo los números en tu aplicación antes de enviar el texto a la API. Escribe la forma hablada que quieres.

Normalizarlo tú mismo mantiene la pronunciación predecible entre modelos y evita depender de valores por defecto que pueden cambiar.

Formato de salida

El parámetro output_format controla el contenedor, la frecuencia de muestreo y el bitrate del audio que recibes. Los valores que más vas a usar:

Ajustes de voz

Los siguientes ajustes controlan cómo se entrega la voz generada:

• Stability: Controla la consistencia frente a la expresividad. Valores bajos generan una voz más variada y expresiva, mientras que valores altos producen una entonación más estable y predecible.
• SimilarityBoost: Controla lo parecida que es la voz generada a la voz de referencia.
• Style: Exagera el estilo natural de la voz al aumentar el valor.
• useSpeakerBoost: Aumenta la similitud con el hablante original a costa de una pequeña latencia.
• Speed: Ajusta la velocidad de la voz respecto al valor por defecto (1.0).

De todos estos ajustes, Stability suele ser el que más influye en la calidad percibida. Valores bajos generan voces más expresivas pero menos consistentes, mientras que valores altos priorizan la consistencia y la previsibilidad.

Al elegir una voz, la combinación de menor latencia es Flash junto con una clonación instantánea de voz o una voz por defecto; las Clonaciones Profesionales suenan muy bien pero añaden algo de latencia por cada generación.

En esta guía, el id de voz de ejemplo es JBFqnCBsd6RMkjVDRZzb (George).

Integración por streaming (HTTP y WebSocket)

En esta sección entramos en la parte práctica de la integración de la API de Texto a Voz. Verás cómo instalar el SDK, abrir un stream y consumir el audio a medida que llega. El método HTTP cubre la mayoría de casos de reproducción web y app, mientras que el WebSocket es ideal para agentes y salida en directo de LLM.

Ambos métodos asumen que ya tienes el cliente de ElevenLabs inicializado como se muestra abajo.

npm install @elevenlabs/elevenlabs-js

import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";

const elevenlabs = new ElevenLabsClient({
  apiKey: process.env.ELEVENLABS_API_KEY,
});

La integración por streaming abre un stream y consume los fragmentos según llegan. voiceId es el primer argumento, seguido de un objeto de opciones con claves en camelCase (modelId, outputFormat, voiceSettings):

const stream = await elevenlabs.textToSpeech.stream("JBFqnCBsd6RMkjVDRZzb", {
  text,
  modelId: "eleven_flash_v2_5",
  outputFormat: "mp3_44100_128",
  voiceSettings: { stability: 0, similarityBoost: 1.0, style: 0, useSpeakerBoost: true, speed: 1.0 },
});

for await (const chunk of stream) {
  // chunk is a Buffer; feed it to the player as it arrives
}

Para la variante WebSocket, conecta a wss://api.elevenlabs.io/v1/text-to-speech/{voice_id}/stream-input, envía un primer mensaje con tus ajustes de voz y un espacio inicial, luego envía mensajes de texto según estén disponibles y recibe frames JSON cuyo campo audio contiene los fragmentos codificados en base64.

Procesamiento por lotes y límites de concurrencia para alto rendimiento

La integración de alto rendimiento depende de la concurrencia, es decir, el número de peticiones generando audio al mismo tiempo. Cada plan tiene un límite por familia de modelos.

Cada plan incluye un límite de concurrencia distinto:

• Gratis: 4 peticiones Flash simultáneas.
• Starter: 6 peticiones Flash simultáneas.
• Creator: 10 peticiones Flash simultáneas.
• Pro: 20 peticiones Flash simultáneas.
• Scale y Business: 30 peticiones Flash simultáneas, con límites personalizados para Enterprise.

Los límites para Multilingual v2 son aproximadamente la mitad de los anteriores.

Un pool limitado ayuda a controlar esto, restringiendo cuántas peticiones se ejecutan a la vez:

// Set MAX_CONCURRENCY at or below your plan's Flash concurrency limit.
const MAX_CONCURRENCY = 8;

async function synthMany(texts: string[]): Promise<Buffer[]> {
  const results: Buffer[] = [];
  for (let i = 0; i < texts.length; i += MAX_CONCURRENCY) {
    const batch = texts.slice(i, i + MAX_CONCURRENCY);
    results.push(...(await Promise.all(batch.map(eachSingleRequest)))); // never more than MAX_CONCURRENCY in flight
  }
  return results;

Configura MAX_CONCURRENCY un poco por debajo del límite de tu plan, no justo en el máximo. Ese margen absorbe cualquier otro tráfico que use la misma clave y evita que llegues al punto en que recibes un 429.

Límites de caracteres y división de textos largos

Cada modelo tiene un máximo de caracteres por petición. Si vas a trabajar con textos largos, tendrás que dividirlos y unir el audio después.

Estos son los límites de caracteres por petición para cada modelo:

• Flash v2.5: Hasta 40.000 caracteres por petición.
• Flash v2: Hasta 30.000 caracteres por petición.
• Multilingual v2: Hasta 10.000 caracteres por petición.
• Eleven v3: Hasta 5.000 caracteres por petición.

Si el texto es más largo, tendrás que dividirlo en varias peticiones. Intenta cortar por frases para que la prosodia se mantenga entre fragmentos.

function splitText(text: string, maxChars: number): string[] {
  const sentences = text.trim().split(/(?<=[.!?])\s+/);
  const chunks: string[] = [];
  let current = "";
  for (let sentence of sentences) {
    if (current.length + sentence.length + 1 > maxChars) {
      if (current) chunks.push(current.trim());
      // A single sentence longer than the limit is hard-split.
      while (sentence.length > maxChars) {
        chunks.push(sentence.slice(0, maxChars));
        sentence = sentence.slice(maxChars);
      }
      current = sentence;
    } else {
      current = `${current} ${sentence}`.trim();
    }
  }
  if (current) chunks.push(current.trim());
  return chunks;
}

Genera los fragmentos en orden y concatena el audio. Para narraciones largas donde cada fragmento es independiente, basta con enviar la salida de splitText al pool limitado y dejar que gestione el resto.

Cacheo e idempotencia

El resultado de Texto a Voz es lo bastante determinista como para que volver a generar el mismo texto con la misma voz, modelo y ajustes sea un desperdicio. Cachea el resultado usando un hash de los parámetros que afectan al audio, y usa esa misma clave como token de idempotencia en los reintentos.

Así es como puedes hacerlo.

import { createHash } from "node:crypto";

function cacheKey(text: string, voiceId: string, modelId: string,
                  outputFormat: string, settings: object): string {
  // Every parameter that changes the audio must be in the key.
  const payload = JSON.stringify({ text, voiceId, modelId, outputFormat, settings });
  return createHash("sha256").update(payload).digest("hex");
}

async function cachedSynth(text: string, voiceId: string, modelId: string,
                           outputFormat: string, settings: object): Promise<Buffer> {
  const key = cacheKey(text, voiceId, modelId, outputFormat, settings);
  const cached = await cacheGet(key);          // e.g. read from disk or S3
  if (cached) return cached;

  const audio = await elevenlabs.textToSpeech.convert(voiceId, { text, modelId, outputFormat });
  await cachePut(key, audio);                   // store the bytes under the key
  return audio;
}

La clave es que todos los parámetros que cambian el audio deben estar en la clave del cacheo, incluyendo outputFormat y los ajustes de voz. Si lo haces bien, la misma clave sirve como token de idempotencia. Si un cliente reintenta una petición que ya tuvo éxito, devuelves los bytes cacheados en vez de generar de nuevo.

Gestión de errores y límites de velocidad (429)

Un cliente en producción necesita reintentos con backoff y jitter, además de gestionar cada código de estado de forma distinta, porque algunos errores merecen reintento y otros no.

La tabla siguiente asocia cada estado con la acción adecuada, y la sección explica por qué un 429 es un límite blando y no un muro infranqueable.

Un 429 no es un muro, y conviene entender el mecanismo. Si superas el límite de concurrencia, las peticiones primero se ponen en cola por prioridad, lo que suele añadir unos 50ms. Solo si sigues por encima de la capacidad recibes un 429.

La respuesta también incluye las cabeceras current-concurrent-requests y maximum-concurrent-requests, que muestran tu margen en tiempo real, así que puedes leerlas y reducir el ritmo antes de llegar al límite.

const RETRYABLE = new Set([429, 500, 502, 503, 504]);

async function synthWithRetry(text: string, voiceId: string, maxRetries = 5): Promise<Buffer> {
  let delay = 500; // ms, base for exponential backoff
  for (let attempt = 0; attempt <= maxRetries; attempt++) {
    try {
      return await elevenlabs.textToSpeech.convert(voiceId, {
        text, modelId: "eleven_flash_v2_5", outputFormat: "mp3_44100_128",
      });
    } catch (err: any) {
      const status = err.statusCode;
      // 401/422 and exhausted retries are not recoverable here.
      if (!RETRYABLE.has(status) || attempt === maxRetries) throw err;
      // Exponential backoff with full jitter.
      await new Promise((r) => setTimeout(r, Math.random() * delay));
      delay = Math.min(delay * 2, 8000);
    }
  }
  throw new Error("unreachable");
}

Si necesitas más margen en vez de mejores reintentos, amplía tu plan. Los clientes Enterprise pueden solicitar límites superiores a través de su gestor de cuenta.

Benchmarking de latencia y tiempo hasta el primer byte

La latencia depende de tu región, tu entrada y la carga actual, así que la única cifra fiable es la que midas tú mismo en tu entorno.

Esta sección te da el tiempo hasta el primer byte (TTFB) para el endpoint de streaming Flash, y está pensada para que puedas comparar con otro proveedor bajo las mismas condiciones.

Tómalo como una metodología, no como un resultado publicado. Ninguna ejecución garantiza nada.

Aquí tienes algunos detalles importantes al medir la latencia de una integración de API de Texto a Voz:

• Incluye el viaje de red completo: El TTFB depende de tu ubicación y del clúster más cercano del proveedor, así que haz la prueba desde donde suelen estar tus servidores.
• Descarta una ejecución de calentamiento: La primera petición en una conexión fría es más lenta y puede distorsionar los resultados.
• Mantén las entradas fijas: La longitud del texto, la voz, el modelo y la carga afectan al resultado, así que mantenlos idénticos entre proveedores.
• Publica una distribución: Los resultados varían en cada ejecución, así que publica la mediana y el p95 en vez de un solo valor.

Teniendo esto en cuenta, ya puedes hacer tus pruebas de benchmarking.

const TEXT = "This is a fixed benchmark sentence used for every provider.";

async function measureElevenLabs(): Promise<number> {
  const start = performance.now();
  const res = await fetch(
    "https://api.elevenlabs.io/v1/text-to-speech/JBFqnCBsd6RMkjVDRZzb/stream?output_format=mp3_44100_128",
    {
      method: "POST",
      headers: { "xi-api-key": process.env.ELEVENLABS_API_KEY!, "Content-Type": "application/json" },
      body: JSON.stringify({ text: TEXT, model_id: "eleven_flash_v2_5" }),
    },
  );
  for await (const _ of res.body!) {
    return performance.now() - start; // first chunk received
  }
  throw new Error("no audio returned");
}

Para comparar con otro proveedor, crea una función con la misma estructura. Luego ejecuta ambos con un pequeño runner que descarte una llamada de calentamiento, tome unas 20 muestras espaciadas para que no se solapen y publique la mediana y el p95 en milisegundos.

Una comparación justa depende de controlar las variables.

Ejecuta ambos proveedores desde la misma máquina y red, idealmente un servidor en la región donde vayas a desplegar, no un portátil en una red doméstica. Usa el mismo texto de entrada y mantén el audio corto para que la inferencia del modelo sea lo que más influya en el resultado. Publica la mediana y el p95 de muchas ejecuciones, porque una sola medición es ruido.

Recuerda que el TTFB por internet pública incluye entre 20 y 200ms de viaje de red que no dependen del modelo. Servimos desde clústeres en Norteamérica, Europa y el Sudeste Asiático y redirigimos al más cercano, así que sitúa tu cliente de pruebas en consecuencia, o estarás midiendo sobre todo la distancia al centro de datos.

Puntos clave para tu integración de la API de Texto a Voz

Una integración de la API de Texto a Voz en producción depende de unas pocas decisiones importantes.

Si aciertas en estas, todo lo demás encaja:

• Elige el modelo según el uso: Usa Flash v2.5 para cualquier caso interactivo y un modelo de mayor fidelidad como Multilingual v2 o Eleven v3 para renderizado offline donde la latencia no es tan importante.
• Haz streaming siempre que un usuario esté esperando: Usa streaming HTTP para texto conocido y WebSocket para agentes, así el tiempo inactivo no consume tu presupuesto de concurrencia.
• Ajusta el paralelismo al límite de tu plan: Limita las peticiones simultáneas justo por debajo del límite de tu plan y cachea usando un hash de cada parámetro que afecte al audio para no facturar dos veces el mismo audio.
• Reintenta 429 y 5xx con backoff exponencial y jitter completo: Haz backoff en 429 y 5xx con jitter completo y revisa las cabeceras de concurrencia para ver lo cerca que estás del límite.
• Divide los textos largos por frases: Corta por frases dentro del límite de caracteres de cada modelo para que la prosodia se mantenga.

Si quieres profundizar aún más, echa un vistazo a la guía práctica de streaming, el concepto de streaming de audio, autenticación y tokens de un solo uso para uso en cliente.

Crea tu integración de Texto a Voz con ElevenAPI

Después de leer esta guía, tienes todos los patrones que necesitas para una integración de la API de Texto a Voz en producción. Ya sea streaming, procesamiento por lotes, cacheo, reintentos o benchmarking, estás listo para ponerlo en marcha.

Empieza aprendiendo más sobre la API de Texto a Voz o regístrate para hacer tu primera llamada con ElevenAPI hoy mismo.

Preguntas frecuentes sobre la integración de la API de Texto a Voz