Integración de la API de texto a voz: guía completa para desarrolladores

En resumen: la API de texto a voz de DubVoice.ai es REST, se autentica con una clave sk_ y admite webhooks. Haz POST con el texto y voice_id a /api/v1/tts y consulta GET /api/v1/tts/{task_id} para obtener audio_url y srt_url. Todas las cuentas incluyen créditos iniciales.

¿Quieres añadir texto a voz a tu aplicación? Esta guía cubre todo lo necesario para integrar la API de DubVoice.ai, desde la autenticación hasta las buenas prácticas en producción.

¿Por qué usar una API de TTS?

Construir texto a voz desde cero exige conjuntos de datos enormes, infraestructura de GPU cara y experiencia profunda en aprendizaje automático. Una API te da:

• Voces listas para producción — más de 17.800 voces naturales desde el primer momento
• Soporte multilingüe — más de 50 idiomas con una sola API
• Escalabilidad — miles de peticiones sin preocuparte por la infraestructura
• Mejora continua — la calidad de voz mejora sin que tengas que hacer nada

Inicio rápido

Autenticación

Todas las peticiones necesitan una clave de API. Consíguela en el panel de DubVoice.ai: Ajustes → Claves de API.

Petición básica

curl -X POST https://dubvoice.ai/api/v1/tts \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Hello, welcome to our application!",
    "voice_id": "voice_rachel",
    "language": "en"
  }'

Respuesta

La API devuelve un archivo de audio (MP3 por defecto) junto con metadatos como el número de caracteres y el tiempo de procesamiento.

Patrones de integración

Patrón 1: generación bajo demanda

El audio se genera cuando el usuario lo pide. Ideal para aplicaciones interactivas, chatbots y funciones de accesibilidad.

Patrón 2: pregeneración

Genera y cachea el audio de contenido conocido. Ideal para plataformas de e-learning, sistemas de voz y contenido estático.

Patrón 3: streaming

Para aplicaciones en tiempo real donde importa la latencia. El audio se emite por fragmentos según se produce.

Buenas prácticas

• Cachea con generosidad — si el mismo texto se pide varias veces, sírvelo desde caché
• Gestiona los límites — aplica retroceso exponencial ante respuestas 429
• Valida la entrada — comprueba longitud y contenido antes de enviar
• Monitoriza el consumo — controla los caracteres para evitar costes inesperados
• Usa webhooks — para textos largos, prefiere generación asíncrona con retrollamada

Manejo de errores

Trata siempre los errores de forma explícita:

• 400 — petición inválida (revisa longitud del texto, voice_id, idioma)
• 401 — clave de API inválida o caducada
• 429 — límite de peticiones superado (aplica retroceso)
• 500 — error del servidor (reintenta con retroceso exponencial)

Precio del uso por API

Las peticiones por API consumen créditos del mismo saldo y a la misma tarifa que la interfaz web. Un crédito equivale a un carácter. Los paquetes van de 250.000 créditos (4,99 $) a 40 millones (110 $).

Casos de uso habituales

• Apps móviles — narración en aplicaciones de lectura, noticias o navegación
• Aplicaciones web — accesibilidad, contenido en audio, notificaciones
• Dispositivos — avisos en el hogar inteligente, respuestas de voz embebidas
• Videojuegos — diálogo de personajes, voz de narrador, historias dinámicas
• Plataformas SaaS — versiones en audio de informes, paneles y alertas

Síncrono o asíncrono: decídelo antes de programar

Esperar el render o enviar y consultar es la decisión que da forma al resto de la integración, y es fácil equivocarse dejándose llevar por lo que viene por defecto.

Un texto corto vuelve lo bastante rápido como para esperarlo dentro de la petición. Un saludo, una notificación, el nombre de un producto — uno o dos segundos, y bloquear es más simple que la alternativa. Un texto largo, no. Un artículo de 15.000 caracteres puede tardar minutos, y una función serverless que se queda esperando será eliminada por la plataforma mucho antes de que el audio esté listo.

El modo de fallo merece nombrarse: tu función expira, tu usuario ve un error, y el trabajo termina correctamente en el servidor de todas formas. Has gastado los créditos y perdido el resultado.

Así que por encima de unos pocos miles de caracteres, envía y consulta. Recoge el identificador de tarea al momento, devuélvelo al navegador y deja que el navegador consulte una ruta de estado ligera. La petición que envía se queda por debajo del segundo dure lo que dure el render.

Gestionar fallos sin pagar dos veces

Dos reglas cubren casi todo lo que sale mal.

Trata un límite de peticiones como una espera, no como un error. Un 429 trae una cabecera Retry-After que te dice cuánto aguantar. Respétala en vez de reintentar de inmediato — reintentar contra un límite solo lo alarga. Retrocede de forma exponencial con algo de aleatoriedad para que los procesos concurrentes no reintenten al unísono.

Haz los reintentos idempotentes. Si tu ejecutor se cae después de enviar pero antes de guardar el identificador, el arreglo ingenuo es volver a enviar — y ya has pagado dos veces por el mismo audio. Escribe el identificador en tu base de datos antes que nada y comprueba si ya existe antes de enviar.

Qué guardar y durante cuánto

Guarda el identificador de tarea, el hash del texto, el identificador de voz y la URL del audio resultante. El hash del texto es lo que te permite saltarte un render entero cuando vuelve el mismo guion, que en la práctica pasa a menudo: la misma descripción de producto se pide una y otra vez.

No trates la URL del proveedor como almacenamiento permanente. Descarga el archivo y ponlo donde tú mandas, en tu propio calendario. Una URL que no emitiste tú puede caducar, y te enterarás por un ticket de soporte sobre un reproductor muerto.

Para el recorrido por todo lo demás disponible con la misma clave, mira [todo lo que puede hacer la plataforma](/blog/everything-you-can-do-with-dubvoice-ai).

Cómo empezar

• Regístrate en dubvoice.ai y consigue tu clave de API
• Pruébala con una petición cURL sencilla
• Intégrala en tu aplicación con el lenguaje que prefieras
• Prueba con distintas voces e idiomas
• Despliega y vigila el consumo

Consulta la documentación completa en dubvoice.ai/api-docs para la referencia de endpoints, el catálogo de voces y los códigos de idioma.