Cómo integrar la API de texto a voz en notificaciones de pago

Por Equipo editorial VozBanco · Actualizado 2026-11-18

Esta guía explica cómo integrar la API de texto a voz de VozBanco para generar notificaciones de pago, alertas y validaciones en entornos de banca y fintech. Aprenderás a conectar tu producto con una API de texto a voz que devuelve archivos de audio, ideal para equipos de producto que buscan comunicación con usuarios finales mediante audio sintetizado.

El proceso se divide en pasos concretos: desde la creación de la cuenta y la obtención de la clave API hasta la configuración del SDK y el manejo de errores. Encontrarás ejemplos de código en Python, Node.js y cURL, junto con recomendaciones específicas sobre selección de voces, formatos de audio y optimización de costos para integraciones robustas y escalables.

Cómo integrar la API de texto a voz en notificaciones de pago

Preguntas frecuentes

¿Cómo se divide un texto largo?

El límite es de 4096 caracteres por solicitud. Debes dividir el texto en partes dentro de este límite y enviar cada fragmento como una petición independiente. Luego, une los archivos de audio resultantes para obtener el audio completo. Esto garantiza que cada parte se procese correctamente sin exceder la capacidad de entrada de la API.

¿Qué voz usar para notificaciones de pago?

Para notificaciones de pago, puedes usar 'aria' (narradora clara) o 'sage' (instruccional). 'milo' también es una opción viable para un tono conversacional y amigable. Estas voces ofrecen claridad y neutralidad, ideales para transmitir información financiera crítica sin ambigüedades, asegurando que el usuario comprenda el estado de su transacción rápidamente.

¿Se puede cambiar el idioma después de generar?

No. El idioma se define durante la generación del audio mediante el campo language o por detección automática. Una vez generado el archivo, el idioma está fijo en el audio resultante. No existe una función para traducir o cambiar el idioma del audio ya creado.

¿Cómo se maneja la cola de solicitudes?

Las solicitudes se procesan en orden secuencial. Si hay alta demanda, tu petición puede esperar en una cola. Esto significa que el tiempo de generación puede variar, especialmente para textos largos. No hay garantía de latencia fija, por lo que es ideal para notificaciones asíncronas.

¿Qué hacer si el audio está cortado?

Verifica que el texto no exceda los 4096 caracteres por solicitud. Si el texto es más largo, divídelo en fragmentos más pequeños. Además, asegúrate de que la velocidad (speed) esté dentro del rango de 0.25 a 4.0. Si el fallo persiste, revisa la respuesta de la API para códigos de error específicos.

¿Es necesario usar el SDK de OpenAI?

No es obligatorio. Puedes usar HTTP estándar o cualquier SDK compatible con la estructura de la solicitud. La API sigue el mismo formato de cuerpo JSON que el endpoint de speech de OpenAI, por lo que puedes adaptarlo fácilmente a tu infraestructura actual sin dependencias específicas de librerías externas.

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

Si no especificas el campo language, el sistema intenta inferirlo basado en el guion del texto. Por defecto, el texto en latinos se asume como inglés. Para otros idiomas en latinos, es recomendable establecer explícitamente el campo language con el código ISO para evitar errores de pronunciación.

¿Se pueden usar voces masculinas para alertas?

Sí. Las voces masculinas disponibles son 'felix' (enérgico), 'milo' (conversacional), 'atlas' (neutral) y 'orion' (documental). 'atlas' es ideal para alertas neutras y claras, mientras que 'felix' puede usarse para alertas urgentes o promocionales. Todas las voces soportan los 23 idiomas disponibles.

¿Qué pasa si se pierde la clave API?

Puedes emitir una nueva clave en cualquier momento desde tu panel de cuenta. Al generar una nueva clave, la anterior deja de funcionar inmediatamente. Esto permite una gestión segura de accesos sin necesidad de contactar soporte, asegurando que puedas continuar con tus integraciones sin interrupciones prolongadas.

¿Cómo se verifica el saldo disponible?

El saldo se visualiza en la página /get-api-key/ después de iniciar sesión. También puedes consultar el estado de tu cuenta a través del endpoint GET /v1/voices. El saldo no expira y se actualiza automáticamente tras las recargas o uso de créditos.

¿Se puede usar en un servidor backend?

Sí, está diseñado para integración backend. Envías texto desde tu servidor y recibes el archivo de audio mediante la API REST. Es ideal para generar notificaciones, alertas y validaciones de manera programática, integrándose perfectamente con flujos de trabajo de banca y fintech sin necesidad de intervención del usuario final.

¿Cómo se optimiza el uso de caracteres?

Cada carácter, incluido espacios y puntuación, cuenta. Para optimizar, reduce textos redundantes y usa frases concisas. Recuerda que el límite es de 4096 caracteres por petición. Dividir textos largos eficientemente ayuda a evitar errores y a controlar los costos, ya que el precio es por millón de caracteres.

¿Qué es la marca de agua en el audio?

Cada archivo generado incluye una marca de agua inaudible que indica que es voz sintética. Esto ayuda a identificar el origen del audio como generado por la API. No afecta la calidad auditiva ni el peso del archivo, pero sirve como una firma digital de autenticidad.

¿Se puede usar para llamadas salientes?

Sí, puedes integrar la API en sistemas de llamadas salientes (IVR) para generar respuestas de voz. Sin embargo, no hay streaming en tiempo real; debes generar el audio por adelantado o por fragmentos. Esto requiere una lógica de cola en tu backend para manejar la latencia de generación.

¿Cómo se audita el uso de la API?

Se mantiene un registro de metadatos de la solicitud, incluyendo hora, número de caracteres y estado. Esta información está disponible en tu panel de cuenta para verificar el consumo y el saldo. Los datos se conservan para facturación y control de uso, pero el audio generado no se almacena.

¿Se puede usar para videos de marketing?

Sí, puedes generar audio para videos de marketing. Los formatos soportados incluyen mp3, wav, opus, flac y pcm. Recuerda que el audio lleva una marca de agua inaudible que indica su origen sintético. No hay restricciones de uso para contenido publicitario, pero debes gestionar la longitud del texto.

Paso 1: Creación de cuenta

Ilustración de onda de sonido para: Paso 1: Creación de cuenta

Accede a /get-api-key/ y regístrate con tu cuenta de Google para obtener un crédito de prueba inmediato de $0.50, válido por 7 días. Si prefieres usar correo electrónico y contraseña, la cuenta se crea sin saldo inicial.

La clave API se muestra automáticamente en el panel. Cada cuenta mantiene una sola clave activa; al emitir una nueva, la anterior deja de funcionar al instante.

Registro con Google

El registro es instantáneo y asigna automáticamente $0.50 de crédito, equivalente a unos 50 000 caracteres. Este saldo permite probar la integración sin necesidad de tarjetas ni suscripciones mensuales.

Obtención de clave

Tu clave única (formato tts-...) aparece en el panel de control. Úsala en el encabezado Authorization: Bearer. Si necesitas revocar el acceso, simplemente genera una nueva clave desde la misma interfaz.

Verificación de saldo

El panel muestra tu balance actual, el crédito de prueba restante y los caracteres consumidos. No hay facturación automática ni cargos sorpresa; el saldo no expira y se recarga manualmente mediante USDT en la red TRON.

  • Mínimo de recarga: $5 USD en USDT (TRC-20).

Paso 2: Configuración del SDK

Ilustración de onda de sonido para: Paso 2: Configuración del SDK

Para consumir la API de VozBanco, puedes usar el SDK de OpenAI, ya que la estructura de las solicitudes es compatible con la de OpenAI. Solo necesitas ajustar la URL base y la clave de autenticación para apuntar a nuestra infraestructura.

Instalación del paquete

Instala la biblioteca estándar de OpenAI en tu entorno de desarrollo. Esta librería manejará la codificación JSON y la firma de las solicitudes HTTP necesarias para la generación de audio.

  • Necesitas Python 3.7+ o Node.js 18+
  • Paquete: openai (versión más reciente)

Configuración de base_url

Debes apuntar el cliente a nuestra infraestructura específica. Configura la variable base_url hacia https://api.getx33.com/v1. Esto asegura que tus solicitudes lleguen al endpoint correcto para la síntesis de voz.

Inicialización del cliente

Inicializa el cliente de la API utilizando tu clave secreta obtenida en el panel de control. Asegúrate de que la variable de entorno o la constante contenga el prefijo tts- para una autenticación correcta.

Paso 3: Primera solicitud

Ilustración de onda de sonido para: Paso 3: Primera solicitud

Una vez configurado el cliente, envía una solicitud POST a https://api.getx33.com/v1/audio/speech. El cuerpo debe contener el texto a sintetizar, el modelo y la voz seleccionada. Esto devuelve un archivo de audio listo para reproducir.

Para notificaciones de pago, el texto debe ser claro y conciso. La API procesa las solicitudes secuencialmente, por lo que en momentos de alta demanda podría haber una pequeña espera antes de recibir el audio.

Texto de ejemplo

Envía un JSON con el campo input. Por ejemplo: `{"model": "tts-1", "voice": "atlas", "input": "Tu pago de $50.00 ha sido procesado correctamente."}`. El texto tiene un límite de 4096 caracteres por solicitud.

Parámetros de voz

Elige entre 8 voces preestablecidas. Para alertas financieras, atlas ofrece un tono neutral y claro, ideal para noticias. milo es más conversacional si prefieres un tono más amigable. Ajusta la velocidad entre 0.25 y 4.0 si es necesario.

  • Modelos: tts-1 o tts-1-hd (mismo motor).
  • Voz: atlas (neutral, noticias) o milo (amigable).
  • Velocidad: rango de 0.25 a 4.0.

Recepción del audio

La respuesta contiene el archivo de audio binario. Puedes guardarlo o reproducirlo directamente en tu app. Los formatos disponibles son mp3, wav, opus, flac o pcm.

Si la síntesis falla, no se cobra. El audio se genera en tiempo real aproximado, aunque frases cortas pueden tardar unos segundos.

Paso 4: Manejo de textos largos

Ilustración de onda de sonido para: Paso 4: Manejo de textos largos

Para mensajes extensos como resúmenes de transacciones o alertas detalladas, la API limita cada solicitud a 4096 caracteres. Es necesario dividir el texto en partes más pequeñas y generar el audio para cada segmento por separado.

Una vez obtenidos los archivos de audio individuales, se unen para formar el mensaje completo. Este enfoque asegura que cada fragmento se sintetice correctamente sin exceder los límites de la solicitud.

División en partes

Divide el texto en bloques de máximo 4096 caracteres. Cada bloque se envía como una solicitud independiente a la API.

  • Calcula la longitud del texto antes de enviarlo.

Unión de archivos

Recepciona los archivos de audio generados para cada parte. Utiliza una librería de audio o concatenación básica para unirlos en un solo archivo final.

Límite de 4096 caracteres

El límite es estricto por solicitud. Los espacios y puntuación cuentan como caracteres. Si excedes este límite, la API rechazará la solicitud.

Paso 5: Selección de voz

Ilustración de onda de sonido para: Paso 5: Selección de voz

La elección de la voz afecta directamente la claridad de las notificaciones de pago y alertas en tu aplicación. VozBanco ofrece ocho presets diseñados para distintos contextos, permitiendo seleccionar el tono adecuado.

Voz Atlas para noticias

Atlas es una voz masculina neutral, ideal para informar sobre transacciones recientes o actualizaciones de saldo. Su tono objetivo facilita la comprensión rápida en entornos de fintech donde la precisión es crítica.

Voz Luna para historia

Luna es una voz femenina suave, ideal para narrar historias.

Voz Milo para conversación

Milo es una voz masculina amigable y conversacional. Funciona bien para recordatorios amables o instrucciones paso a paso, manteniendo un tono cercano sin perder la claridad técnica necesaria para la operación.

Paso 6: Formatos de audio

Ilustración de onda de sonido para: Paso 6: Formatos de audio

La API de VozBanco permite especificar el formato de salida mediante el parámetro response_format. Esto es crucial para equilibrar la calidad del audio, el ancho de banda y la compatibilidad con los reproductores de tus aplicaciones de notificaciones bancarias.

MP3 para web

El formato MP3 es ideal para la mayoría de las interfaces web y móviles. Ofrece una buena relación entre calidad y tamaño de archivo, facilitando la carga rápida en las notificaciones de pago sin consumir demasiados recursos del cliente.

WAV para calidad

Si necesitas audio sin pérdida para validaciones críticas o sistemas legacy, WAV es la opción adecuada. Aunque los archivos son más grandes, garantizan una fidelidad completa del audio generado, útil para pruebas de calidad o integraciones que requieren formato no comprimido.

OPUS para eficiencia

OPUS ofrece la mejor compresión para su calidad, reduciendo significativamente el uso de ancho de banda. Es excelente para notificaciones masivas en entornos con restricciones de datos móviles, manteniendo la inteligibilidad clara de las alertas financieras.

Paso 7: Manejo de errores

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

Las notificaciones de pago requieren fiabilidad. Cuando la síntesis falla, el cargo se devuelve íntegramente, evitando costos imprevistos en tu cuenta bancaria.

El manejo correcto de errores garantiza que tus alertas de validación o confirmación de saldo lleguen sin perder dinero en solicitudes fallidas.

Códigos de error

Si la síntesis falla, la carga se devuelve en su totalidad. Esto permite verificar el saldo sin penalización económica, manteniendo la predictibilidad del costo por carácter.

Reintento de solicitudes

Implementa un reintento simple para errores transitorios. Dado que las solicitudes se procesan en cola, un error temporal puede resolverse con una nueva petición sin costo adicional si falla.

Límites de velocidad

El límite es de 60 solicitudes por minuto por clave (10 antes del primer recarga). Supera este límite y las peticiones se encolan o fallan, afectando la entrega de alertas en tiempo real.

  • 60 req/min por clave activa.
  • 10 req/min antes del primer top-up.
  • Procesamiento secuencial bajo carga.
Paso 7: Manejo de errores

Paso 8: Optimización de costos

Ilustración de onda de sonido para: Paso 8: Optimización de costos

Optimizar el costo de la API TTS requiere entender que cada carácter cuenta, incluyendo espacios y puntuación. El precio fijo es de $0.01 por cada 1.000 caracteres procesados, con facturación precisa por solicitud. Para notificaciones de pagos, la pre-generación de audios para mensajes estáticos (como 'tu transferencia ha sido completada') reduce la carga computacional en tiempo real.

El uso de caché es la estrategia más efectiva para ahorrar. Si el texto de la alerta no varía, guarda el archivo de audio generado y reutilízalo. Esto evita gastar crédito en repetición de síntesis idéntica y acelera la entrega al usuario final, manteniendo los costos predecibles en alto volumen.

Pre-generación de audios

Genera los audios por anticipado para mensajes de plantilla que no contienen datos dinámicos complejos. Esto es ideal para confirmaciones de pago estándar donde la variación es mínima.

Así reduces la latencia de la API y el consumo de caracteres en tiempo real, pagando solo por las partes únicas del mensaje.

  • Identifica mensajes de plantilla repetitivos.
  • Genera y almacena los archivos de audio.
  • Usa la API solo para datos dinámicos (montos, fechas).

Uso de cache

Almacena los audios generados en tu servidor o CDN. Si el texto es idéntico, devuelve el archivo guardado en lugar de hacer una nueva solicitud.

Esto es crucial para alertas de validación o notificaciones de estado que se repiten frecuentemente.

  • Implementa una lógica de caché basada en el hash del texto.
  • Establece una vida útil (TTL) adecuada para tus datos.
  • Invalida el caché cuando cambie el contexto del mensaje.

Monitoreo de uso

Revisa regularmente el panel de tu cuenta para ver el consumo de caracteres y el saldo restante. Aunque las solicitudes fallidas son gratuitas, las exitosas se facturan al instante.

Monitorea la velocidad de generación para anticipar cuellos de botella que puedan afectar la experiencia del usuario en notificaciones críticas.

  • Revisa el saldo y caracteres usados en /get-api-key/.
  • Configura alertas si el uso supera un umbral esperado.
  • Audita los logs de solicitudes para detectar patrones inusuales.

Paso 9: Pruebas en producción

Ilustración de onda de sonido para: Paso 9: Pruebas en producción

Antes de activar las notificaciones masivas, utiliza el crédito de prueba gratuito de $0.50 disponible al registrarte con Google para validar el flujo completo sin riesgo financiero. Este saldo equivale a aproximadamente 50 000 caracteres y expira en 7 días. Las cuentas creadas con correo y contraseña no reciben este crédito de prueba.

La validación técnica asegura que la integración responda correctamente a los límites de la API y que el tono de voz se alinee con la experiencia del usuario final en el contexto bancario.

Uso del crédito de prueba

Al crear una cuenta con Google, se asignan automáticamente $0.50 de crédito válido por 7 días. Este saldo permite generar hasta 50 000 caracteres, suficientes para probar varias voces y formatos antes de realizar una recarga vía USDT.

Si te registras con correo y contraseña, no recibirás este crédito inicial. Considera usar Google para pruebas rápidas o recargar un mínimo de $5 para validar el flujo de pago en un entorno más realista.

  • Crédito: $0.50 (~50k caracteres).
  • Vigencia: 7 días desde la creación.
  • Cuenta con email: sin crédito inicial.

Verificación de idioma

La API detecta automáticamente el idioma según el script del texto (por ejemplo, texto en latín se asume inglés por defecto). Para textos en español o portugués, especifica siempre el parámetro language para evitar errores de pronunciación.

Prueba frases típicas de notificaciones bancarias, como confirmaciones de transferencia o alertas de saldo bajo, para asegurar que la síntesis reconoce correctamente los números, monedas y nombres propios en el idioma objetivo.

  • Defecto: inglés para texto latino.
  • Recomendado: definir language explícitamente.
  • Idiomas soportados: 23, incluyendo español.

Validación de tono

Evalúa si la voz seleccionada transmite el tono adecuado. Por ejemplo, usa atlas para notificaciones neutras o milo para recordatorios amigables. Genera una muestra corta y escúchala para verificar la naturalidad.

Asegúrate de que el audio generado no contenga pausas extrañas o entonaciones inadecuadas que puedan confundir al usuario final. Una validación rápida evita malentendidos en notificaciones críticas de seguridad o pagos.

  • Usa atlas para中性.
  • Usa miló para conversacional.
  • Escucha muestras antes de producción.

Paso 10: Despliegue final

Ilustración de onda de sonido para: Paso 10: Despliegue final

Una vez desplegada la API de VozBanco, es fundamental observar cómo se procesan las solicitudes en la cola. Las peticiones se ejecutan en secuencia; bajo alta carga, las notificaciones de pagos pueden experimentar retrasos breves antes de generarse el audio.

La gestión de claves asegura la integridad de tu facturación. Cada cuenta cuenta con una clave activa única. Si detectas un uso no autorizado, puedes emitir una nueva clave inmediatamente, lo que invalida la anterior al instante.

Monitoreo de cola

Los textos largos se dividen en partes de hasta 4096 caracteres y se procesan uno tras otro. Esto significa que el tiempo de generación es aproximadamente en tiempo real, pero bajo congestión, las alertas de validación podrían esperarse en la cola antes de ser servidas.

Monitorea los tiempos de respuesta para ajustar tus umbrales de alerta. Si una notificación crítica tarda más de lo esperado, verifica si hay picos de demanda que estén saturando la cola de procesamiento.

  • Las peticiones se procesan secuencialmente
  • Los retrasos ocurren bajo alta carga
  • El tiempo es aproximadamente en tiempo real

Gestión de claves

Tu cuenta mantiene una sola clave activa. Esta clave se utiliza para autenticar todas las solicitudes a la API. Si decides rotarla, la clave antigua deja de funcionar de inmediato al emitir la nueva.

Guarda tu clave en variables de entorno seguras en tus servidores de producción. La emisión de una nueva clave detiene el uso de la anterior instantáneamente, facilitando la respuesta ante posibles incidencias de seguridad.

Revisa tu saldo y uso en la página de tu cuenta para mantener el control de los costos por carácter consumido.

  • Una clave activa por cuenta
  • Rotación inmediata al emitir nueva clave
  • Invalidación instantánea de la clave anterior

Soporte por correo

El soporte de VozBanco se realiza exclusivamente por correo electrónico. No disponemos de número de teléfono, chat en vivo ni garantía de tiempo de respuesta (SLA).

Para incidencias con facturación, claves o detalles técnicos de la API, envía tu consulta al soporte. Incluye tu ID de cuenta y detalles de la solicitud fallida para una resolución más rápida.

  • Soporte exclusivo por correo electrónico
  • Sin teléfono ni chat en vivo
  • Sin garantía SLA de respuesta

Ejemplo de código completo

Ilustración de onda de sonido para: Ejemplo de código completo

Estos ejemplos muestran cómo generar audio de notificaciones de pago utilizando la API de VozBanco. Cada snippet demuestra la estructura JSON y la autenticación necesaria para obtener un archivo de audio listo para integrar en tus sistemas de alertas.

El código incluye la configuración de la URL base, el envío de la voz 'atlas' para un tono neutral adecuado para noticias financieras, y el manejo de la respuesta binaria.

Script en Python

Usa la librería openai con la URL base apuntando a https://api.getx33.com/v1. Configura la clave Bearer y envía el texto de la notificación. El SDK maneja la descarga del archivo de audio generado.

Script en Node.js

Utiliza el paquete openai de Node.js. Asegúrate de cambiar el baseUrl a https://api.getx33.com/v1. El código envía la solicitud POST y guarda el buffer de audio en disco o lo envía directamente al cliente.

Ejemplo con cURL

Un comando directo para probar la integración sin dependencias. Reemplaza tts-tu-clave con tu clave real y ajusta el texto en el cuerpo JSON. Este método es ideal para validaciones rápidas en entornos de desarrollo.

Recursos adicionales

Ilustración de onda de sonido para: Recursos adicionales

Consulte la documentación completa en /docs/ para detalles técnicos de la API, incluyendo especificaciones de endpoints y modelos. Acceda a /pricing/ para entender la estructura de costos por carácter y a /get-api-key/ para gestionar su clave y saldo.

Estos recursos complementan la guía paso a paso, ofreciendo referencias rápidas para la integración técnica y la gestión de la cuenta sin ambigüedades.

Documentación completa

La documentación técnica detalla el esquema de la API, los parámetros de la solicitud y los formatos de respuesta. Incluye ejemplos de código en Python, Node.js y cURL para facilitar la integración en sus sistemas de notificación bancaria.

  • Especificaciones de endpoints /v1/audio/speech y /v1/voices
  • Ejemplos de integración con OpenAI SDK
  • Descripción detallada de modelos tts-1 y tts-1-hd

Ejemplos de voz

Explore las ocho voces disponibles en /docs/.

  • Atlas: tono neutral ideal para noticias de pago
  • Luna: estilo suave para confirmaciones de historial
  • Milo: conversación amigable para validaciones de usuario

Guía de idiomas

La API soporta 23 idiomas, incluyendo español, inglés y portugués para mercados latinoamericanos. Consulte la lista completa en /docs/ para verificar el código ISO necesario y evitar errores de predicción de idioma en textos en español.

  • Español, Inglés, Portugués, Francés, Alemán
  • Código ISO opcional para forzar idioma
  • Soporte para 23 idiomas listados

Escucha las 8 voces

Cada muestra a continuación fue generada por esta API a partir de la misma frase. Si el texto de la alerta no varía, guarda el archivo de audio generado y reutilízalo.

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. openai-python on GitHub
  3. ISO 639 language codes
  4. FFmpeg documentation
  5. Node.js documentation
  6. Tether (USDT)
  7. IETF RFC 7845: Ogg Opus
  8. Creative Commons Attribution 4.0
  9. curl documentation
  10. LibriTTS-R corpus (OpenSLR 141)
  11. LibriTTS-R paper (arXiv 2305.18802)
  12. TRON developer hub: TRC-20

Más en este sitio