Documentación técnica de la API de texto a voz

Por Equipo editorial VozHumana · Actualizado 2026-11-19

Esta documentación técnica explica cómo integrar nuestra API de texto a voz en tus sistemas de call center. Encontrarás la estructura exacta de las solicitudes, los parámetros necesarios y ejemplos prácticos para generar audio IVR con voces masculinas claras y naturales.

Aquí aprenderás a obtener tu clave API, a configurar el endpoint principal y a manejar errores comunes. Incluye instrucciones para usar el SDK de OpenAI, gestionar límites de velocidad y entender los formatos de salida disponibles, todo enfocado en escalar tus llamadas sin complicaciones.

Documentación técnica de la API de texto a voz

Preguntas frecuentes

¿Qué modelo de voz debo usar para call centers?

Para call centers, las voces masculinas atlas (neutral, ideal para noticias o información general) o milo (amigable, conversacional) son opciones adecuadas. Ambas están optimizadas para claridad en IVR. Puedes ajustar la velocidad entre 0.25 y 4.0 para adaptarte al flujo de llamadas de tu equipo sin perder naturalidad.

¿Es compatible la API con Python o Node.js?

Sí, puedes usar la API con Python y Node.js mediante la SDK de OpenAI o HTTP estándar. Utiliza el mismo formato de solicitud que la API de OpenAI, por lo que puedes usar los SDK oficiales de OpenAI modificando la base_url a https://api.vipclubmm.info/v1 y usando tu clave API para las autenticaciones.

¿Cómo manejo textos mayores a 4096 caracteres?

Debes dividir el texto en partes de hasta 4096 caracteres por solicitud. Genera el audio para cada fragmento individualmente y luego une los archivos de audio resultantes en tu aplicación para crear el archivo final completo. Esto asegura que cada solicitud cumpla con los límites de la API.

¿Qué significa el código de error 429?

El código 429 indica que has excedido el límite de velocidad de 60 solicitudes por minuto para tu clave API. Si acabas de crear la cuenta, el límite es de 10 solicitudes por minuto. Debes esperar a que el contador se reinicie o realizar una recarga para aumentar la capacidad.

¿Puedo cambiar la velocidad de la voz en tiempo real?

Puedes establecer la velocidad entre 0.25 y 4.0 en cada solicitud, pero no es un ajuste en tiempo real durante la reproducción. Debes especificar el parámetro speed al enviar el texto. Si necesitas una velocidad diferente, debes enviar una nueva solicitud con el valor ajustado.

¿Se requiere SSL para las llamadas a la API?

Sí, se recomienda el uso de HTTPS para asegurar la transmisión de datos. La API está disponible en https://api.vipclubmm.info/v1, lo que garantiza el uso de SSL/TLS para proteger tu clave API y los datos enviados en el cuerpo de la solicitud JSON.

¿Cómo se detecta el idioma automáticamente?

Si no especificas el idioma, el sistema lo adivina basándose en el guion del texto. El texto en latín se predice por defecto como inglés. Para textos en otros idiomas con caracteres latinos, debes establecer explícitamente el parámetro language con el código ISO para evitar errores de pronunciación.

¿Qué formato es mejor para IVR?

Para IVR, mp3 o wav son opciones comunes. mp3 es eficiente en ancho de banda, mientras que wav ofrece calidad sin pérdida. Puedes elegir entre mp3, wav, opus, flac o pcm según tus necesidades de almacenamiento y compatibilidad con tu sistema telefónico. Todos son válidos para integración.

¿La API soporta audio en tiempo real?

No, la API no soporta streaming ni audio en tiempo real. Devuelve el archivo de audio completo una vez que la síntesis termina. Las solicitudes se procesan secuencialmente, por lo que puede haber una cola bajo carga. No hay WebSockets ni transmisión parcial de audio disponible.

¿Cómo se genera una nueva clave API?

Puedes emitir una nueva clave API en cualquier momento desde tu panel de cuenta. Al generar una nueva, la clave anterior deja de funcionar inmediatamente. Esto te permite rotar las credenciales si es necesario sin interrupciones prolongadas en tus servicios de texto a voz.

¿Qué pasa si el servidor está ocupado?

Las solicitudes se procesan una tras otra. Bajo carga, tu solicitud puede esperar en una cola. La velocidad típica es de aproximadamente 25 caracteres por segundo. Si hay mucha demanda, la generación de audio puede tardar más que el tiempo real del texto.

¿Se puede usar la API desde un script bash?

Sí, puedes usar la API desde un script bash mediante curl. La documentación incluye ejemplos listos para usar con curl, permitiendo enviar solicitudes POST con el cuerpo JSON necesario para generar audio. Es una forma sencilla de integrar la API en procesos automatizados o scripts básicos.

¿Cuántas voces masculinas hay disponibles?

Hay cuatro voces masculinas disponibles: felix (enérgica), milo (amigable), atlas (neutral) y orion (profunda). Estas voces están diseñadas para diferentes contextos, desde promociones hasta documentales, y pueden hablar en cualquiera de los 23 idiomas soportados por la API sin necesidad de cambiar el modelo.

¿El audio generado tiene marca de agua?

Sí, cada archivo de audio generado lleva una marca de agua inaudible que lo identifica como voz sintética. Esto ayuda a distinguir el contenido generado por la API de las grabaciones humanas. La marca de agua es parte del archivo de audio sin afectar la calidad audible.

Primera solicitud

curl

curl https://api.vipclubmm.info/v1/audio/speech \
  -H "Authorization: Bearer $TTS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"tts-1","voice":"aria","input":"Hello from the API.","response_format":"mp3"}' \
  --output hello.mp3

Python (openai)

from openai import OpenAI

client = OpenAI(base_url="https://api.vipclubmm.info/v1", api_key="tts-...")

with client.audio.speech.with_streaming_response.create(
    model="tts-1", voice="nova", input="Hello from Python.", response_format="mp3"
) as response:
    response.stream_to_file("hello.mp3")

Node.js (openai)

import OpenAI from "openai";
import fs from "node:fs";

const client = new OpenAI({ baseURL: "https://api.vipclubmm.info/v1", apiKey: process.env.TTS_API_KEY });
const res = await client.audio.speech.create({ model: "tts-1", voice: "milo", input: "Hello from Node.js." });
fs.writeFileSync("hello.mp3", Buffer.from(await res.arrayBuffer()));
voice
ariafemenino
novafemenino
lunafemenino
sagefemenino
felixmasculino
milomasculino
atlasmasculino
orionmasculino
language
arالعربية
zh中文
daDansk
nlNederlands
enEnglish
fiSuomi
frFrançais
deDeutsch
elΕλληνικά
heעברית
hiहिन्दी
itItaliano
ja日本語
ko한국어
msBahasa Melayu
noNorsk
plPolski
ptPortuguês
ruРусский
esEspañol
swKiswahili
svSvenska
trTürkçe

Obtención de clave API

Ilustración de onda de sonido para: Obtención de clave API

Para utilizar la API, registra una cuenta en la página /get-api-key/ mediante Google o correo electrónico. El registro es inmediato y te permite generar tu primera clave de acceso sin configuraciones complejas.

Registro en la plataforma

Registro en la plataforma

Inicia sesión con tu cuenta de Google o crea una con email y contraseña. Una vez registrado, tendrás acceso al panel donde se gestionan tus credenciales y el saldo.

Ubicación de la clave

Ubicación de la clave

Toda la información esencial, incluida tu clave API activa, se encuentra en la sección /get-api-key/. Allí verás también tu saldo actual, el crédito de prueba si aplica y un ejemplo de cURL listo para usar.

  • La clave comienza con el prefijo tts-.

Emisión de nueva clave

Puedes generar una nueva clave en cualquier momento desde tu panel de control. Este proceso es útil para rotar credenciales o revocar acceso a dispositivos específicos sin afectar tu cuenta.

Invalidación inmediata

Al emitir una nueva clave, la anterior deja de funcionar de forma instantánea. Esto asegura que solo la credencial activa pueda realizar solicitudes a la API, manteniendo tu servicio seguro.

Endpoint principal de síntesis

Ilustración de onda de sonido para: Endpoint principal de síntesis

El endpoint principal de síntesis es el núcleo de la API de VozHumana. Permite convertir texto en archivos de audio listos para integrarse en tus flujos de IVR o aplicaciones de call center mediante una única llamada HTTP.

La estructura sigue el formato de la API de OpenAI, facilitando la conexión con tus sistemas actuales mediante el SDK oficial de OpenAI o HTTP estándar.

Método POST

Envía los parámetros de síntesis utilizando el método HTTP POST. Este método asegura que los datos del cuerpo de la solicitud se procesen correctamente para generar el audio solicitado.

URL del endpoint

La dirección base para todas las solicitudes de audio es: https://api.vipclubmm.info/v1/audio/speech. Esta URL es el punto de entrada único para recibir los archivos de voz sintetizados.

Cabecera de autenticación

Incluye tu clave API en la cabecera de la solicitud. Esto garantiza que tu cuenta tenga los permisos necesarios y que el consumo se registre correctamente en tu balance.

  • Authorization: Bearer tts-tu_clave_aqui

Cuerpo de la solicitud

El cuerpo debe ser un objeto JSON que contenga el texto a convertir, el modelo de voz seleccionado, la voz masculina específica y el formato de audio deseado. Asegúrate de que el texto no supere los 4096 caracteres por solicitud.

  • model: "tts-1" o "tts-1-hd"
  • input: texto a sintetizar
  • voice: voz masculina seleccionada
  • response_format: mp3, wav, opus, flac o pcm

Parámetros de la solicitud

Ilustración de onda de sonido para: Parámetros de la solicitud

La API de VozHumana acepta una estructura JSON clara que se ajusta al estándar utilizado por las SDKs de OpenAI. Cada solicitud debe especificar el motor de síntesis, el texto a convertir y la voz deseada para garantizar que el resultado cumpla con los requisitos técnicos de tu IVR.

Los parámetros principales definen la calidad del audio, la longitud del texto y el formato de entrega. Puedes ajustar la velocidad de reproducción entre 0.25x y 4.0x para sincronizar la voz con tus flujos de llamada, eligiendo entre los formatos disponibles para optimizar el ancho de banda.

subs": ["Modelo tts-1 y tts-1-hd", "Campo input con texto", "Voz masculina seleccionada", "Formato de respuesta"],

image": "Close-up of a server rack with soft blue LED lights, representing cloud API infrastructure, clean and professional, shallow depth of field"

Ejemplo con cURL

Ilustración de onda de sonido para: Ejemplo con cURL

Este ejemplo demuestra una solicitud básica para generar audio IVR. Envía texto breve y recibe un archivo de audio listo para integrarse en tu sistema de llamadas.

Reemplaza la clave API con la que obtuviste en /get-api-key/. El comando devuelve el archivo de audio binario directamente en la consola o lo guarda en disco.

Código de ejemplo

Usa este comando para sintetizar un mensaje de bienvenida. Ajusta la voz masculina según tu necesidad, como 'atlas' para noticias o 'milo' para conversación.

  • curl -X POST https://api.vipclubmm.info/v1/audio/speech \
  • -H "Authorization: Bearer tts-tu_clave_aqui" \
  • -H "Content-Type: application/json" \
  • --data '{"model": "tts-1", "input": "Bienvenido a nuestro servicio de atención al cliente.", "voice": "atlas", "response_format": "mp3"}' \
  • -o saludo.mp3

Reemplazo de clave

La clave comienza con 'tts-'. Cámbiala por la activa en tu panel. Si emites una nueva clave, la anterior deja de funcionar al instante.

Salida de audio

El archivo generado es un audio sintetizado con marca de agua invisible. Se guarda como 'saludo.mp3' por defecto en este ejemplo.

Códigos de estado

200 indica éxito. 401 si la clave es inválida. 429 si excediste los 60 requests por minuto. 500 para fallos internos del servicio.

Uso con SDK de OpenAI

Ilustración de onda de sonido para: Uso con SDK de OpenAI

La API de VozHumana sigue la misma estructura de solicitud que el endpoint de speech de OpenAI, lo que permite reutilizar el código existente en tus aplicaciones. Solo necesitas ajustar la URL base para apuntar a nuestros servidores y usar tu clave de API personalizada.

Cambio de base_url

Configura la variable base_url de tu SDK para que apunte a https://api.vipclubmm.info/v1. Esto redirige todas las llamadas al motor de síntesis de VozHumana sin modificar la lógica de tu código.

Instalación del SDK

Instala el paquete de la SDK de OpenAI para tu lenguaje de programación preferido. Es el único cliente necesario, ya que la estructura del JSON es compatible nativamente.

Configuración de clave

Incluye tu clave API en la cabecera de autorización. Usa el formato Authorization: Bearer tts-... para autenticar cada solicitud de generación de audio.

Llamada al método

Invoca el método de generación de voz pasando el texto, la voz masculina deseada y el formato de salida. El SDK manejará la serialización y la respuesta de audio.

Uso con SDK de OpenAI

Manejo de errores

Ilustración de onda de sonido para: Manejo de errores

La API devuelve códigos HTTP estándar para indicar el estado de cada solicitud. Un código 200 significa que el audio se generó correctamente. Los códigos 4xx indican errores del cliente, como parámetros inválidos o falta de autenticación.

Los errores 5xx señalan problemas internos. En caso de fallo durante la síntesis, no se cobra el crédito y puedes reintentar la solicitud sin penalización.

Códigos HTTP comunes

Utilizamos estándares REST claros. Un 200 OK confirma la entrega del archivo de audio. Un 400 Bad Request indica que el cuerpo de la solicitud no cumple con el formato JSON esperado o contiene datos fuera de rango.

Un 401 Unauthorized aparece si la clave es incorrecta. Un 429 Too Many Requests señala que has excedido el límite de 60 solicitudes por minuto. Los errores 500 indican fallos temporales del servidor.

  • 200: Éxito, audio disponible.
  • 400: Formato de solicitud inválido.
  • 401: Clave API incorrecta o inválida.
  • 429: Límite de velocidad excedido.
  • 500: Error interno del servidor.

Errores de autenticación

Si la cabecera Authorization no contiene una clave válida con el prefijo 'tts-', la API rechaza la solicitud. Asegúrate de que tu clave comience por 'tts-' y esté copiada correctamente sin espacios adicionales.

Si emites una nueva clave en tu panel, la anterior deja de funcionar inmediatamente. Si ves un error 401 tras cambiar tu clave, verifica que estés usando la versión más reciente.

  • Usa 'Authorization: Bearer tts-...'.
  • La clave debe estar activa en tu cuenta.
  • Las claves viejas se invalidan al emitir una nueva.

Límites excedidos

El límite es de 60 solicitudes por minuto por clave API. Si excedes este límite, recibirás un código 429. Antes de tu primera recarga, el límite es de 10 solicitudes por minuto.

Las solicitudes fallidas no cuentan como consumidas para tu saldo, pero sí ocupan un slot en tu límite de velocidad mientras se procesan. Espera unos segundos antes de reintentar.

  • Límite estándar: 60 req/min.
  • Límite inicial: 10 req/min.
  • Las solicitudes fallidas no cobran saldo.

Errores de formato

El campo input debe ser una cadena de texto válida. Si excedes los 4096 caracteres, la API puede rechazar la solicitud o devolver un error. Dividiendo el texto en partes más cortas, aseguras una generación correcta.

El campo voice debe ser uno de los valores permitidos. Si usas un formato de respuesta no soportado o una velocidad fuera del rango 0.25–4.0, la solicitud será rechazada con un error 400.

Asegúrate de que el cuerpo de la solicitud sea JSON válido. Los errores de sintaxis JSON son comunes al copiar y pegar ejemplos de código.

  • Máximo 4096 caracteres por solicitud.
  • Velocidad entre 0.25 y 4.0.
  • Formatos válidos: mp3, wav, opus, flac, pcm.

Límites y rendimiento

Ilustración de onda de sonido para: Límites y rendimiento

La API de VozHumana está diseñada para escalar el volumen de llamadas IVR manteniendo la estabilidad. Conocer sus límites de velocidad y tiempo de respuesta es clave para integrar la síntesis de voz en flujos de trabajo automatizados sin interrupciones.

Este apartado detalla cómo se gestionan las peticiones simultáneas y cómo se optimiza el uso del servicio para equipos de call centers que requieren consistencia en la entrega de audios masculinos claros.

60 solicitudes por minuto

Cada clave API tiene un límite de 60 solicitudes por minuto. Este umbral permite un flujo constante de generación de audio sin saturar los servidores. Antes de la primera recarga, el límite es de 10 solicitudes por minuto.

  • Límite estándar: 60 req/min por clave.
  • Acceso inicial: 10 req/min antes del primer recargo.
  • Un límite de 60 solicitudes por minuto por clave API.

Cola de procesamiento

Las solicitudes se procesan en orden secuencial. Si superas el límite o el sistema está bajo carga, tu petición se colocará en una cola de espera hasta que esté disponible un recurso. Esto garantiza que no se pierdan datos, aunque el tiempo de respuesta pueda variar ligeramente en picos de uso.

Tiempo de generación

La velocidad de síntesis es aproximadamente en tiempo real: se generan unos 25 caracteres de texto por cada segundo de audio resultante. Para frases cortas, la generación puede tardar unos pocos segundos adicionales debido a la inicialización del motor. Para textos largos, el procesamiento se alinea con la duración del audio.

Textos largos divididos

El límite máximo por solicitud es de 4096 caracteres. Si tu texto para el IVR excede esta longitud, debes dividirlo manualmente en partes y unir los archivos de audio resultantes. Cada parte se genera como un archivo independiente que luego puedes concatenar en tu pipeline de llamadas.

  • Máximo: 4096 caracteres por petición.
  • Espacios y puntuación cuentan como caracteres.
  • Unión manual de archivos de audio.

Voces y formatos disponibles

Ilustración de onda de sonido para: Voces y formatos disponibles

Esta sección detalla las opciones de voz masculina, formatos de audio, velocidad de reproducción e idiomas disponibles para tu integración de IVR.

Utiliza estos parámetros para adaptar la síntesis a las necesidades específicas de tus llamadas automatizadas y garantizar una experiencia de usuario clara.

Listado de voces masculinas

Selecciona entre cuatro voces masculinas diseñadas para diferentes contextos de llamada.

Felix ofrece un tono energético ideal para promociones. Milo suena amigable y conversacional para interacciones generales. Atlas proporciona una voz neutral y clara, perfecta para noticias o avisos. Orion cuenta con un tono profundo, adecuado para documentales o mensajes institucionales.

  • Felix: energético, promo
  • Milo: amigable, conversacional
  • Atlas: neutral, noticias
  • Orion: profundo, documental

Formatos MP3, WAV, FLAC

La API devuelve el audio en los formatos mp3, wav, opus, flac o pcm. Cada archivo generado incluye una marca de agua inaudible que lo identifica como voz sintética.

Estos formatos son compatibles con la mayoría de las plataformas de PBX y sistemas de IVR actuales.

  • mp3
  • wav
  • opus
  • flac
  • pcm

Velocidad variable

Ajusta la velocidad de reproducción entre 0.25 y 4.0 para controlar la duración y claridad de los mensajes.

Esta flexibilidad permite optimizar el tiempo de llamada en IVR sin perder la inteligibilidad del contenido.

Idiomas soportados

Las voces pueden hablar en 23 idiomas, incluyendo inglés, español, alemán, francés, italiano, portugués, ruso, chino, japonés, coreano, árabe, hindi y turco, entre otros.

Si el texto está en latín pero no es inglés, establece el parámetro language para evitar que se adivine erróneamente.

  • Arabic
  • Chinese
  • Danish
  • Dutch
  • English
  • Spanish

Escucha las 8 voces

Cada muestra a continuación fue generada por esta API a partir de la misma frase. Estas distinciones vocales permiten adaptar el mensaje a la urgencia o calma de la llamada.

Avatar de la voz aria
ariafemenino
Avatar de la voz nova
novafemenino
Avatar de la voz luna
lunafemenino
Avatar de la voz sage
sagefemenino
Avatar de la voz felix
felixmasculino
Avatar de la voz milo
milomasculino
Avatar de la voz atlas
atlasmasculino
Avatar de la voz orion
orionmasculino

23 idiomas

Cualquier voz puede hablar cualquiera de estos idiomas.

Fuentes y lecturas adicionales

  1. Wikipedia
  2. ISO 639 language codes
  3. openai-node on GitHub
  4. FFmpeg documentation
  5. Node.js documentation
  6. curl documentation
  7. OpenAI API reference: create speech
  8. LibriVox public-domain audiobooks
  9. MDN: Web Speech API
  10. openai-python on GitHub
  11. LibriTTS-R paper (arXiv 2305.18802)
  12. Tether (USDT)

Más en este sitio