Integra nuestra API de Texto a Voz en tu aplicación

Por Equipo editorial de VozCentral · Actualizado 2026-11-18

Esta documentación técnica está diseñada para equipos de producto que integran síntesis de voz en flujos de trabajo de centros de contacto y sistemas IVR. Aquí encontrarás los detalles precisos para conectar nuestra API a tu infraestructura, desde la autenticación hasta el manejo de respuestas binarias, sin suposiciones ni características inventadas.

Utiliza los endpoints descritos para generar audio a partir de texto mediante solicitudes HTTP estándar. La guía cubre la selección de voces, formatos de salida y límites de uso, asegurando que puedas escalar la generación de audio de manera predecible y compatible con las librerías existentes, como el SDK de OpenAI (usando la URL base de la API).

Integra nuestra API de Texto a Voz en tu aplicación

Preguntas frecuentes

¿Cómo obtengo mi clave API para la integración?

Regístrate en /get-api-key/ con Google o correo electrónico. La página muestra tu clave única, saldo y un ejemplo curl listo para usar. La autenticación se realiza con el encabezado Authorization: Bearer tts-... Puedes emitir una nueva clave en cualquier momento; la anterior deja de funcionar inmediatamente.

¿Qué formato de audio es mejor para sistemas IVR antiguos?

Para máxima compatibilidad con sistemas IVR legacy, utiliza el formato wav. También puedes elegir mp3, opus, flac o pcm según tus necesidades de compresión. El endpoint acepta cualquiera de estas opciones en el campo response_format del cuerpo JSON de la solicitud POST.

¿Puedo usar la librería oficial de OpenAI con esta API?

Sí, la forma de la solicitud es idéntica al endpoint de speech de OpenAI. Solo necesitas cambiar la base_url a https://api.playyk1.com/v1 y utilizar tu propia clave API. Las librerías oficiales de OpenAI funcionan correctamente con esta configuración sin modificaciones adicionales.

¿Cuál es el límite máximo de caracteres por solicitud?

El límite máximo es de 4096 caracteres por solicitud. Si tu texto excede este límite, debes dividirlo en partes y unir los archivos de audio resultantes. Los espacios y la puntuación cuentan como caracteres. Los modelos tts-1 y tts-1-hd comparten este límite.

¿Qué ocurre si excedo los 60 requests por minuto?

El límite es de 60 solicitudes por minuto por clave (10 antes del primer recargo). Si excedes este límite, las solicitudes se procesarán en cola uno tras otro, lo que incrementará la latencia.

¿Cómo especifico el idioma si el texto es en inglés?

Si el texto está en inglés, no es necesario especificar el idioma; el sistema lo detectará automáticamente. Sin embargo, puedes incluir el parámetro language con el código ISO si deseas forzarlo. Para otros idiomas en latín, es recomendable establecer el campo language explícitamente.

¿Se puede cambiar la velocidad de la voz en tiempo real?

No hay streaming ni WebSocket para cambios en tiempo real. La velocidad se configura en cada solicitud mediante el parámetro speed (0.25–4.0). Cada generación es un archivo de audio independiente. No se pueden modificar los parámetros de una generación ya iniciada.

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

El código 429 indica que has excedido el límite de 60 solicitudes por minuto. Las solicitudes se ponen en cola y se procesan secuencialmente.

¿Las voces requieren un modelo específico para ciertos idiomas?

No. Las ocho voces pueden hablar cualquiera de los 23 idiomas soportados. No hay asignación específica de voz a idioma. Puedes elegir cualquier voz para cualquier idioma disponible, como inglés, español, japonés o alemán, sin restricciones de compatibilidad entre voz y idioma.

¿Cómo manejan los textos que superan los 4096 caracteres?

Debes dividir el texto en partes de hasta 4096 caracteres cada una y realizar múltiples solicitudes. Luego, une los archivos de audio generados. El sistema no realiza esta división automáticamente; es responsabilidad del cliente gestionar la segmentación y la concatenación de los resultados.

¿Es necesario enviar el modelo 'tts-1-hd' para mejor calidad?

No es necesario. Los modelos tts-1 y tts-1-hd utilizan el mismo motor y tienen el mismo precio. La selección del modelo no afecta el costo ni la infraestructura subyacente. Puedes elegir cualquiera de los dos indistintamente según tu preferencia de nomenclatura o compatibilidad.

¿Cómo se ve una respuesta exitosa de la API?

Una respuesta exitosa devuelve el archivo de audio directamente en el cuerpo de la respuesta. El formato depende del campo response_format solicitado (mp3, wav, opus, flac o pcm). No hay metadatos JSON adicionales en el cuerpo; solo el flujo de datos del audio generado.

¿Puedo usar la API desde un servidor backend o también desde el navegador?

Sí, puedes usar la API desde cualquier lugar que pueda hacer solicitudes HTTP. Utiliza la clave API en el encabezado Authorization.

¿Qué hace la voz 'aria' exactamente?

Aria es una voz femenina descrita como cálida y clara, ideal para narración. Es una de las ocho voces disponibles basadas en grabaciones con licencia. No tiene características técnicas únicas más allá de su tono preset; la configuración se aplica mediante el campo voice en la solicitud.

Primera solicitud

curl

curl https://api.playyk1.com/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.playyk1.com/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.playyk1.com/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

Autenticación y clave API

Ilustración de onda de sonido para: Autenticación y clave API

Para comenzar a utilizar la API de VozCentral, es necesario obtener una clave de API única al registrarse en la plataforma. Cada cuenta está vinculada a una sola clave activa que sirve como token de autorización para todas las solicitudes de síntesis de voz.

Obtención de la clave Bearer

Obtención de la clave Bearer

La clave se genera automáticamente al completar el registro mediante Google o correo electrónico en la página de obtención de claves. Esta credencial, con formato tts-..., es el identificador principal que vincula las solicitudes a tu cuenta y saldo.

Reemplazo de clave activa

Reemplazo de clave activa

Puedes emitir una nueva clave en cualquier momento desde tu panel de cuenta. Al hacerlo, la clave anterior deja de ser válida de manera inmediata, garantizando que solo la credencial más reciente sea utilizada en tus flujos de producción.

Formato del encabezado

Todas las solicitudes deben incluir la clave en el encabezado HTTP estándar. Esto asegura la autenticación correcta antes de que se procese la síntesis de audio.

  • Authorization: Bearer tts-tu-clave-aqui

Endpoint principal de síntesis

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

La síntesis de audio se realiza mediante una llamada POST a https://api.playyk1.com/v1/audio/speech. Esta es la única ruta necesaria para convertir texto en audio, devolviendo el archivo directamente en la respuesta sin necesidad de polling adicional.

Método POST y URL

Envía tu solicitud al endpoint principal especificado. La infraestructura está diseñada para procesar las peticiones secuencialmente, lo que significa que bajo carga alta los resultados pueden tardar unos segundos, especialmente en frases cortas.

Cuerpo de la solicitud JSON

El cuerpo debe ser un objeto JSON que contenga los parámetros de la síntesis. Puedes especificar el modelo, la voz, el formato de salida y la velocidad de lectura para adaptar el resultado a tu flujo de trabajo IVR.

Campos obligatorios

Es indispensable incluir los campos model, input y voice. El campo input acepta hasta 4096 caracteres por solicitud; textos más largos deben dividirse y unirse manualmente. Si no especificas language, el sistema inferirá el idioma, aunque se recomienda definirlo explícitamente para textos en latín que no sean inglés.

  • model: "tts-1" o "tts-1-hd"
  • input: texto a sintetizar (máx. 4096 caracteres)
  • voice: identificador de la voz seleccionada
  • response_format: mp3, wav, opus, flac o pcm

Modelos de voz disponibles

Ilustración de onda de sonido para: Modelos de voz disponibles

La API ofrece dos identificadores de modelo: tts-1 y tts-1-hd. Ambos utilizan exactamente el mismo motor de síntesis subyacente, garantizando una consistencia total en la calidad de la voz y la prosodia, independientemente de cuál elijas en la carga útil JSON.

Mismo motor y precio

No existe diferencia técnica ni de costo entre las dos opciones. El precio es idéntico para ambos valores, calculado por millón de caracteres procesados. Esta simplificación elimina la complejidad de tomar decisiones de arquitectura basadas en la calidad percibida, permitiendo enfocarse en la integración de flujos de trabajo IVR.

Selección de modelo

En la práctica, puedes usar tts-1 como valor predeterminado estable. Dado que el motor es idéntico, la elección entre tts-1 y tts-1-hd es meramente nominal para tu integración actual. Solo cambia el valor si tu equipo de producto establece una convención de código específica para futuras expansiones del motor.

  • Ambos usan el mismo motor de síntesis.
  • Costo idéntico por carácter generado.
  • Calidad de audio consistente entre ambos.

Formatos de audio soportados

Ilustración de onda de sonido para: Formatos de audio soportados

La API acepta múltiples formatos de audio para adaptarse a las necesidades técnicas de tu infraestructura de centros de contacto. Puedes elegir entre formatos optimizados para transmisión web o para grabaciones de alta fidelidad en sistemas IVR.

MP3 para compatibilidad web

El formato MP3 es ideal para aplicaciones web y móviles donde el ancho de banda es crítico. Ofrece una buena relación calidad-tamaño y es compatible con la mayoría de los reproductores modernos, facilitando la integración en interfaces de usuario.

  • Compatible con la mayoría de navegadores y dispositivos móviles
  • Tamaño de archivo reducido para menor consumo de datos

WAV para calidad estándar

WAV es la opción estándar para sistemas que requieren audio sin pérdida de compresión. Es ampliamente soportado en plataformas de telefonía y sistemas de grabación de llamadas, garantizando la integridad del audio para fines de cumplimiento y auditoría.

  • Audio sin pérdida de calidad
  • Amplio soporte en sistemas telefónicos y de grabación

OPUS, FLAC y PCM

OPUS ofrece una compresión eficiente. FLAC proporciona audio sin pérdida, ideal para archivado. PCM es el formato crudo sin compresión, perfecto para procesamiento de señal inmediato.

  • OPUS: alta eficiencia para streaming
  • FLAC: sin pérdida con compresión
  • PCM: formato crudo sin compresión

Configuración de voz y velocidad

Ilustración de onda de sonido para: Configuración de voz y velocidad

La configuración de voz permite seleccionar entre ocho presets diseñados para distintos contextos de comunicación, desde narrativas suaves hasta tonos informativos. Cada voz está construida a partir de grabaciones con licencia, garantizando consistencia acústica en tus flujos de IVR.

La velocidad ajustable entre 0.25x y 4.0x permite adaptar la dicción a las necesidades del usuario final, optimizando la comprensión en aplicaciones de centros de contacto sin requerir procesamiento adicional.

Lista de 8 voces disponibles

Elige entre voces femeninas (Aria, Nova, Luna, Sage) y masculinas (Felix, Milo, Atlas, Orion) para ajustar el tono de tus respuestas automáticas.

  • Aria: Narradora clara y cálida.
  • Nova: Tono brillante y enérgico.
  • Luna: Suave, ideal para historias.
  • Sage: Calma, instruccional.
  • Felix: Energético, promocional.
  • Milo: Amigable, conversacional.
  • Atlas: Neutral, estilo noticias.
  • Orion: Profundo, documental.

Rango de velocidad 0.25 a 4.0

Ajusta la velocidad de reproducción mediante el campo speed. Valores bajos ralentizan la voz para mayor claridad, mientras que valores altos aceleran la generación para respuestas rápidas en IVR.

Código de idioma opcional

Especifica el idioma ISO para garantizar la pronunciación correcta. Si no se indica, el sistema deduce el idioma del script (el latín por defecto es inglés). Configúralo explícitamente para textos en latín que no sean inglés.

Configuración de voz y velocidad

Ejemplo de integración con cURL

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

Aquí tienes un ejemplo directo para generar audio sintético. Este comando simula una solicitud típica que enviarías desde tu sistema IVR o centro de contacto.

La respuesta incluye el encabezado Content-Type y el cuerpo binario del archivo de audio, listo para ser guardado o reproducido inmediatamente.

Solicitud básica de texto

Utiliza el siguiente comando cURL para enviar un texto corto. Asegúrate de reemplazar tts-tu-clave-aqui con tu clave Bearer real.

Aquí se especifica la voz nova, el formato mp3 y un texto de prueba en español para validar la integración.

  • curl -X POST https://api.playyk1.com/v1/audio/speech \
  • -H "Authorization: Bearer tts-tu-clave-aqui" \
  • -H "Content-Type: application/json" \
  • -d '{"model": "tts-1", "input": "Bienvenido a nuestro servicio de atención al cliente.", "voice": "nova", "response_format": "mp3"}'

Respuesta con archivo de audio

Si la solicitud es exitosa, recibirás un código 200 con el archivo de audio comprimido en el cuerpo de la respuesta. No hay metadatos JSON adicionales.

El archivo generado contiene la síntesis exacta del texto proporcionado, listo para ser integrado en tus flujos de llamada.

Manejo de la respuesta binaria

Para guardar el archivo en tu servidor, redirige la salida estándar a un archivo local. Esto evita problemas de codificación con datos binarios.

Este paso es crucial para asegurar que el audio se pueda reproducir correctamente en los reproductores de voz de tus sistemas IVR.

  • curl -X POST https://api.playyk1.com/v1/audio/speech \
  • -H "Authorization: Bearer tts-tu-clave-aqui" \
  • -d '{"model": "tts-1", "input": "Prueba de integración.", "voice": "nova", "response_format": "mp3"}' \
  • -o audio_generado.mp3

Uso con OpenAI SDK

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

La API sigue la forma de solicitud del endpoint de voz de OpenAI, lo que permite reutilizar los SDK oficiales sin modificaciones complejas. Solo es necesario ajustar la URL base para apuntar a nuestro servicio, manteniendo la misma estructura JSON y autenticación Bearer.

Cambio de base_url

Configura la variable base_url del SDK para que apunte a https://api.playyk1.com/v1. Esto redirige todas las solicitudes al motor de síntesis de VozCentral, manteniendo la compatibilidad con tus scripts existentes.

Compatibilidad con librerías oficiales

Las librerías oficiales de OpenAI funcionan correctamente al modificar únicamente la URL base. La autenticación se gestiona con tu clave API (tts-...) en el encabezado Authorization, igual que en la integración estándar.

Ejemplo en Python o Node

En Python, importa OpenAI y define base_url="https://api.playyk1.com/v1". En Node, configura la misma URL en las opciones del cliente. El resto del código, como la llamada a audio.speech(), permanece idéntico.

Límites y errores comunes

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

La API opera con límites estrictos para garantizar la estabilidad del servicio en entornos de producción. Conocer estas restricciones permite diseñar flujos de integración que eviten bloqueos involuntarios y mantengan la calidad del audio en tiempo real.

60 solicitudes por minuto

Cada clave API está limitada a 60 solicitudes por minuto. Antes de la primera recarga, el límite es de 10 solicitudes por minuto. Si se excede este límite, las solicitudes adicionales se procesarán en cola. Para volúmenes altos, se recomienda implementar una lógica de reintentos con backoff exponencial.

Límite de 4096 caracteres

Cada solicitud puede contener un máximo de 4096 caracteres, incluyendo espacios y puntuación. Si el texto excede este límite, debes dividirlo en partes y unir los archivos de audio resultantes. Esta limitación se aplica por solicitud individual, no por sesión.

Códigos de error HTTP

Los errores más comunes incluyen 400 para parámetros inválidos (como un modelo o voz incorrecta), 401 para claves API inválidas o expiradas, y 429 para límites de velocidad excedidos. Los errores 500 indican fallos temporales del servidor. Las solicitudes fallidas no se cobran.

  • 400: Parámetros inválidos o faltantes.
  • 401: Clave API incorrecta o inválida.
  • 429: Demasiadas solicitudes (límite de velocidad).
  • 500: Error interno del servidor.

Escucha las 8 voces

Cada muestra a continuación fue generada por esta API a partir de la misma frase. La velocidad de habla (speed) debe ajustarse según la complejidad del mensaje.

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. Node.js documentation
  3. LibriTTS-R corpus (OpenSLR 141)
  4. OpenAI API reference: create speech
  5. openai-node on GitHub
  6. IETF RFC 7845: Ogg Opus
  7. TRON developer hub: TRC-20
  8. Creative Commons Attribution 4.0
  9. MDN: Web Speech API
  10. openai-python on GitHub
  11. Python documentation
  12. W3C WAI: making audio and video accessible

Más en este sitio