Documentación de la API de texto a voz para fintech

Por Equipo editorial VkyText · Actualizado 2026-11-19

Esta documentación está diseñada para equipos de TI en banca y fintech que necesitan integrar la API de texto a voz de VkyText en sus sistemas de notificación transaccional. Aquí encontrará los pasos técnicos para autenticarse, realizar la primera solicitud y gestionar los formatos de audio compatibles con sus infraestructuras existentes.

El contenido cubre la obtención de claves, el uso del SDK de OpenAI con la URL base personalizada, y la gestión de límites como los 60 solicitudes por minuto. También incluye ejemplos de código en Python y curl, junto con la explicación de parámetros como el modelo tts-1 y el formato de respuesta, para una integración predecible y sin complicaciones.

Documentación de la API de texto a voz para fintech

Preguntas frecuentes

¿Qué es la API de texto a voz VkyText?

Es una API en la nube que convierte texto en archivos de audio mediante una petición POST. Utiliza el mismo formato de solicitud que la API de speech de OpenAI, lo que permite usar sus SDKs oficiales cambiando solo la URL base. Es ideal para integrar generación de audio en sistemas de notificación existentes sin complejidades de infraestructura adicionales.

¿Cómo funciona la conversión de texto a audio?

Envía texto mediante POST a /v1/audio/speech y recibe un archivo de audio. El texto se divide en partes de hasta 4096 caracteres si excede el límite. La generación tarda aproximadamente un segundo por cada 25 caracteres de texto. Las solicitudes se procesan secuencialmente, por lo que bajo carga alta podrían esperar en una cola hasta ser atendidas.

¿Qué voces están disponibles para notificaciones bancarias?

Hay 8 voces preestablecidas: Aria, Nova, Luna y Sage (femeninas); Felix, Milo, Atlas y Orion (masculinas). Para banca, Atlas ofrece un tono neutral para noticias, Sage para instrucciones calmadas y Orion para documentales. Todas las voces pueden hablar en cualquiera de los 23 idiomas soportados sin necesidad de cambiar la configuración de voz.

¿Cuántos idiomas soporta la API?

Soporta 23 idiomas: árabe, chino, danés, neerlandés, inglés, finés, francés, alemán, griego, hebreo, hindi, italiano, japonés, coreano, malayo, noruego, polaco, portugués, ruso, español, suajili, sueco y turco. Si no se especifica el idioma, se adivina por el script; para texto en latín no inglés, debe configurarse manualmente para evitar errores de pronunciación.

¿Es la prueba gratuita real o tiene limitaciones?

Ofrece $0.50 de crédito (aprox. 50,000 caracteres) válidos por 7 días al registrarse con Google. Las cuentas creadas con email y contraseña no incluyen este crédito inicial. Es una prueba real y funcional, pero limitada en tiempo y saldo para evaluar la calidad del audio y la velocidad de generación antes de realizar una recarga.

¿Cómo se cobra por el uso de la API?

El costo es de $10 por cada millón de caracteres ($0.01 por 1,000 caracteres). Los espacios y puntuación cuentan como caracteres. La recarga se realiza mediante USDT en la red TRON (TRC-20), con un mínimo de $5. No hay planes mensuales ni cargos ocultos. El saldo no expira y se acredita automáticamente en minutos.

¿Qué formatos de audio se pueden generar?

Puede solicitar audio en los formatos mp3, wav, opus, flac o pcm mediante el campo response_format. Estos formatos estándar facilitan la integración con los sistemas de notificación existentes de bancos y fintech. No se ofrece streaming ni WebSocket; el audio se entrega completo al finalizar la solicitud POST.

¿Se puede controlar la velocidad de la voz?

Sí, el parámetro speed permite ajustar la velocidad entre 0.25 y 4.0. Esto es útil para adaptar las notificaciones transaccionales a diferentes contextos, como alertas rápidas o explicaciones detalladas. La velocidad afecta el tiempo de generación, pero el formato de respuesta y la estructura del audio permanecen consistentes.

¿Qué sucede si una solicitud falla?

Si la síntesis falla, el cargo se devuelve íntegramente. No se le cobra por las peticiones que no generan audio correctamente. Esto asegura que solo pague por el audio generado con éxito. Puede reintentar la solicitud o ajustar los parámetros de entrada según los errores devueltos en la respuesta de la API.

¿Se almacena el texto enviado para entrenamiento?

No. El texto de entrada se utiliza únicamente para producir el audio y no se usa para entrenamiento de modelos. El audio generado se devuelve en la respuesta y no se almacena en nuestros servidores. Solo se conservan los metadatos de la solicitud (tiempo, caracteres, estado) para fines de facturación y auditoría.

¿Cómo se gestionan las claves de API?

Cada cuenta tiene una clave activa. Puede emitir una nueva clave en cualquier momento desde su panel; la clave antigua deja de funcionar inmediatamente. La autenticación se realiza con el encabezado Authorization: Bearer tts-... Esto permite una rotación segura sin interrupciones prolongadas en los servicios de notificación de su infraestructura bancaria.

¿Hay límite de caracteres por solicitud?

Sí, cada solicitud POST acepta un máximo de 4096 caracteres en el campo input. Para textos más largos, debe dividirlos en partes y unir los archivos de audio resultantes. Esta limitación técnica facilita la gestión de errores y la integración con sistemas de notificación que procesan mensajes transaccionales de longitud variable.

¿Qué ocurre si se excede el límite de peticiones?

El límite es de 60 solicitudes por minuto por clave (10 por minuto antes del primer recargo). Si excede el límite, las solicitudes adicionales podrían esperar en una cola o recibir un error. Procesamos las peticiones secuencialmente, por lo que la carga alta puede aumentar ligeramente la latencia de generación de audio.

¿Ofrecen soporte para integración en tiempo real?

No ofrecemos streaming, WebSocket ni audio parcial. La API devuelve el archivo de audio completo tras procesar la solicitud. Para flujos de tiempo real estricto, debe gestionar la cola de solicitudes y la latencia de red. Es una API de petición-respuesta estándar, ideal para notificaciones asíncronas en banca.

Primera solicitud

curl

curl https://api.vkyat.info/v1/audio/speech \
  -H "Authorization: Bearer $TTS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"tts-1","voice":"aria","input":"Hello from the API.","response_format":"mp3"}' \
  --output hello.mp3

Python (openai)

from openai import OpenAI

client = OpenAI(base_url="https://api.vkyat.info/v1", api_key="tts-...")

with client.audio.speech.with_streaming_response.create(
    model="tts-1", voice="nova", input="Hello from Python.", response_format="mp3"
) as response:
    response.stream_to_file("hello.mp3")

Node.js (openai)

import OpenAI from "openai";
import fs from "node:fs";

const client = new OpenAI({ baseURL: "https://api.vkyat.info/v1", apiKey: process.env.TTS_API_KEY });
const res = await client.audio.speech.create({ model: "tts-1", voice: "milo", input: "Hello from Node.js." });
fs.writeFileSync("hello.mp3", Buffer.from(await res.arrayBuffer()));
voice
ariafemenino
novafemenino
lunafemenino
sagefemenino
felixmasculino
milomasculino
atlasmasculino
orionmasculino
language
arالعربية
zh中文
daDansk
nlNederlands
enEnglish
fiSuomi
frFrançais
deDeutsch
elΕλληνικά
heעברית
hiहिन्दी
itItaliano
ja日本語
ko한국어
msBahasa Melayu
noNorsk
plPolski
ptPortuguês
ruРусский
esEspañol
swKiswahili
svSvenska
trTürkçe

Obtención de la clave de API

Ilustración de onda de sonido para: Obtención de la clave de API

La obtención de la clave de API es el primer paso para integrar VkyText en sus sistemas de notificación bancaria. El acceso se gestiona directamente en la página /get-api-key/, donde puede registrar su cuenta utilizando su identidad de Google o un correo electrónico con contraseña.

Una vez autenticado, el panel le mostrará inmediatamente su clave Bearer activa junto con el saldo actual y el historial de uso. Esta clave es el único elemento necesario para autenticar todas las solicitudes a la API.

Registro con Google o email

Registro con Google o email

Al utilizar Google, se le asigna automáticamente un crédito de prueba de $0.50 válido durante 7 días, equivalente a aproximadamente 50 000 caracteres. Si prefiere registrarse con correo electrónico y contraseña, la cuenta se crea sin crédito de prueba inicial.

Las cuentas son específicas de este sitio web. Asegúrese de utilizar la misma credencial para mantener el acceso consistente a su clave y métricas de uso.

Ubicación de la clave en el panel

Ubicación de la clave en el panel

En la sección principal de su perfil, encontrará su clave de API en formato Bearer, lista para ser copiada. Junto a ella, se visualiza el saldo disponible, el estado del crédito de prueba y los caracteres consumidos.

Esta información se actualiza en tiempo real. Puede usar la clave directamente en encabezados HTTP o configurarla en variables de entorno para scripts de automatización.

  • Formato: tts-xxxxxxxxxxxxxxxxxxxx
  • Ubicación: Página /get-api-key/ de su panel

Revocación y nueva generación

Puede revocar su clave activa en cualquier momento desde el mismo panel. Al generar una nueva clave, la anterior deja de funcionar inmediatamente, lo que permite una gestión segura ante posibles fugas.

Este proceso no afecta su saldo ni su historial de facturación. Solo la nueva clave podrá realizar solicitudes de síntesis de voz.

Primera solicitud con curl

Ilustración de onda de sonido para: Primera solicitud con curl

Para generar audio desde la terminal, utiliza un comando POST directo a nuestro endpoint. Este método bypassa la necesidad de librerías complejas y permite verificar rápidamente la conectividad con la infraestructura de VkyText antes de integrar el flujo en aplicaciones de notificación bancaria.

El cuerpo de la solicitud debe contener únicamente los parámetros necesarios para la síntesis. Asegúrate de que el texto respete el límite de 4096 caracteres y que la clave de autenticación se pase en el encabezado Authorization.

Comando POST estándar

Envía una petición POST a la URL base de la API. La estructura sigue el estándar de OpenAI, por lo que puedes usar cualquier cliente HTTP que soporte JSON.

Cuerpo JSON de ejemplo

El siguiente ejemplo muestra la estructura mínima requerida para generar un archivo de audio en formato MP3.

  • "model": "tts-1"
  • "voice": "nova"
  • "input": "Your balance is low."
  • "response_format": "mp3"

Verificación de respuesta

Una respuesta exitosa devuelve el archivo de audio binario directamente en el cuerpo. Si la solicitud falla, recibirás un código de estado HTTP específico y un mensaje de error claro.

Uso con SDK de OpenAI

Ilustración de onda de sonido para: Uso con SDK de OpenAI

La API de VkyText es compatible con el formato de solicitud de la API de OpenAI, lo que permite utilizar los SDK oficiales con mínimas modificaciones. Al cambiar la URL base, los desarrolladores pueden aprovechar la infraestructura de clientes ya conocida para integrar la síntesis de voz en sus flujos de trabajo de banca y fintech sin aprender una nueva biblioteca desde cero.

Esta aproximación reduce la fricción técnica al permitir que los equipos de TI reutilicen el código existente, ajustando únicamente la configuración de conexión. El formato JSON de entrada permanece idéntico, garantizando que las llamadas a la API se procesen correctamente con los motores tts-1 o tts-1-hd.

Cambio de base_url

Para utilizar el SDK de OpenAI con VkyText, modifique la propiedad base_url para apuntar a https://api.vkyat.info/v1. Esta dirección es la raíz para todas las solicitudes de la API, incluyendo la generación de audio y la obtención de la lista de voces disponibles.

Compatibilidad con Python

El SDK oficial de OpenAI para Python funciona directamente con VkyText sin necesidad de adaptadores adicionales. Basta con instanciar el cliente de voz y proporcionar la URL base modificada. Las llamadas al endpoint /v1/audio/speech se serializan correctamente según el formato esperado por nuestra API.

Configuración de credenciales

Proporcione su clave API de VkyText en la cabecera Authorization usando el prefijo Bearer. La clave se obtiene en su panel de control tras registrarse con Google o correo electrónico. Asegúrese de que la clave tenga saldo suficiente o haya sido validada para evitar errores de autenticación.

Formatos de audio soportados

Ilustración de onda de sonido para: Formatos de audio soportados

La API devuelve audio binario directamente en la respuesta. Puedes seleccionar el formato de salida mediante el campo response_format en tu solicitud JSON. Esto permite elegir el equilibrio adecuado entre compatibilidad de reproductores y eficiencia de ancho de banda para tus sistemas de notificación.

MP3 para compatibilidad web

El formato MP3 es la opción predeterminada y ofrece la máxima compatibilidad con reproductores web y móviles. Es ideal para notificaciones de voz automatizadas que deben reproducirse en cualquier dispositivo sin requerir codecs adicionales.

  • Compatible con HTML5 <audio> nativo
  • Tamaño de archivo reducido para menor latencia
  • Calidad suficiente para voz transaccional

WAV para calidad lossless

WAV proporciona audio sin pérdida, manteniendo la fidelidad exacta de la voz sintética. Este formato es útil cuando tus sistemas de procesamiento de audio downstream requieren datos cridos sin compresión, aunque ocupa más espacio de almacenamiento.

  • Calidad de audio original sin compresión
  • Ideal para procesamiento posterior en backend
  • Requiere mayor ancho de banda

OPUS y FLAC para eficiencia

OPUS ofrece una compresión eficiente manteniendo buena calidad, mientras que FLAC garantiza pérdida cero con archivos más pequeños que WAV. Ambos formatos son opciones válidas para optimizar el almacenamiento o la transmisión de grandes volúmenes de audios generados.

  • OPUS: alta compresión con buena calidad
  • FLAC: pérdida cero, menor que WAV
  • Útiles para archivado a largo plazo

Límites y cuotas de uso

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

La API TTS de VkyText está diseñada para manejar volúmenes transaccionales con límites claros y predecibles. Cada clave de API tiene un límite de 60 solicitudes por minuto, lo que permite integrarla en sistemas de notificación sin bloqueos inesperados.

60 requests por minuto

Este límite se aplica por clave activa y se mide en ventanas deslizantes. Para la mayoría de las integraciones de banca, 60 solicitudes por minuto son suficientes para procesar alertas de saldo o movimientos en tiempo real sin saturar el sistema.

10 requests antes del primer pago

Antes de realizar tu primera recarga, la cuota se reduce a 10 solicitudes por minuto. Este estado inicial permite probar la integración con cargas bajas. Una vez que se acredita la primera transferencia de USDT (TRC-20), el límite vuelve automáticamente a 60 rpm.

Cola de procesamiento

Las solicitudes se procesan en orden secuencial. Si excedes la tasa o hay alta demanda, las peticiones se encolan y se ejecutan una tras otra. El tiempo de generación es aproximadamente en tiempo real, por lo que textos largos pueden tardar más, pero la cola garantiza que no se pierdan datos.

Límites y cuotas de uso

Manejo de errores comunes

Ilustración de onda de sonido para: Manejo de errores comunes

La API devuelve códigos de estado HTTP estándar para indicar el estado de cada solicitud. Identificar rápidamente el tipo de error permite ajustar la lógica de reintento o la validación de entrada en sus pipelines de notificación bancaria.

Este enfoque minimiza tiempos de inactividad en la generación de audios transaccionales y facilita la integración con sistemas de monitoreo existentes.

Clave inválida

Si la cabecera Authorization contiene un token incorrecto o expirado, la API responde con 401 Unauthorized. Asegúrese de que su clave comience con tts- y esté activa.

Revocar y generar una nueva clave detiene inmediatamente la anterior. Si el error persiste, verifique que no haya copiado espacios extra en la cadena de la clave.

  • Código de estado: 401
  • Acción: Revocar clave en /get-api-key/

Límite de caracteres excedido

Cada solicitud acepta un máximo de 4096 caracteres en el campo input. Si su texto transaccional excede este límite, la API rechazará la petición con 400 Bad Request. Divida el texto en fragmentos más pequeños antes de enviar.

  • Máximo: 4096 caracteres por solicitud
  • Incluye espacios y puntuación

Error de formato JSON

Si el cuerpo de la solicitud no es un JSON válido o falta el campo input, se retornará 400. Verifique que la codificación sea UTF-8 y que no haya caracteres no escapados en las cadenas de texto.

Un formato incorrecto evita la síntesis y no consume crédito, pero requiere corrección manual del payload antes del reintento.

  • Verificar estructura JSON
  • Usar validadores antes del envío

Parámetros de la solicitud

Ilustración de onda de sonido para: Parámetros de la solicitud

La API acepta dos modelos con el mismo motor de síntesis y precio: tts-1 y tts-1-hd. Ambos reciben la misma tarifa de $10 por millón de caracteres, por lo que la elección depende exclusivamente de la preferencia de calidad de audio deseada para las notificaciones transaccionales.

Los parámetros de voz, velocidad e idioma permiten ajustar la entrega. Puede seleccionar entre ocho voces predefinidas (como aria para narración o atlas para noticias) y ajustar la velocidad entre 0.25 y 4.0.

Modelo tts-1 y tts-1-hd

Seleccione tts-1 o tts-1-hd según sus necesidades de calidad. Ambos utilizan el mismo motor de generación y tienen idéntico costo por carácter, facilitando la previsión de gastos sin sorpresas en la facturación.

Voz y velocidad

El campo voice acepta valores como aria, nova, luna, sage, felix, milo, atlas u orion. Ajuste speed entre 0.25 y 4.0 para optimizar la duración del audio generado sin afectar la inteligibilidad del mensaje.

  • Voces femeninas: aria, nova, luna, sage
  • Voces masculinas: felix, milo, atlas, orion
  • Velocidad configurable de 0.25x a 4.0x

Idioma opcional

Si omite language, el sistema infiere el idioma basándose en el script (el texto en latín se asume inglés por defecto). Para textos en español u otros idiomas con script latino, especifique el código ISO para garantizar la pronunciación correcta.

Ejemplos de código para integración

Ilustración de onda de sonido para: Ejemplos de código para integración

Estos ejemplos ilustran la integración directa con sistemas de notificación transaccional, priorizando la fiabilidad y la claridad en la recepción del audio.

Cada snippet está diseñado para minimizar la complejidad de infraestructura, permitiendo a los equipos de TI automatizar la generación de avisos de saldo o alertas de seguridad sin dependencias pesadas.

Script Python básico

Utilice la librería requests para enviar el texto y recibir el archivo binario. Es fundamental verificar que el código maneje correctamente los encabezados de autenticación.

Este enfoque es ideal para scripts de fondo que procesan lotes de notificaciones diarias sin necesidad de instalar SDKs adicionales de OpenAI.

  • Verifique siempre el código de estado 200 antes de guardar el archivo.
  • Ajuste el parámetro speed entre 0.25 y 4.0 para optimizar la longitud del audio.

Solicitud HTTP nativa

Una llamada curl simple permite validar la integración sin código adicional. Es útil para pruebas rápidas en entornos de staging o para verificar la disponibilidad del endpoint desde servidores proxy.

El cuerpo JSON debe incluir estrictamente los campos model, input y voice para evitar errores de formato.

  • Use https://api.vkyat.info/v1/audio/speech como endpoint.
  • Incluya Authorization: Bearer tts-... en los headers.

Manejo de audio binario

La respuesta contiene datos binarios que deben escribirse directamente en un archivo o enviarse a un sistema de notificación existente. No realice conversiones de texto intermedias.

El formato elegido (mp3, wav, opus) determina el tamaño del archivo, pero la lógica de escritura es idéntica para todos los soportes.

  • Escriba los bytes recibidos sin decodificarlos primero.
  • Use response.content en lugar de response.text para evitar corrupción.

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.

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

Más en este sitio