Preguntas frecuentes
¿Qué es la API de texto a voz VkyText?
VkyText es una API de texto a voz en la nube para equipos de TI en banca. Envías texto y recibes un archivo de audio mediante una llamada POST. Su formato de respuesta es compatible con los estándares abiertos, facilitando la integración con los sistemas de notificación existentes sin complicaciones de infraestructura.
¿Cómo funciona la conversión de texto a audio?
Realizas una petición POST al endpoint /v1/audio/speech con el texto y la voz deseada. El sistema procesa la solicitud y devuelve el archivo de audio. Para textos largos, se dividen en partes de 4096 caracteres y se unen los archivos resultantes, manteniendo la coherencia en las notificaciones.
¿Qué voces están disponibles para notificaciones bancarias?
Disponemos de ocho voces preestablecidas. Para entornos financieros, atlas ofrece un tono neutral ideal para noticias, mientras que sage es calmado para instrucciones. Otras opciones incluyen aria, nova, luna, felix, milo y orion, todas basadas en grabaciones licenciadas y aptas para diferentes tipos de avisos transaccionales.
¿Cuántos idiomas soporta la API?
La API soporta 23 idiomas, incluyendo inglés, español, alemán, francés, japonés, chino, árabe y ruso. Cualquier voz puede hablar cualquiera de estos idiomas. Si no se especifica el idioma, se intenta adivinar por el script (el texto en latín por defecto es inglés), pero se recomienda establecerlo explícitamente para textos en latín no inglés.
¿Es la prueba gratuita real o tiene limitaciones?
La prueba otorga $0.50 de crédito (aprox. 50 000 caracteres) válidos por 7 días al registrarse con Google. Si usas email y contraseña, no recibes crédito inicial.
¿Cómo se cobra por el uso de la API?
El costo es de $10 por cada millón de caracteres, lo que equivale a $0.01 por 1 000 caracteres. Los espacios y puntuación cuentan. El pago se realiza mediante top-ups en USDT (TRC-20). No hay planes mensuales ni cargos fijos; pagas solo por los caracteres procesados con éxito.
¿Qué formatos de audio se pueden generar?
Puedes solicitar los formatos mp3, wav, opus, flac o pcm mediante el campo response_format. Estos formatos estándar permiten una fácil integración con los reproductores y sistemas de notificación existentes en la banca. El formato elegido se devuelve directamente en la respuesta de la API.
¿Se puede controlar la velocidad de la voz?
Sí, el parámetro speed permite ajustar la velocidad entre 0.25 y 4.0. Esto facilita adaptar la duración de las notificaciones a las necesidades del usuario final. La velocidad se aplica directamente al motor de síntesis, permitiendo ajustes finos para diferentes tipos de mensajes transaccionales.
¿Qué sucede si una solicitud falla?
Si la síntesis falla, la carga se devuelve íntegramente. No se cobra por las peticiones que no generan audio correctamente. Esto asegura que tu facturación refleje únicamente el trabajo completado. Puedes reintentar la solicitud o verificar los parámetros de entrada como el texto o la voz seleccionada.
¿Se almacena el texto enviado para entrenamiento?
No. El texto de entrada se utiliza exclusivamente para producir el audio de la notificación y no se emplea para entrenar modelos. Los archivos de audio generados se devuelven en la respuesta y no se almacenan. Solo se conservan metadatos de la solicitud para fines de facturación.
¿Cómo se gestionan las claves de API?
Cada cuenta tiene una clave activa. Puedes emitir una nueva clave en cualquier momento desde tu panel, lo que invalida la anterior inmediatamente. La autenticación se realiza mediante el encabezado Authorization: Bearer. Esto facilita la rotación de credenciales en los sistemas de notificación de tu infraestructura bancaria.
¿Hay límite de caracteres por solicitud?
Sí, cada solicitud puede contener hasta 4096 caracteres. Para textos más largos, debes dividirlos en partes y unir los archivos de audio resultantes. Esto garantiza un procesamiento eficiente. Los límites de caracteres incluyen espacios y puntuación, por lo que debes calcular el tamaño del texto antes de enviar.
¿Qué ocurre si se excede el límite de peticiones?
El límite es de 60 solicitudes por minuto por clave (10 antes del primer recargo). Si excedes este límite, las peticiones pueden esperar en una cola o recibir un error. Esto asegura la estabilidad del servicio. Monitorea tu tasa de solicitudes para mantener la fluidez en las notificaciones masivas.
¿Ofrecen soporte para integración en tiempo real?
No ofrecemos streaming, WebSocket ni audio parcial en tiempo real. La API devuelve el archivo completo tras procesar la solicitud. Aunque la generación es rápida, las peticiones se procesan una tras otra, por lo que bajo carga pueden esperar en una cola. Para integraciones que requieren audio instantáneo parcial, esta API puede no ser la opción adecuada.
Concepto básico de la API TTS
La API de VkyText convierte texto en audio mediante un proceso directo: se envía una cadena de caracteres y se recibe un archivo de sonido. Este modelo elimina la necesidad de infraestructura compleja para la síntesis de voz.
El servicio opera como un servicio en la nube estándar, permitiendo la integración rápida en los sistemas de notificación bancaria existentes sin dependencias de librerías propietarias.
Entrada de texto y salida de audio
La entrada es una cadena de texto plano, con un límite de 4096 caracteres por solicitud. La salida es un archivo de audio generado instantáneamente, listo para reproducirse en el canal de notificación elegido.
Endpoint POST estándar
La comunicación se realiza mediante una solicitud HTTP POST al endpoint https://api.vkyat.info/v1/audio/speech. Este diseño sigue patrones reconocidos por los desarrolladores de TI, facilitando la implementación.
Formato JSON unificado
El cuerpo de la solicitud utiliza formato JSON, especificando el modelo, el texto de entrada, la voz deseada y el formato de respuesta. Esta estructura estandarizada simplifica el parsing en cualquier lenguaje de programación moderno.
Proceso de solicitud y respuesta
La integración comienza con una petición POST al endpoint de la API, enviando el texto de la notificación bancaria en formato JSON. El sistema recibe los parámetros de modelo, voz y formato deseado para iniciar la síntesis.
Envío de datos al servidor
Se envía el texto a sintetizar junto con la configuración de voz y el idioma. La API valida la autenticación y los límites de caracteres antes de procesar la solicitud.
- Cuerpo JSON con texto y metadatos
- Autenticación mediante token Bearer
- Validación inmediata de parámetros
Procesamiento de la voz
El motor de síntesis convierte el texto en audio utilizando las voces seleccionadas. El tiempo de generación depende de la longitud del texto, siendo aproximadamente en tiempo real para textos largos.
- Síntesis basada en motores tts-1 o tts-1-hd
- Latencia variable según cola de carga
- Generación de audio sintetizado
Descarga del archivo de audio
Una vez completada la síntesis, el archivo de audio se devuelve directamente en la respuesta HTTP. El sistema de notificación puede reproducirlo o almacenarlo temporalmente según su lógica interna.
Selección de voces para contextos financieros
La claridad en la transmisión de datos financieros es crítica. Para notificaciones de saldos, movimientos o alertas, se recomiendan voces como Atlas (neutral, estilo noticiero) o Sage (calma, instruccional). Estas presillas ofrecen una dicción precisa y un tono profesional que facilita la comprensión inmediata de cifras y plazos.
El tono consistente evita malentendidos en comunicaciones automatizadas. Al seleccionar una voz fija para un tipo de notificación específico, los equipos de TI garantizan que el usuario identifique instantáneamente el contexto de la alerta, ya sea informativa o transaccional.
Voces neutras y claras
Atlas proporciona un tono neutral, ideal para lectura de noticias financieras o reportes de movimientos. Sage ofrece una voz calmada y clara, adecuada para instrucciones paso a paso o confirmaciones de seguridad. Ambas evitan cargas emocionales innecesarias, priorizando la legibilidad del texto transaccional.
Las voces femeninas como Aria o Luna pueden usarse para contextos más narrativos, pero para datos duros, las opciones masculinas neutras suelen percibirse como más directas en entornos corporativos.
- Ausencia de entonación exagerada que distraiga del contenido numérico.
- Dicción precisa para números, fechas y montos en múltiples idiomas.
- Voz Atlas: neutral, estilo noticiero; Voz Sage: calma, instruccional.
Velocidad ajustable
El parámetro speed permite escalar la reproducción entre 0.25 y 4.0. En notificaciones de alta frecuencia, una velocidad de 1.0 a 1.5 mantiene el ritmo natural sin sacrificar comprensión. Para listas densas de transacciones, aumentar ligeramente la velocidad puede reducir el tiempo de lectura sin perder claridad.
La velocidad afecta la carga de procesamiento. Velocidades más altas generan audio más corto, optimizando el uso de la cuota de caracteres por minuto.
Consistencia en el tono
Mantener la misma voz para un tipo de notificación específico (ej. alertas de fraude vs. confirmaciones de pago) crea un patrón auditivo reconocible. Esto reduce la carga cognitiva del usuario final, que identifica el tipo de mensaje solo por la voz.
La consistencia es clave en sistemas de notificación masiva. Una voz fija asegura que todas las salidas de audio mantengan el mismo registro de confianza y profesionalismo, alineado con la identidad de la marca bancaria.
Manejo de texto largo en notificaciones
Las notificaciones bancarias suelen contener detalles extensos como movimientos de cuenta o alertas de seguridad que superan el límite de una sola solicitud. Para garantizar la entrega completa del audio, el sistema divide el texto de entrada en fragmentos manejables antes del procesamiento.
División en partes de 4096 caracteres
Cada solicitud POST acepta un máximo de 4096 caracteres, incluyendo espacios y puntuación. Si el texto de la notificación excede este límite, la aplicación cliente debe segmentarlo en bloques consecutivos que respeten esta restricción estricta.
Unión automática de archivos
Una vez que se han generado los fragmentos de audio individuales para cada parte del texto, la aplicación cliente debe unirlos. Esto elimina la necesidad de que el equipo de TI gestione la sincronización de múltiples archivos en los sistemas de notificación.
Límites de caracteres por petición
Es crítico respetar el límite de 4096 caracteres por llamada a la API. Si se supera, la solicitud puede fallar o truncarse. Para textos muy largos, como resúmenes mensuales, se recomienda implementar un bucle que envíe las partes y recopile los resultados.
Integración con sistemas existentes
Integrar VkyText en la infraestructura bancaria es directo gracias a su compatibilidad con el ecosistema estándar. Utilizamos el formato de solicitud de la API de OpenAI, lo que permite a los equipos de TI reutilizar las bibliotecas y clientes HTTP que ya conocen y mantienen, evitando la necesidad de aprender una sintaxis específica de un proveedor nuevo.
Uso de SDK de OpenAI
El endpoint y la estructura JSON son idénticos a los de OpenAI. Esto significa que puedes usar el SDK oficial de OpenAI cambiando la variable base_url, sin modificar la lógica de tu aplicación de notificaciones.
Adaptación de base_url
La única configuración técnica requerida es cambiar la variable base_url para apuntar a https://api.vkyat.info/v1. Esta simple modificación redirige todas las llamadas de síntesis a nuestro motor de voz sin alterar el código de tu sistema de alertas.
Autenticación con Bearer
La seguridad se gestiona mediante un token Bearer único por cuenta. Simplemente incluye tu clave API en el encabezado Authorization: Bearer <tu-clave> de cada solicitud. Si necesitas renovar la clave, la anterior deja de funcionar inmediatamente.
Control de calidad y formato
El formato de respuesta se adapta a los sistemas de notificación existentes mediante estándares abiertos. Se pueden elegir entre MP3, WAV, OPUS, FLAC o PCM según la compatibilidad del reproductor de audio del cliente.
Formatos MP3, WAV, OPUS
El formato MP3 es óptimo para reducir el ancho de banda en notificaciones móviles, mientras que WAV y FLAC garantizan la máxima fidelidad para archivado o reproducción en sistemas de contestadora fija.
Velocidad de reproducción
Ajusta la velocidad entre 0.25 y 4.0 para equilibrar la claridad auditiva con la eficiencia de transmisión. Una velocidad estándar facilita la comprensión de cifras y nombres en alertas financieras.
Detección de idioma
Si no se especifica, el sistema detecta el idioma por el script (por defecto inglés si es latín). Para textos en español u otros idiomas latinos, es recomendable establecer el parámetro language explícitamente para asegurar la pronunciación correcta.
Gestión de errores y fallos
Cuando la síntesis falla, el cargo se devuelve íntegramente. No se cobra por los caracteres intentados si el audio no se genera, lo que elimina el riesgo financiero en entornos de alta disponibilidad.
Los equipos de TI pueden confiar en que el costo coincide estrictamente con el audio entregado exitosamente, simplificando la auditoría de gastos en notificaciones transaccionales.
Solicitudes fallidas sin costo
Si la síntesis falla, el cargo se devuelve en su totalidad. Esto garantiza que solo se pague por audio generado con éxito, protegiendo el presupuesto de las notificaciones masivas.
La garantía de reembolso es automática y aplica inmediatamente tras la detección del fallo en el procesamiento del texto.
- Cobro solo por audio entregado
- Reembolso inmediato en caso de fallo
- Sincronización precisa con el saldo
Códigos de estado HTTP
La API responde con códigos estándar HTTP que permiten una integración robusta. Los códigos 2xx indican éxito, mientras que los 4xx y 5xx señalan errores de cliente o servidor respectivamente.
Estos códigos facilitan la implementación de lógica de manejo de errores sin necesidad de analizar cuerpos de respuesta complejos.
- Códigos 2xx para éxito
- Códigos 4xx para errores de cliente
- Códigos 5xx para errores del servidor
Reintentos automáticos
Se recomienda implementar reintentos automáticos en el cliente para manejar errores temporales. Dado que las solicitudes se procesan en cola, un breve retraso antes del reintento optimiza la tasa de éxito.
Los reintentos deben respetar los límites de tasa para evitar bloqueos adicionales, asegurando una integración fluida con los sistemas de notificación bancaria.
- Reintentos para errores temporales
- Respeto a los límites de tasa
- Implementación sencilla en SDKs
Seguridad y privacidad de datos
El texto que envías a la API se utiliza exclusivamente para generar el audio de la notificación bancaria. No se almacena ni se emplea para entrenar modelos de lenguaje, garantizando que tus datos transaccionales permanezcan confidenciales durante el procesamiento.
Texto no usado para entrenamiento
A diferencia de otros servicios, nuestro motor no retiene el contenido de tus mensajes para mejorar sus algoritmos. Una vez generado el audio, el texto original queda disponible solo para tu registro interno si lo deseas.
Audio no almacenado
El archivo de audio generado se devuelve en la respuesta de la API y no se guarda en nuestros servidores de forma persistente. Solo conservamos los metadatos de la solicitud (tiempo, caracteres, estado) estrictamente necesarios para la facturación y auditoría.
Claves de API únicas
Cada cuenta dispone de una única clave activa con alcance específico. Si detectas un uso no autorizado o deseas rotar credenciales, puedes emitir una nueva clave en cualquier momento; la anterior deja de funcionar inmediatamente.
- Autenticación mediante header
Authorization: Bearer - Emisión instantánea de nuevas claves
- Invalidación inmediata de claves antiguas
Ejemplo de uso en alertas de saldo
La API convierte texto transaccional en audio listo para notificaciones. Un ejemplo típico es alertar sobre un débito bancario.
Texto de ejemplo
Texto: "Su cuenta ha sido debitada con 150.00 USD. Saldo actual: 250.00 USD. Fecha: 24 de mayo de 2024."
Este texto incluye monto, saldo y fecha, datos críticos para la claridad en banca.
Solicitud curl
Envío POST a https://api.vkyat.info/v1/audio/speech con modelo tts-1, voz atlas y formato mp3.
Cuerpo JSON con el texto anterior y rate limit de 60 req/min.
- Modelo: tts-1
- Voz: atlas
- Formato: mp3
- Velocidad: 1.0
Resultado de audio
Archivo MP3 generado con voz neutra y clara.
Tiempo de generación: unos segundos, ya que las frases cortas toman tiempo de procesamiento.
Audio listo para reproducirse en la app o sistema de notificaciones.
Consideraciones para equipos de TI
Los equipos de TI deben configurar el límite de 60 solicitudes por minuto por clave API para evitar interrupciones en la generación de audio durante picos de notificaciones.
Este control es esencial para mantener la estabilidad del servicio y asegurar que las alertas críticas se procesen sin sobrecargar la cola de síntesis.
Límites de tasa (60 req/min)
La API permite 60 solicitudes por minuto por clave activa. Antes de la primera recarga, el límite es de 10 req/min.
Se recomienda implementar lógica de rate limiting en el lado del cliente o del servidor intermedio para respetar estos umbrales y evitar errores 429.
Colas de procesamiento
Las solicitudes se procesan secuencialmente. Bajo carga, las peticiones pueden esperar en una cola antes de iniciarse.
Esto garantiza la integridad de la generación de audio, aunque introduce un ligero retraso inicial en momentos de alta concurrencia.
Latencia en texto largo
La velocidad de generación es aproximadamente de 25 caracteres por segundo de audio. Textos extensos requieren división en partes de 4096 caracteres.
La latencia total incluye el tiempo de espera en cola más el procesamiento de cada fragmento y su unión final.
Comparación con otros métodos
Las notificaciones bancarias tradicionales combinan texto y audio pregrabado. Este enfoque limita la personalización y aumenta los costos de producción para cada variación de mensaje.
Las APIs TTS modernas ofrecen flexibilidad, pero suelen requerir integraciones complejas o SDKs propietarios. VkyText utiliza un formato estándar compatible con OpenAI, simplificando la adopción.
Vs. grabaciones estáticas
Las grabaciones estáticas son fijas en contenido y tono. Para cambiar un monto o nombre, se debe regenerar todo el archivo de audio.
Con TTS, el texto se inserta dinámicamente. Esto permite personalizar cada notificación sin crear archivos de audio adicionales para cada variante.
- Sin costos de producción por cada cambio de texto.
- Personalización en tiempo real para nombres y montos.
Vs. otras APIs TTS
Muchas APIs requieren SDKs específicos o formatos de solicitud únicos. Esto añade complejidad al integrar con sistemas bancarios existentes.
VkyText sigue el formato de solicitud de OpenAI. Los equipos de TI pueden usar librerías comunes cambiando solo la URL base.
- Menos código de adaptación necesario.
- Uso de bibliotecas estándar de la industria.
Ventajas de la estandarización
La estandarización reduce la curva de aprendizaje. Los desarrolladores ya conocen la estructura de las peticiones JSON y los campos de respuesta.
Esto acelera la integración y el mantenimiento a largo plazo. Es más fácil migrar o escalar si la interfaz es consistente.
- Documentación clara y ampliamente conocida.
- Integración más rápida con pipelines de notificaciones.
Soporte técnico y contacto
El soporte para VkyText se gestiona exclusivamente por correo electrónico, sin números de teléfono ni chat en vivo. Este canal permite enviar capturas de pantalla de respuestas de la API o detalles de facturación para un análisis preciso por parte de nuestro equipo técnico.
Para consultas generales, visite /contact/ en vkyat.info. No ofrecemos garantía de tiempo de actividad ni contratos corporativos, por lo que la comunicación es asíncrona y basada en tickets.
Email de soporte
Envie sus dudas a [email protected]. Indique siempre su clave de API y el ID de la transacción si es relevante para agilizar la revisión de logs de facturación o estado de síntesis.
- Respuesta en horario laboral
- Sin chat en vivo
- Sin número de teléfono
Documentación detallada
La documentación completa de la API está disponible en /docs/. Incluye ejemplos de código, especificación de campos y referencias de errores HTTP. Consulte /about/ para información sobre la infraestructura.
Comunidad de desarrolladores
Aunque no tenemos foros públicos moderados, los desarrolladores comparten snippets de integración en repositorios externos utilizando la base URL de VkyText. Revise la sección de preguntas frecuentes en la documentación para soluciones comunes a límites de tasa y formato JSON.
Escucha las 8 voces
Cada muestra a continuación fue generada por esta API a partir de la misma frase. Cada cuenta solo permite una clave activa; la emisión de una nueva revoca inmediatamente a la anterior.
23 idiomas
Cualquier voz puede hablar cualquiera de estos idiomas.
