Preguntas frecuentes
¿Qué lenguajes de programación se recomiendan?
Puede usar cualquier lenguaje que soporte HTTP y JSON. Como la API sigue la forma de solicitud de OpenAI, las SDK oficiales de OpenAI funcionan cambiando el base_url a https://api.voltrush.info/v1. También es compatible con llamadas HTTP directas o herramientas como cURL.
¿Se puede usar JavaScript para la integración?
Sí, es totalmente compatible. Puede usar la SDK de OpenAI para JavaScript configurando el base_url correctamente o realizar llamadas fetch estándar. Esto permite integrar la síntesis de voz directamente en aplicaciones web o servidores Node.js sin necesidad de librerías propietarias adicionales.
¿Es difícil integrar la API en un sitio web?
La integración es directa mediante una llamada POST al endpoint /v1/audio/speech. Solo necesita enviar el texto, el modelo y la voz en formato JSON. Al recibir la respuesta, obtiene el archivo de audio listo para reproducirse o guardarse, simplificando el flujo técnico.
¿Cuánto tiempo tarda en generarse el audio?
La generación es aproximadamente en tiempo real, procesando unos 25 caracteres por segundo. Las frases cortas pueden tardar unos segundos. Bajo carga, las solicitudes pueden esperar en cola, ya que se procesan una tras otra, pero no hay streaming ni audio parcial.
¿Se puede usar la API en servidores locales?
Sí, es un servicio en la nube. Solo necesita conexión a internet para enviar texto a https://api.voltrush.info/v1. No requiere instalación de software local ni infraestructura propia. Los servidores locales pueden consumir la API mediante llamadas HTTP estándar desde cualquier entorno.
¿Qué pasa si el texto tiene caracteres especiales?
El sistema acepta texto UTF-8 estándar, incluyendo caracteres especiales y acentos en los 23 idiomas soportados. El límite es de 4096 caracteres por solicitud. Si el texto excede este límite, debe dividirlo en partes y unir los archivos de audio resultantes manualmente.
¿Se puede traducir el texto antes de generar audio?
La API no incluye traducción automática. Debe traducir el texto externamente y luego enviarlo al endpoint con el código de idioma ISO correspondiente. Esto asegura que la voz sintetice correctamente el idioma objetivo, ya que la API solo convierte texto a audio.
¿Hay un límite de concurrente solicitudes?
Las solicitudes se procesan en secuencia, una tras otra. Aunque no hay un límite estricto de concurrencia simultánea, el límite real es de 60 solicitudes por minuto por clave. Si hay mucha carga, las peticiones pueden esperar en cola antes de procesarse.
¿Cómo se maneja la caché de audio?
La API no almacena ni gestiona caché de audio generada. Los archivos se devuelven en la respuesta y no se guardan en nuestros servidores. Su aplicación debe implementar su propia lógica de caché si desea evitar regenerar audio idéntico para ahorrar costos y tiempo.
¿Se puede personalizar el tono de voz?
No se puede personalizar el tono, la emoción o la velocidad más allá del ajuste de velocidad (0.25–4.0). Se ofrecen 8 voces preestablecidas que no admiten etiquetas SSML ni ajustes finos de entonación. Cada archivo tiene una marca de agua invisible.
¿Es necesario descargar la API?
No, es una API en la nube. No requiere descargar ningún software, SDK propio ni plugin. Solo necesita enviar solicitudes HTTP a nuestro endpoint. Esto facilita la integración en cualquier entorno, desde servidores hasta aplicaciones móviles o web, sin gestión de infraestructura local.
¿Funciona con versiones antiguas de Python?
Funciona con cualquier versión de Python que soporte las librerías estándar de HTTP y JSON, o la SDK de OpenAI. No hay requisitos de versión específicos de Python, siempre que el entorno pueda realizar llamadas HTTP POST con el cuerpo JSON requerido.
¿Se puede usar en aplicaciones de Android?
Sí, puede usar la API desde aplicaciones Android mediante llamadas HTTP desde el dispositivo o desde su backend. No hay un SDK móvil específico, pero cualquier lenguaje de programación compatible con HTTP puede integrar la síntesis de voz en su aplicación nativa o híbrida.
¿Qué navegador es mejor para probar?
Cualquier navegador moderno funciona para probar la API mediante herramientas de desarrollo o extensiones. Como la respuesta es un archivo de audio, la compatibilidad depende del navegador para reproducir formatos como MP3, WAV, OPUS, FLAC o PCM. No hay diferencias de rendimiento entre navegadores.
¿Cómo se verifica la autenticidad del audio?
Cada archivo generado lleva una marca de agua inaudible que lo identifica como voz sintética. Esto permite verificar que el audio proviene de nuestra API. No se ofrece certificación de autenticidad ni sellos visibles, pero la marca de agua es consistente en todas las generaciones.
¿Se puede usar la API en tiempo real?
No ofrece streaming ni audio parcial. La API devuelve el archivo completo una vez terminada la síntesis. Para flujos en tiempo real, debe implementar su propia lógica de buffering o usar la API en modo bloque, esperando la respuesta completa antes de reproducir.
Paso 1: Registro y configuración
Para comenzar, acceda a https://voltrush.info/get-api-key/ y registre una cuenta utilizando su correo electrónico o Google. Este paso inicial es necesario para obtener las credenciales que permitirán a sus sistemas gubernamentales comunicarse con la API de VozCulta.
Creación de cuenta en el sitio
La creación de cuenta es inmediata y gratuita. Si utiliza Google, recibe un crédito de prueba de $0.50 válido por 7 días; con correo y contraseña, el saldo inicia en cero.
Obtención de la clave API
Una vez registrado, la página principal muestra su clave única (prefijo tts-...). Esta clave autenticará sus solicitudes POST al endpoint de síntesis de voz.
- Una clave activa por cuenta.
- Nueva clave invalida a la anterior instantáneamente.
Verificación del saldo disponible
Verifique su saldo y los caracteres restantes directamente en el panel de la cuenta. El coste es de $10 por millón de caracteres, incluyendo espacios y puntuación.
Paso 2: Primer ejemplo en cURL
Este paso demuestra la integración básica mediante la terminal, ideal para validar la conectividad antes de desarrollar aplicaciones complejas. El comando utiliza la estructura JSON estándar compatible con el endpoint de VozCulta.
La respuesta contiene el archivo de audio binario; no se devuelve una referencia ni se verifica el saldo en la respuesta.
Copia del comando de ejemplo
Utilice la siguiente estructura cURL, reemplazando tts-xxxxxx con su clave única y ajustando los parámetros según sus necesidades de narración.
- curl -X POST https://api.voltrush.info/v1/audio/speech \
- -H "Authorization: Bearer tts-xxxxxx" \
- -H "Content-Type: application/json" \
- -d '{"model": "tts-1", "input": "Bienvenido al servicio de voz pública", "voice": "aria", "response_format": "mp3"}'
Ejecución en la terminal
Ejecute el comando en su entorno de línea de comandos. La API procesará la solicitud secuencialmente; para textos cortos, la respuesta tarda solo unos segundos.
Verificación del archivo de audio
El resultado es un archivo de audio válido en el formato seleccionado. Confirme que el audio se reproduce correctamente y que la voz corresponde al preset elegido.
Paso 3: Uso con SDK de OpenAI
La API es compatible con los SDK oficiales de OpenAI mediante la modificación de la URL base. Esto permite aprovechar librerías familiares para las solicitudes de síntesis sin necesidad de desarrollar un cliente personalizado desde cero.
El enfoque simplifica la integración técnica para equipos que ya conocen el ecosistema de OpenAI, manteniendo la compatibilidad con la estructura de peticiones estándar de VozCulta.
Instalación del paquete
Instale la librería oficial en su entorno de desarrollo. Este paquete maneja la autenticación y la serialización de datos JSON requerida por la API.
Asegúrese de que su versión del SDK sea compatible con las llamadas HTTP REST estándar.
- pip install openai
- npm install openai
Configuración de la base URL
Defina la variable de entorno OPENAI_BASE_URL apuntando a https://api.voltrush.info/v1. Esto redirige las solicitudes a los servidores de VozCulta en lugar de los de OpenAI.
Utilice su clave API (tts-...) como valor de OPENAI_API_KEY. El SDK la incluirá automáticamente en el encabezado de autorización.
Ejecución del código Python o Node
Envíe una solicitud POST al endpoint /v1/audio/speech con el texto y el modelo tts-1. El SDK se encargará de recibir el archivo de audio binario.
Guarde la respuesta en un archivo local. Recuerde que el límite es de 4096 caracteres por solicitud y que la velocidad es aproximadamente real-time.
Paso 4: Selección de voces
Elaige las ocho voces predefinidas según el tono del documento institucional. Cada voz tiene una personalidad específica, desde narradoras claras hasta voces de documentales profundos, todas capaces de pronunciar los 23 idiomas soportados sin necesidad de configuración adicional.
Evaluación de tonos disponibles
Las voces están diseñadas para roles específicos: Aria y Luna son ideales para narración suave; Atlas y Orion para noticias y documentos formales. Todas las voces pueden pronunciar cualquier idioma de la lista, aunque la calidad depende del preset elegido.
- Aria: narradora clara y cálida
- Atlas: neutral, ideal para noticias
- Orion: profunda, para documentales
Uso de voces para narración
Utiliza Sage para instrucciones paso a paso o Felix para avisos urgentes. La consistencia de la voz en todos los formatos de audio ayuda a los usuarios a reconocer el tipo de información que están escuchando, mejorando la accesibilidad en servicios públicos.
Elección de voz masculina o femenina
El género de la voz es una decisión estética, no técnica. Tanto voces femeninas como masculinas soportan los mismos idiomas y formatos. Se recomienda audizar las muestras para asegurar que el tono se alinea con la identidad de la agencia o institución.
Paso 5: Manejo de textos largos
Los textos extensos superan el límite de 4096 caracteres por solicitud. La estrategia recomendada es dividir el documento en fragmentos manejables antes de enviarlos a la API.
Una vez recibidos los archivos de audio individuales, estos se concatenan para crear el archivo final. Este flujo asegura que la síntesis sea completa sin errores por tamaño.
División del texto en partes
Calcule la longitud del texto e infórmelo. Divida el contenido en bloques menores a 4096 caracteres. Envíe cada bloque como una solicitud independiente.
- Respete el límite estricto de caracteres por petición.
- Mantenga la coherencia del contexto al dividir oraciones.
Concatenación de archivos de audio
Reciba cada archivo de audio generado. Utilice una librería de procesamiento de audio para unir las secencias. Verifique que no haya silencios extraños entre los cortes.
- Procese las solicitudes en orden secuencial.
- Asegure la compatibilidad del formato de salida.
Gestión de caracteres máximos
Cada carácter, espacio y puntuación cuenta. Los textos largos requieren múltiples llamadas. Monitoree el uso para evitar exceder el límite de 60 solicitudes por minuto.
- Cobro por cada mil caracteres procesados.
- Las solicitudes fallidas no generan cargo.
Paso 6: Formatos de audio
La API de VozCulta permite elegir entre cinco formatos de audio: mp3, wav, opus, flac y pcm. La selección depende del equilibrio entre calidad, tamaño de archivo y compatibilidad con los sistemas de los gobiernos o entidades sin fines de lucro.
Selección de MP3 para web
El formato MP3 es ideal para la distribución general en sitios web y aplicaciones móviles debido a su amplia compatibilidad. Ofrece una buena relación calidad-tamaño, lo que facilita la carga rápida de audios narrativos en plataformas de acceso ciudadano.
Uso de WAV para calidad
WAV proporciona audio sin pérdida, manteniendo la fidelidad original de la síntesis. Este formato es adecuado para archivos de archivo o procesos de postproducción donde se requiere la máxima integridad del sonido sin compresión.
Elección de OPUS para ahorro
OPUS ofrece alta calidad a tamaños de archivo reducidos, ideal para reducir costos de almacenamiento y ancho de banda. Es la opción técnica recomendada para optimizar recursos en grandes volúmenes de texto a voz.
Paso 7: Control de velocidad
El parámetro speed permite ajustar la velocidad de síntesis entre 0.25 y 4.0, ofreciendo flexión para distintos contextos de uso. Por defecto, la API genera audio a una velocidad cercana a la natural, procesando aproximadamente 25 caracteres por segundo.
Ajuste de parámetro de velocidad
Puede modificar la velocidad en la solicitud JSON enviando el campo speed. Valores superiores a 1.0 aceleran la voz, mientras que valores inferiores la ralentizan. Esto es útil para adaptar la salida a diferentes necesidades de claridad o eficiencia de tiempo.
Velocidad normal vs. rápida
La velocidad normal es adecuada para la mayoría de los casos. Aumentar la velocidad puede reducir el tiempo de generación para textos largos, aunque puede afectar ligeramente la claridad. Para documentos técnicos o anuncios oficiales, mantener la velocidad estándar garantiza la mejor comprensión.
- Rango válido: 0.25 a 4.0.
- Velocidad estándar: aproximadamente 25 caracteres/segundo.
Velocidad lenta para accesibilidad
Reducir la velocidad a valores bajos (ej. 0.75) mejora la accesibilidad para personas con dificultades de procesamiento auditivo. Es recomendable para anuncios públicos o lecturas de documentos oficiales donde la precisión es prioritaria sobre la rapidez.

Paso 8: Manejo de errores
El manejo de errores es crucial para garantizar la continuidad de los servicios de audio en instituciones gubernamentales. Al integrar la API de VozCulta, es fundamental identificar las respuestas del servidor para distinguir entre fallos temporales y problemas definitivos en la síntesis de voz.
Identificación de códigos de error
La API devuelve códigos HTTP estándar que indican el estado de la solicitud. Un error 4xx suele señalar problemas con la clave o el formato, mientras que un 5xx indica fallos del servidor. Es importante revisar el cuerpo de la respuesta para obtener detalles específicos sobre la causa del fallo.
- Código 401: Clave API inválida o expirada.
- Código 429: Límite de velocidad excedido (60 req/min).
- Código 422: Texto demasiado largo o formato incorrecto.
- Código 500: Error interno del servidor de síntesis.
Reintento de solicitudes fallidas
Para errores transitorios como problemas de red o saturación del servidor, se recomienda implementar una lógica de reintento con backoff exponencial. Las solicitudes fallidas no consumen saldo, por lo que repetir la operación es seguro y económico hasta que se obtenga un archivo de audio válido.
- Reintentar automáticamente errores 500 y 503.
- Esperar intervalos crecientes entre reintentos.
- Limitar el número máximo de reintentos para evitar bucles infinitos.
Logueo de eventos
Mantener un registro detallado de las solicitudes, incluyendo el texto enviado, la voz utilizada y el estado de la respuesta, facilita la resolución de incidencias. Este historial permite auditar el uso y detectar patrones de error específicos en la generación de audio para los ciudadanos.
- Registrar timestamp, ID de solicitud y código de estado.
- Guardar el hash del texto procesado para depuración.
- Notificar al equipo técnico en caso de errores recurrentes.
Paso 9: Pruebas de calidad
La validación técnica asegura que la síntesis cumple los estándares de inteligibilidad antes de integrarse en sistemas gubernamentales. Utilice la terminal o el SDK para generar audio con textos representativos de los servicios públicos y audicione los resultados para verificar la claridad de la voz.
Este paso complementa la configuración técnica verificando la calidad perceptual. Es fundamental para garantizar que los ciudadanos, especialmente aquellos con discapacidades visuales, puedan comprender la información sin ambigüedades en los documentos digitalizados.
Audición de muestras generadas
Genere audio con textos reales de las notificaciones o informes que utilizará la institución. Escuche atentamente la fluidez y la entonación natural de las voces seleccionadas, como Luna para narración o Atlas para noticias.
Verifique que no haya cortes abruptos ni artefactos de audio inusuales. Si el texto supera los 4096 caracteres, confirme que la concatenación de las partes suena continua y coherente.
- Audice archivos en formato MP3 y WAV para comparar la calidad.
- Verifique la claridad en frases con números y fechas comunes en trámites.
Verificación de acentos
Aunque las voces pueden hablar cualquier idioma de la lista, confirme que la pronunciación es correcta para el idioma objetivo. Si el texto está en español pero la detección automática falla, especifique el campo language en la solicitud.
Pruebe textos con caracteres especiales o nombres propios frecuentes en la administración pública para asegurar que la voz los pronuncia correctamente.
- Confirme la precisión fonética en textos con nombres propios.
- Verifique que no haya interferencias de acentos no deseados.
Test de comprensión auditiva
Realice pruebas de comprensión con usuarios finales o personal de la institución. Lea textos de instrucciones de servicios y mida si son fácilmente comprensibles sin apoyo visual.
Este proceso ayuda a ajustar la velocidad del habla. Si la comprensión es baja, reduzca la velocidad a valores cercanos a 1.0 o inferiores para mejorar la claridad.
- Mida la comprensión con grupos representativos de usuarios.
- Ajuste la velocidad según los resultados de comprensión auditiva.
Paso 10: Despliegue en producción
Al pasar la API a producción, es esencial monitorear el uso en tiempo real desde el panel de cuentas para anticipar necesidades de escala sin interrupciones en los servicios de audio para ciudadanos.
La gestión proactiva de los límites técnicos y la seguridad de la clave garantizan que la generación de voz continúe de forma estable durante picos de demanda institucionales.
Monitorización de uso
Acceda al panel de su cuenta para visualizar el consumo de caracteres y el estado del saldo. Esto permite ajustar la planificación de proyectos de digitalización basándose en datos reales de generación.
Gestión de límites de velocidad
La API permite 60 solicitudes por minuto por clave (10 por minuto antes del primer recargo). Monitoree esta métrica para evitar colas de procesamiento que retrasen la entrega de audio en aplicaciones en tiempo real.
- Respetar el límite de 60 req/min asegura una latencia predecible.
- Las solicitudes en cola se procesan secuencialmente.
Actualización de claves
Gereencie la seguridad emitiendo una nueva clave API desde el panel cuando sea necesario. La clave antigua deja de funcionar inmediatamente, asegurando que solo las aplicaciones actualizadas mantengan el acceso.
Paso 11: Optimización de costos
Optimizar el gasto requiere comprender la estructura de precios: $10 por cada millón de caracteres, lo que equivale a $0.01 por cada 1.000 caracteres, incluyendo espacios y puntuación. Esta métrica permite calcular con precisión el costo de cada informe o documento antes de su generación.
Carga de saldo en USDT
El único método de recarga es mediante USDT en la red TRON (TRC-20). El monto mínimo es de $5 y el crédito se acredita automáticamente en minutos. No hay suscripciones ni cargos por transacción adicionales, garantizando que cada centavo entre en su cuenta de facturación.
Monitoreo de caracteres gastados
El panel de control muestra el balance actual y los caracteres consumidos. Las solicitudes fallidas son gratuitas, lo que significa que solo se paga por el audio generado con éxito. Esto permite auditar el gasto real sin sorpresas en la facturación.
Planificación de uso
Dado que el saldo no expira, las organizaciones pueden acumular crédito para proyectos a largo plazo. Al generar textos largos, recuerde que el costo se calcula por carácter, por lo que optimizar el texto fuente reduce directamente el gasto sin afectar la calidad del audio.
Paso 12: Soporte y mantenimiento
El soporte técnico se gestiona exclusivamente por correo electrónico, ya que no ofrecemos línea telefónica ni chat en vivo. Esta vía permite documentar cada consulta y mantener un registro claro para auditorías gubernamentales.
Contacto por correo electrónico
Envía tus incidencias o preguntas a la dirección de soporte indicada en la sección de contacto. Los tiempos de respuesta varían según la carga, pero todos los mensajes son revisados por ingenieros.
Actualización de documentación
La documentación en /docs/ se mantiene sincronizada con los cambios de la API. Si detectas alguna discrepancia entre el código de ejemplo y el comportamiento actual, repórtalo para su corrección.
Resolución de dudas técnicas
Para problemas de integración, incluye en tu correo los datos de la solicitud, el código de error y el formato utilizado. Esto acelera la identificación del problema sin necesidad de llamadas.
- No hay garantía de tiempo de respuesta (SLA).
- Solo se soporta asistencia vía email.
Escucha las 8 voces
Cada muestra a continuación fue generada por esta API a partir de la misma frase. El panel de control muestra el balance actual y los caracteres consumidos.
23 idiomas
Cualquier voz puede hablar cualquiera de estos idiomas.
