¿Cómo funciona la API de texto a voz para desarrolladores?

Por Equipo editorial de VozNube · Actualizado 2026-11-19

Esta guía explica la integración técnica de la API VozNube, diseñada para desarrolladores indie que necesitan síntesis de voz predecible en sus aplicaciones SaaS. Cubrimos el flujo completo: desde la petición POST estándar hasta la gestión de errores y costes, con ejemplos concretos de implementación sin abstracciones innecesarias.

Aprenderás a manejar límites de caracteres, seleccionar voces entre ocho presets y optimizar formatos de audio según el ancho de banda. Ideal para quienes integran notificaciones o accesibilidad, evitando sorpresas en la infraestructura y manteniendo el control total sobre el rendimiento y la autenticación.

¿Cómo funciona la API de texto a voz para desarrolladores?

Preguntas frecuentes

¿Qué es una API de texto a voz?

Es un servicio en la nube que convierte texto en archivos de audio mediante una solicitud HTTP. Envías texto y recibes el audio generado. Funciona enviando una petición POST al endpoint correspondiente con el texto y la configuración deseada, devolviendo el archivo de audio en la respuesta.

¿Cómo se integra una API REST en una app?

Realiza una petición POST al endpoint /v1/audio/speech con tu clave API en el encabezado Authorization. El cuerpo JSON debe incluir el modelo, input, voice y formato. Si usas el SDK de OpenAI, solo cambia el base_url a https://api.wasp66.info/v1 y usa tu clave.

¿Qué es un endpoint POST?

Es la dirección URL donde tu aplicación envía datos para ser procesados. En este caso, POST https://api.wasp66.info/v1/audio/speech recibe el texto y los parámetros de síntesis, procesa la solicitud y devuelve el archivo de audio generado como respuesta.

¿Cuántos caracteres puedo enviar en una petición?

Cada petición puede contener hasta 4096 caracteres. Si tu texto es más largo, debes dividirlo en fragmentos de este tamaño máximo, generar el audio para cada parte y luego unir los archivos de audio resultantes para obtener el audio completo.

¿Qué diferencia hay entre tts-1 y tts-1-hd?

Ambos modelos utilizan el mismo motor de síntesis y tienen el mismo precio. La única diferencia es el nombre del modelo en la API; funcionalmente son idénticos para la generación de audio y el cálculo de caracteres consumidos.

¿Cómo manejo textos que superan 4096 caracteres?

Debes dividir el texto en partes de máximo 4096 caracteres. Envía cada parte en una solicitud POST separada. Luego, une los archivos de audio devueltos por cada respuesta para crear el archivo final completo con la narración continua.

¿Qué formatos de audio son mejores para web?

Para web, mp3 y opus son ideales por su equilibrio entre calidad y tamaño. mp3 tiene máxima compatibilidad, mientras que opus ofrece mejor compresión. wav y flac son para alta fidelidad, y pcm para procesamiento directo sin codificación.

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

Si no especificas el campo language, el sistema lo infiere según el script. El texto en latín se asume inglés por defecto. Para otros idiomas en latín o scripts no estándar, debes establecer explícitamente el código ISO del idioma.

¿Qué es la tasa de bits o velocidad en TTS?

Es el parámetro speed que controla la velocidad de la voz, entre 0.25 y 4.0. Un valor de 1.0 es la velocidad normal. Ajustarlo permite acelerar o ralentizar la narración sin cambiar el tono de la voz seleccionada.

¿Cómo se gestiona la autenticación Bearer?

Incluye tu clave API en el encabezado Authorization: Bearer tts-... de cada petición. Cada cuenta tiene una clave activa. Si emites una nueva, la anterior deja de funcionar inmediatamente. Puedes renovar la clave cuando quieras desde tu panel.

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

Las solicitudes se procesan secuencialmente. Si excedes el límite de 60 requests por minuto por clave, tus peticiones pueden entrar en una cola de espera. El procesamiento es secuencial bajo carga, por lo que los tiempos de respuesta pueden aumentar.

¿Es seguro usar la API Key en el frontend?

La clave funciona para autenticar peticiones, pero no hay control granular de permisos. Si la expones en el frontend, cualquier usuario puede usar tu saldo. Para producción, es mejor usar un backend intermedio que oculte la clave y gestione los límites.

¿Cómo se calcula el coste exacto de una frase?

El coste es $0.01 por cada 1000 caracteres, contando espacios y puntuación. Multiplica el número total de caracteres por 0.00001. Las peticiones fallidas no generan cargo. El saldo se descuenta automáticamente tras la síntesis exitosa.

¿Qué es el formato Opus y para qué sirve?

Opus es un formato de audio que ofrece compresión con pérdida, ideal para reducir el consumo de datos.

¿Cómo se prueban las integraciones sin gastar mucho?

Regístrate con Google para obtener $0.50 de crédito de prueba válido por 7 días. Esto permite generar aproximadamente 50.000 caracteres sin costo. También puedes enviar peticiones pequeñas para verificar la integración antes de integrar el flujo completo en tu app.

¿Se puede usar esta API para notificaciones push?

Sí, puedes generar audio de notificaciones y enviarlo como parte de una push notification si tu plataforma lo soporta. Genera el audio mediante la API, obtén la URL o el archivo, y envíalo al dispositivo del usuario mediante tu servicio de notificaciones.

¿Qué es la concatenación de audio en TTS?

Es el proceso de unir varios archivos de audio generados por separado en un solo archivo continuo. Es necesario cuando el texto excede 4096 caracteres, dividiéndolo en partes, generando cada una y luego fusionándolas para mantener la coherencia narrativa.

¿Cómo cambio la velocidad de la voz programáticamente?

Añade el campo speed al cuerpo JSON de la petición POST, con un valor entre 0.25 y 4.0. Un valor de 1.0 es la velocidad normal. El API ajustará la velocidad de síntesis según este valor antes de devolver el audio.

Arquitectura de la Integración

Ilustración de onda de sonido para: Arquitectura de la Integración

La integración comienza con una petición POST a /v1/audio/speech, enviando texto JSON y recibiendo un archivo de audio. Este flujo simple elimina la necesidad de gestionar infraestructura de síntesis, permitiendo a los desarrolladores indie enfocarse en la lógica de su aplicación SaaS sin complicaciones de backend.

Petición POST estándar

La API acepta texto plano en el cuerpo de la petición, con un límite de 4096 caracteres. La respuesta devuelve directamente el archivo de audio codificado, listo para ser reproducido o almacenado temporalmente en la aplicación.

  • Endpoint: POST https://api.wasp66.info/v1/audio/speech
  • Formato de entrada: JSON con campo 'input'
  • Formato de salida: Audio binario (mp3, wav, etc.)

Manejo de tiempos de respuesta

La generación es aproximadamente en tiempo real, procesando unos 25 caracteres por segundo de audio. Para frases cortas, la latencia es de pocos segundos, lo que asegura una experiencia fluida en interfaces interactivas donde la respuesta inmediata es crítica.

Gestión de cola de peticiones

Las peticiones se procesan secuencialmente bajo carga. Si el servidor está saturado, las solicitudes pueden entrar en una cola de espera. Esto es predecible y no requiere lógica compleja de reintentos automáticos, ya que la cola garantiza el orden de procesamiento.

Selección de Voz y Idioma

Ilustración de onda de sonido para: Selección de Voz y Idioma

La API ofrece ocho voces predefinidas con tonos distintos, desde narradoras claras hasta voces profundas para documentales. Cada voz es un preset listo para usar, sin necesidad de ajustes complejos ni clonación personalizada. Esto simplifica la integración en interfaces SaaS donde la consistencia auditiva es crítica.

Elección de 8 presets

Selecciona entre cuatro voces femeninas (Aria, Nova, Luna, Sage) y cuatro masculinas (Felix, Milo, Atlas, Orion). Cada preset tiene un carácter acústico específico, ideal para diferenciar tipos de notificaciones o roles en la aplicación.

  • Aria: narradora clara y cálida
  • Nova: brillante y enérgica
  • Luna: suave para historias
  • Sage: calma e instructiva
  • Felix: dinámica para promos
  • Milo: conversacional y amigable
  • Atlas: neutral para noticias
  • Orion: profunda para documentales

Detección automática vs explícita

Si no especificas el idioma, el sistema lo infiere por el script (por defecto, texto en latín se asume inglés). Para textos en latín que no sean inglés, establece el campo language explícitamente para evitar errores de pronunciación.

Consistencia de voz en UI

Mantén el mismo parámetro voice en todas las peticiones de una misma funcionalidad. Esto garantiza que los usuarios identifiquen inmediatamente el origen de las notificaciones o alertas. Cada archivo generado lleva una marca de agua inaudible que lo identifica como voz sintética.

Manejo de Textos Largos

Ilustración de onda de sonido para: Manejo de Textos Largos

La API acepta un máximo de 4096 caracteres por solicitud. Para textos que exceden este límite, el cliente debe dividir el texto en fragmentos, enviar cada parte mediante una petición POST y luego unir los archivos de audio resultantes.

Es crucial gestionar la concatenación en el lado del cliente para mantener la coherencia del flujo de audio.

Límite de 4096 caracteres

Cada llamada a POST /v1/audio/speech procesa hasta 4096 caracteres, incluyendo espacios y puntuación. Si el texto es más largo, debe dividirse manualmente antes de enviarlo. Esto evita errores de validación y permite un control preciso sobre la longitud de cada segmento de audio generado.

Concatenación de audio

Los archivos de audio generados para cada fragmento deben unirse secuencialmente. Dado que las peticiones se procesan en serie, el tiempo de espera entre fragmentos puede acumularse. El cliente debe manejar la lógica de ensamblaje para garantizar que no haya silencios o cortes abruptos entre las partes del texto original.

  • Usar librerías como ffmpeg o codecs nativos para unir formatos como MP3 o WAV.
  • Mantener el orden exacto de las solicitudes para preservar la secuencia narrativa.

Gestión de memoria en cliente

El cliente debe gestionar los fragmentos de audio para la concatenación final. Para aplicaciones con recursos limitados, es recomendable procesar y concatenar en bloques pequeños para evitar picos de uso de memoria que puedan afectar la estabilidad de la aplicación SaaS.

Formatos de Audio

Ilustración de onda de sonido para: Formatos de Audio

La API acepta cinco formatos de salida mediante el campo response_format: mp3, wav, opus, flac y pcm. Esta flexibilidad permite adaptar la entrega de audio a las necesidades específicas de cada cliente, equilibrando compatibilidad y eficiencia de red.

MP3, WAV, Opus, FLAC, PCM

MP3 y Opus ofrecen compresión con pérdida, ideales para reducir el consumo de datos. WAV y FLAC proporcionan audio sin pérdida, manteniendo la fidelidad original de la voz sintetizada. PCM entrega datos de audio sin comprimir, útil para procesamiento posterior en el cliente.

  • MP3/Opus: máximo ahorro de ancho de banda.
  • WAV/FLAC: calidad de estudio sin pérdida.
  • PCM: datos crudos para procesamiento inmediato.

Elección según ancho de banda

Selecciona formatos comprimidos (MP3, Opus) para aplicaciones móviles o conexiones lentas. Utiliza FLAC o WAV cuando la latencia no sea crítica y se requiera máxima integridad de datos, aunque esto incrementa el tráfico de red significativamente.

Calidad de salida

Todas las voces generan audio con una claridad consistente, independientemente del formato elegido. La diferencia radica únicamente en la compresión. Los formatos sin pérdida preservan matices espectrales, mientras que los con pérdida optimizan la velocidad de descarga sin afectar notablemente la inteligibilidad del habla.

Control de Velocidad

Ilustración de onda de sonido para: Control de Velocidad

La API permite ajustar la velocidad de síntesis entre 0.25 y 4.0 mediante el campo speed. Este parámetro modifica la tasa de habla sin alterar la entonación base de la voz seleccionada, ofreciendo control directo sobre la duración del audio generado.

Un factor de 1.0 corresponde a la velocidad natural. Valores superiores aceleran la voz, reduciendo el tiempo de procesamiento, mientras que valores inferiores la ralentizan para mayor claridad en contextos de baja atención.

Ajuste de factor 0.25–4.0

El campo speed acepta valores decimales en el rango especificado. Este ajuste es inmediato y se aplica durante la generación, permitiendo adaptar el audio a diferentes contextos de uso sin necesidad de post-procesamiento.

La velocidad se define por solicitud. Puedes variar el parámetro entre llamadas para optimizar la experiencia de usuario según el dispositivo o la urgencia del mensaje.

Impacto en tiempo de generación

A mayor velocidad, el tiempo de generación disminuye. Esto es crítico para reducir la latencia percibida en aplicaciones SaaS que requieren respuestas rápidas.

Ten en cuenta que, aunque la síntesis sea más rápida, las solicitudes siguen procesándose en cola bajo los límites de tasa (60 req/min). Ajustar la velocidad no bypassa los límites de concurrencia.

Legibilidad en notificaciones

Para notificaciones push o alertas, una velocidad de 1.2 a 1.5 suele optimizar la relación entre claridad y brevedad. Textos muy largos pueden resultar confusos a velocidades superiores a 2.0.

En interfaces de accesibilidad, velocidades cercanas a 0.8 o 0.9 mejoran la comprensión para usuarios con dificultades auditivas o cognitivas, manteniendo una pronunciación clara.

Gestión de Errores y Costes

Ilustración de onda de sonido para: Gestión de Errores y Costes

La API garantiza que no pagues por lo que no llega. Si la síntesis falla, el cargo se devuelve íntegramente. Para errores de red transitorios, implementa un reintento exponencial simple en tu cliente o backend antes de marcar la solicitud como fallida definitivamente.

El límite de 60 solicitudes por minuto se aplica por clave API. Antes de la primera recarga, este umbral se reduce a 10 req/min para prevenir abusos durante la fase de prueba. Planifica tu colas de trabajo para no exceder estos límites de forma crónica.

Retry en fallos de red

Los fallos de red son transitorios. Reintenta con backoff exponencial para evitar sobrecargar el endpoint durante picos de latencia.

Si la síntesis falla, el cargo se devuelve íntegramente. No se consume crédito por una respuesta de error confirmada.

  • Reintenta automáticamente en errores 5xx o timeouts.
  • Verifica el estado en el dashboard si el error persiste.

Límites de 60 req/min

El límite estándar es de 60 solicitudes por minuto por clave. Si no has realizado una recarga, el límite baja a 10 req/min.

Exceder este límite retorna un error 429. Los requests en cola no cuentan hasta que se procesan.

Monitorea los límites de tasa para ajustar dinámicamente la tasa de tus jobs en segundo plano.

  • 60 req/min tras primera recarga.
  • 10 req/min sin recarga previa.

Cobro por carácter y créditos

El costo es $0.01 por cada 1,000 caracteres, incluidos espacios y puntuación. Los fallos devuelven el crédito completo.

El saldo no caduca. Puedes top-up mediante USDT (TRC-20) con un mínimo de $5.

La prueba inicial de $0.50 (válida 7 días) cubre aproximadamente 50,000 caracteres.

  • Cobro: $10 por 1M de caracteres.
  • Formato de pago: USDT TRC-20.
  • Sin cargos ocultos ni suscripciones fijas.
Gestión de Errores y Costes

Seguridad y Autenticación

Ilustración de onda de sonido para: Seguridad y Autenticación

La API utiliza un único token activo por cuenta. Cualquier solicitud debe incluir el encabezado Authorization: Bearer tts-.... Este enfoque simplifica la gestión de credenciales en entornos SaaS.

Protección de la API Key

Mantén la clave en variables de entorno. No la expongas en el cliente final si es posible, ya que permite consumir tu saldo.

  • Una sola clave activa por cuenta.
  • Formato estándar Bearer token.

Rotación de claves segura

Puedes emitir una nueva clave en cualquier momento. La clave anterior deja de funcionar inmediatamente, eliminando ventanas de vulnerabilidad sin espera.

Uso en backend vs frontend

Se recomienda usar la clave desde el servidor (backend) para ocultarla al usuario final. Si se usa en frontend, asume que puede ser vista en la red.

Pruebas de Integración

Ilustración de onda de sonido para: Pruebas de Integración

La validación inicial se realiza mediante una llamada cURL directa al endpoint POST https://api.wasp66.info/v1/audio/speech. Este método permite confirmar la autenticación y recibir el archivo de audio sin dependencias externas, ideal para entornos de desarrollo rápido.

Para entornos más complejos, la API es compatible con los SDKs oficiales de OpenAI. Solo requiere ajustar la propiedad base_url a la URL de la API y proporcionar la clave de API correspondiente en el encabezado de autorización.

Una vez obtenida la respuesta, se verifica que el formato solicitado (mp3, wav, opus, flac o pcm) se haya generado correctamente. El contenido del cuerpo de la respuesta debe ser el archivo binario de audio correspondiente al texto enviado.

Validación con cURL inicial

Ejecuta una petición POST con la clave Bearer en el encabezado. El cuerpo JSON debe incluir el modelo (tts-1 o tts-1-hd), el texto de entrada y la voz deseada. La respuesta contiene el audio listo para reproducir o guardar.

  • Usar curl -X POST con headers de autorización.
  • Validar código de estado 200 OK.
  • Confirmar recepción del archivo binario.

Prueba con SDK OpenAI

Configura el cliente del SDK estableciendo base_url en https://api.wasp66.info/v1. Usa el método audio.speech.create pasando tu clave de API. Esto permite reutilizar la lógica de cliente que ya conozcas.

  • Ajustar base_url al dominio de la API.
  • Mantener la estructura de objetos JSON estándar.
  • Manejo automático de autenticación por el SDK.

Verificación de formato de salida

Comprueba que el archivo generado coincide con el valor de response_format. Los formatos variadas como FLAC o WAV ocupan más espacio pero evitan compresión lossy, mientras que MP3 y Opus son ideales para redes móviles.

  • Verificar cabeceras HTTP del contenido.
  • Validar extensión de archivo.
  • Comprobar reproducibilidad en el cliente.

Escalabilidad del Servicio

Ilustración de onda de sonido para: Escalabilidad del Servicio

La API de VozNube opera como un servicio en la nube independiente, eliminando la necesidad de gestionar servidores de síntesis o ajustar la infraestructura al variar la carga. Los desarrolladores indie integran la API mediante llamadas HTTP simples, delegando el procesamiento de audio a la infraestructura del proveedor.

Sin infraestructura propia

Al no requerir servidores dedicados, la integración se limita a la gestión de la API key y el manejo de respuestas JSON. Esto reduce la complejidad operativa para aplicaciones SaaS que necesitan escalar sin mantener hardware adicional.

Crecimiento lineal de costes

El modelo de precios es estrictamente basado en el consumo: $10 por cada 1 millón de caracteres. No hay planes mensuales fijos ni mínimos de gasto. Si el uso aumenta, los costes crecen proporcionalmente a los caracteres generados, manteniendo la predictibilidad financiera.

Sin límites de uso fijos

El servicio no impone límites estrictos de escala vertical más allá de los límites de tasa (60 requests/min por clave). Esto permite que aplicaciones con picos de demanda sigan funcionando sin necesidad de migrar a planes enterprise o negociar contratos personalizados.

Casos de Uso

Ilustración de onda de sonido para: Casos de Uso

La API de VozNube convierte texto en audio para notificaciones críticas, alertas de estado del sistema o avisos de pago en aplicaciones SaaS. Al enviar texto mediante POST, los usuarios reciben un archivo de audio listo para reproducirse sin latencia de infraestructura adicional.

Este flujo elimina la necesidad de servidores de media dedicados. La generación es predecible, con costes lineales por carácter, lo que permite integrar voz en flujos de notificación sin complicaciones de infraestructura ni variaciones de coste fijas.

Notificaciones y alertas

Las notificaciones pueden incluir audio para alertas de sistemas o avisos de pagos. El endpoint POST devuelve el audio directamente, evitando la gestión de servidores de media. Los costes son lineales por carácter, lo que hace viable el uso masivo sin picos de infraestructura.

Se puede configurar la velocidad para que la lectura sea ágil en alertas urgentes. La API maneja la generación sin necesidad de pipelines de video ni edición, manteniendo la simplicidad para desarrolladores indie que integran estas funciones en sus apps.

  • Alertas de sistemas en tiempo real
  • Avisos de pagos o vencimientos
  • Integración directa en flujos de notificación

Accesibilidad en interfaces

La API permite generar audio para contenido accesible, como descripciones de imágenes o textos largos en interfaces. Con 23 idiomas soportados, se puede adaptar el contenido a usuarios que prefieren la escucha. La generación es aproximadamente en tiempo real, procesando unos 25 caracteres por segundo de audio.

Los formatos como MP3 o Opus reducen el uso de ancho de banda, ideal para aplicaciones móviles o de bajo recurso. La voz sintetizada se entrega inmediatamente, sin necesidad de almacenamiento previo ni procesamiento en el lado del servidor.

  • Contenido accesible para lectores de pantalla
  • Soporte multilingüe con 23 idiomas
  • Formatos optimizados para bajo ancho de banda

Lectores de estado de servicio

Los lectores de estado pueden usar la API para convertir logs o mensajes de estado en audio. Esto permite a los usuarios escuchar actualizaciones de servicio sin mirar la pantalla. La API devuelve el audio directamente, sin almacenamiento persistente ni gestión de archivos.

La velocidad ajustable permite que las actualizaciones sean rápidas pero claras. Al no haber límites de uso fijos, se puede escalar el uso según la carga de notificaciones, manteniendo los costes predecibles y lineales por carácter generado.

  • Logs convertidos en audio
  • Actualizaciones de estado sin mirar pantalla
  • Escalabilidad sin límites fijos de uso

Límites y Rendimiento

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

La velocidad de generación es aproximadamente real-time, con un ritmo de 25 caracteres por segundo de audio. Las frases cortas pueden tardar unos segundos adicionales en procesarse debido a la sobrecarga inicial.

El rendimiento depende de la carga del servidor. Bajo alta demanda, las peticiones se encolan y procesan en orden de llegada, lo que puede aumentar ligeramente la latencia percibida.

Velocidad de generación

La síntesis se realiza a un ritmo cercano al tiempo real, estimando 25 caracteres de texto por segundo de audio generado. Para frases breves, el tiempo total puede ser superior debido a la inicialización del motor.

Cola de procesamiento

Las peticiones se procesan secuencialmente. Si hay alta concurrencia, las solicitudes pueden entrar en una cola de espera antes de iniciarse la síntesis, lo que incrementa el tiempo de respuesta total.

Caracteres por petición

Cada llamada POST acepta un máximo de 4096 caracteres. Para textos más extensos, es necesario dividir el contenido y concatenar los archivos de audio resultantes en el lado del cliente o servidor.

Escucha las 8 voces

Cada muestra a continuación fue generada por esta API a partir de la misma frase. Esto evita errores de validación y permite un control preciso sobre la longitud de cada segmento de audio generado.

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. FFmpeg documentation
  3. OpenAI API reference: create speech
  4. IETF RFC 7845: Ogg Opus
  5. MDN: Web Speech API
  6. Creative Commons Attribution 4.0
  7. curl documentation
  8. Python documentation
  9. Tether (USDT)
  10. ISO 639 language codes
  11. LibriTTS-R paper (arXiv 2305.18802)
  12. openai-node on GitHub

Más en este sitio