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
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
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
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-1otts-1-hd(mismo motor). - Voz:
atlas(neutral, noticias) omilo(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
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
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
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
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 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
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
languageexplí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
atlaspara中性. - Usa
milópara conversacional. - Escucha muestras antes de producción.
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
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
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.
23 idiomas
Cualquier voz puede hablar cualquiera de estos idiomas.
