Preguntas frecuentes
¿Qué es el endpoint /v1/audio/speech?
Es el punto final principal para enviar texto y recibir un archivo de audio. Utiliza el método POST con un cuerpo JSON que incluye el modelo, el texto de entrada, la voz, el formato de respuesta y la velocidad. Es compatible con la estructura de la API de OpenAI.
¿Puedo usar la biblioteca de OpenAI?
Sí, las bibliotecas oficiales de OpenAI funcionan modificando la base_url a https://api.voltrush.info/v1 y utilizando su clave API. Esto permite reutilizar el código existente sin necesidad de aprender una nueva sintaxis.
¿Cuál es el tamaño máximo del texto?
El límite es de 4096 caracteres por solicitud. Si su documento supera esta longitud, debe dividirlo en partes y unir los archivos de audio resultantes. Los espacios y la puntuación cuentan como caracteres dentro de este límite máximo permitido.
¿Qué formato de audio es el más pequeño?
Entre las opciones disponibles (mp3, wav, opus, flac, pcm), el formato opus generalmente ofrece la mejor compresión para un tamaño de archivo reducido. La elección depende del equilibrio entre calidad y ancho de banda necesario para su aplicación de digitalización.
¿Cómo cambio la velocidad de la voz?
Ajuste el campo 'speed' en el cuerpo de la solicitud, aceptando valores entre 0.25 y 4.0. Un valor mayor acelera la reproducción, mientras que uno menor la ralentiza. Esto permite adaptar la velocidad de lectura a las necesidades de accesibilidad de los usuarios.
¿Qué hace el campo 'language'?
Este campo opcional especifica el código ISO del idioma para mejorar la precisión de la síntesis. Si no se establece, el sistema intenta adivinar el idioma basado en el script, asumiendo inglés para texto en latín. Se recomienda definirlo explícitamente para textos no ingleses.
¿Es necesario usar SSL para las solicitudes?
Sí, todas las solicitudes deben enviarse a través de HTTPS a https://api.voltrush.info/v1. Esto asegura que la clave API y los datos del texto se transmitan de forma segura, protegiendo la información sensible de sus documentos gubernamentales o de la organización.
¿Qué código de error indica un problema de saldo?
La documentación estándar indica códigos HTTP para errores de autenticación o límites. Si la síntesis falla, el cargo se devuelve íntegramente. Para problemas de saldo, verifique su balance en la página de cuenta, ya que no se realizan cargos por solicitudes fallidas.
¿Cuántas voces hay disponibles en total?
Hay 8 voces preestablecidas disponibles: Aria, Nova, Luna, Sage, Felix, Milo, Atlas y Orion. Estas cubren tonos femeninos y masculinos, optimizadas para narración, instrucciones o documentales, permitiendo elegir el tono más adecuado para la voz de sus servicios públicos.
¿Se puede especificar el idioma en el cuerpo?
Sí, el campo 'language' se incluye en el cuerpo JSON de la solicitud. Debe proporcionar el código ISO del idioma deseado. Esto es crucial para textos en latín que no sean inglés, asegurando que la voz pronuncie correctamente los términos específicos.
¿Qué pasa si excedo el límite de velocidad?
El límite es de 60 solicitudes por minuto por clave API. Si excede este límite, las solicitudes adicionales pueden ser rechazadas o procesadas con retraso. Mantenga una tasa constante para evitar interrupciones en la generación de audio para sus documentos largos.
¿La API devuelve el audio en base64?
La API devuelve el archivo de audio directamente en la respuesta. No se menciona un formato base64 específico en la estructura de la respuesta estándar. El cliente recibe el archivo binario correspondiente al formato solicitado (mp3, wav, etc.) en el cuerpo de la respuesta.
¿Cómo se detecta el idioma automáticamente?
Si no especifica el campo 'language', el sistema infiere el idioma basado en el script del texto. Para textos en latín, asume inglés por defecto. Para otros idiomas como español, francés o alemán, debe establecer explícitamente el campo 'language' para garantizar la precisión.
¿Hay un límite de caracteres por archivo generado?
Sí, cada solicitud genera un archivo de audio con un máximo de 4096 caracteres de entrada. Para textos más largos, debe dividir el contenido en partes, generar los archivos individualmente y unirlos posteriormente. Esto asegura que cada solicitud se procese dentro de los límites técnicos.
Primera solicitud
curl
curl https://api.voltrush.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.mp3Python (openai)
from openai import OpenAI
client = OpenAI(base_url="https://api.voltrush.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.voltrush.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 | |
|---|---|
aria | femenino |
nova | femenino |
luna | femenino |
sage | femenino |
felix | masculino |
milo | masculino |
atlas | masculino |
orion | masculino |
| language | |
|---|---|
ar | العربية |
zh | 中文 |
da | Dansk |
nl | Nederlands |
en | English |
fi | Suomi |
fr | Français |
de | Deutsch |
el | Ελληνικά |
he | עברית |
hi | हिन्दी |
it | Italiano |
ja | 日本語 |
ko | 한국어 |
ms | Bahasa Melayu |
no | Norsk |
pl | Polski |
pt | Português |
ru | Русский |
es | Español |
sw | Kiswahili |
sv | Svenska |
tr | Türkçe |
Obtención de la clave API
Para comenzar a utilizar la API de VozCulta, es necesario obtener una clave de autenticación. Esta clave es el único requisito para enviar solicitudes de síntesis de voz a nuestros servidores.
Accede a la página de registro, elige entre inicio con Google o correo electrónico, y completa el proceso para generar tu credencial única.
Registro en la página web
Navega a /get-api-key/ y selecciona tu método de registro preferido. Si usas Google, recibirás $0.50 de crédito de prueba válido por 7 días. Con email y contraseña, la cuenta se crea sin crédito inicial.
Una vez registrado, tu cuenta estará lista para emitir la primera clave API inmediatamente.
Ubicación de la clave en el panel
En tu panel de control encontrarás tu clave activa, identificada con el prefijo tts-.... Esta credencial se debe incluir en el encabezado Authorization: Bearer de cada solicitud.
El panel también muestra tu saldo actual y el consumo histórico para que mantengas el control de tu inversión.
Regeneración de la clave
Puedes emitir una nueva clave en cualquier momento desde la configuración de tu cuenta. La clave anterior dejará de funcionar inmediatamente, garantizando que solo tengas una activa.
Este proceso es útil si sospechas que tu clave ha sido expuesta o si deseas rotarla por seguridad.
Endpoint principal de síntesis
El endpoint principal permite convertir texto en audio sintetizado mediante una solicitud HTTP. Este servicio es fundamental para la digitalización de documentos gubernamentales y materiales de acceso para organizaciones sin fines de lucro, permitiendo la generación programática de archivos de voz a partir de texto plano.
Método POST /v1/audio/speech
Utilice el método POST para enviar la solicitud de síntesis. La dirección base es https://api.voltrush.info/v1. Este endpoint procesa el texto y devuelve el archivo de audio generado directamente en la respuesta.
Estructura del cuerpo JSON
El cuerpo de la solicitud debe ser un objeto JSON que contenga los parámetros necesarios para la configuración del audio. Asegúrese de que el texto no exceda los 4096 caracteres por solicitud.
Parámetros requeridos y opcionales
Los campos obligatorios son model ("tts-1" o "tts-1-hd"), input (texto a sintetizar) y voice (uno de los 8 presets disponibles). El campo response_format permite elegir entre mp3, wav, opus, flac o pcm. El parámetro speed acepta valores entre 0.25 y 4.0. Opcionalmente, puede especificar language con un código ISO si desea forzar un idioma específico, ya que de lo contrario se intenta adivinar basado en el script.
- model: "tts-1" o "tts-1-hd"
- input: texto hasta 4096 caracteres
- voice: nombre del preset de voz
- response_format: mp3, wav, opus, flac, pcm
- speed: rango 0.25 a 4.0
- language: código ISO (opcional)
Ejemplo con cURL
La forma más directa de probar la API es mediante un comando cURL que envía el texto y recibe el archivo de audio. Este ejemplo genera un archivo MP3 utilizando la voz "nova" con la velocidad predeterminada.
Asegúrate de reemplazar <TU_API_KEY> con tu clave real y ajustar el texto de entrada según tus necesidades de digitalización documental.
Comando básico de ejemplo
Ejecuta este comando en tu terminal para sintetizar un texto corto. El modelo "tts-1" ofrece una buena relación calidad-tiempo para la mayoría de los casos de uso gubernamental o institucional.
Uso de la variable de entorno
Para scripts automatizados, almacena tu clave en una variable de entorno como TTS_API_KEY. Esto evita exponer la credencial en el historial de comandos o en el código fuente.
- export TTS_API_KEY='tts-tu_clave_aqui'
- curl -X POST https://api.voltrush.info/v1/audio/speech \ -H "Authorization: Bearer $TTS_API_KEY" \ -H "Content-Type: application/json" \ -d '{"model": "tts-1", "input": "Texto de prueba", "voice": "nova"}'
Descarga del archivo de audio
Redirige la salida a un archivo local para su almacenamiento o procesamiento posterior. El archivo resultante contiene el audio sintetizado listo para ser insertado en flujos de trabajo de accesibilidad.
- curl -o output.mp3 -X POST https://api.voltrush.info/v1/audio/speech \ -H "Authorization: Bearer $TTS_API_KEY" \ -H "Content-Type: application/json" \ -d '{"model": "tts-1", "input": "Documento digitalizado", "voice": "nova"}'
Integración con SDK de OpenAI
La API de VozCulta mantiene la misma estructura de peticiones que el endpoint de síntesis de voz de OpenAI, lo que permite reutilizar las librerías oficiales cambiando la base_url. Solo es necesario ajustar la configuración básica de conexión para apuntar a la infraestructura de VozCulta.
Cambio de base_url
Para conectar el SDK de OpenAI (en Python, JavaScript, etc.), debe reemplazar la URL base predeterminada por la dirección de la API de VozCulta: https://api.voltrush.info/v1. Esta es la única modificación estructural necesaria para que las librerías reconozcan los endpoints de síntesis.
- Base URL: https://api.voltrush.info/v1
Uso de librerías oficiales
Una vez configurada la URL base, puede utilizar las versiones más recientes de las librerías oficiales de OpenAI. El objeto de cliente debe incluir su clave API (tts-...) en la cabecera de autorización, permitiendo enviar textos y recibir archivos de audio directamente en su entorno de desarrollo habitual.
Compatibilidad de métodos
Los métodos estándar de la API, como POST /v1/audio/speech, funcionan de forma idéntica a la implementación de referencia. Esto garantiza que los cuerpos JSON con campos como model, voice e input se procesen correctamente, manteniendo la compatibilidad con flujos de trabajo existentes.
Listado de voces y modelos
La API expone metadatos estructurados para integrar dinámicamente las opciones de síntesis en sus aplicaciones gubernamentales o sin fines de lucro. Estos endpoints permiten listar las voces disponibles, los modelos de motor y los formatos de audio compatibles sin necesidad de codificación hard-coded.
Acceder a esta información asegura que su integración maneje correctamente las limitaciones de caracteres y seleccione el formato óptimo para la distribución de documentos digitalizados.
Endpoint GET /v1/voices
Devuelve un listado de las 8 voces predefinidas, incluyendo sus identificadores y atributos como tono y género. Cada voz soporta los 23 idiomas listados en la documentación.
- GET https://api.voltrush.info/v1/voices
- Responde con un array de objetos voz
Endpoint GET /v1/models
Retorna los identificadores de los modelos disponibles, actualmente 'tts-1' y 'tts-1-hd', ambos con el mismo motor y precio. Este endpoint facilita la selección técnica según la necesidad de calidad o velocidad de procesamiento.
- GET https://api.voltrush.info/v1/models
Formatos soportados
Los formatos válidos para la respuesta son mp3, wav, opus, flac y pcm. MP3 es ideal para web, WAV para alta calidad y OPUS/FLAC para eficiencia de almacenamiento en archivos de audio largos.
- mp3, wav, opus, flac, pcm

Manejo de errores
La API devuelve códigos de estado HTTP estándar para indicar el éxito o el fracaso de la síntesis. Un código 200 confirma que el audio se generó correctamente. Los errores 4xx indican problemas con la solicitud, como una clave inválida o texto demasiado largo.
Códigos de estado HTTP
Utiliza los códigos estándar HTTP para gestionar el flujo. 200 OK significa que la solicitud fue procesada y el audio está disponible. 400 Bad Request indica parámetros incorrectos, como un formato no soportado. 401 Unauthorized ocurre si la clave API es errónea. 429 Too Many Requests señala que has excedido el límite de 60 solicitudes por minuto.
- 200: Éxito, audio generado.
- 400: Error de parámetros.
- 401: Clave inválida.
- 429: Límite de velocidad excedido.
Mensajes de error comunes
Los mensajes de error describen el problema específico, como "text too long" si el texto supera los 4096 caracteres. También puedes recibir "voice not found" si se especifica una voz inexistente. Estos mensajes ayudan a corregir la solicitud antes de reintentar.
- text too long: supera 4096 caracteres.
- voice not found: voz inválida.
- invalid request: formato JSON incorrecto.
Reintento de solicitudes fallidas
Las solicitudes fallidas no se cobran, por lo que puedes reintentarlas sin costo. Si ocurre un error 5xx, espera unos segundos antes de reintentar para evitar la cola de procesamiento. Para errores 429, reduce la tasa de solicitudes o implementa un backoff exponencial.
- Reintenta errores 5xx con pausa.
- Errores 4xx corrige los parámetros.
- No se cobra en fallos.
Límites de uso
La API de VozCulta opera con límites de tasa diseñados para garantizar la estabilidad del servicio durante la generación de audio. Cada clave API activa permite un máximo de 60 solicitudes por minuto, lo que facilita la integración programática en flujos de trabajo de digitalización de documentos sin necesidad de infraestructura compleja.
Límite de 60 solicitudes por minuto
Una vez que su cuenta ha realizado la primera recarga de saldo, puede realizar hasta 60 solicitudes por minuto. Este límite se aplica por clave API y es suficiente para la mayoría de las necesidades de conversión de texto a voz en servicios gubernamentales y organizaciones sin fines de lucro.
Límite de 10 solicitudes antes de carga
El límite es de 10 solicitudes por minuto antes de la primera recarga. Esto se aplica desde la creación de la cuenta, independientemente de si se está utilizando el crédito de prueba o un saldo cargado. Este umbral permite verificar la integración inicial sin saturar los servidores.
Manejo de la cola de procesamiento
Las solicitudes se procesan en orden secuencial. Si se excede la capacidad de generación en tiempo real, las solicitudes adicionales pueden entrar en una cola de espera. Para textos largos, es recomendable dividir el contenido en fragmentos de hasta 4096 caracteres y unir los archivos de audio resultantes para optimizar el flujo de trabajo.
Formatos de audio
La API permite seleccionar el formato de salida mediante el parámetro response_format en cada solicitud. Este formato determina cómo se codifica el audio generado y afecta directamente el tamaño del archivo y su compatibilidad con reproductores o sistemas de gestión de contenido.
La elección debe basarse en el balance entre calidad de audio y eficiencia de almacenamiento. Todos los formatos entregan la misma síntesis de voz, variando solo en la compresión y el uso de ancho de banda durante la descarga.
MP3 para web
El formato MP3 es la opción más compatible con navegadores. Es ideal para aplicaciones web donde la velocidad de carga es prioritaria y se requiere una compresión eficiente sin pérdida significativa de inteligibilidad.
Adecuado para la mayoría de los casos de uso en servicios gubernamentales y ONGs que distribuyen audio en sitios web o aplicaciones móviles básicas.
- Amplia compatibilidad con reproductores HTML5
- Tamaño de archivo reducido
- Ideal para difusión masiva
WAV para alta calidad
WAV ofrece audio sin compresión. Es el formato recomendado cuando se requiere la máxima calidad de audio para archivos archivados o procesamiento posterior en estudios de grabación.
El tamaño del archivo es considerablemente mayor que MP3, lo que debe considerarse al almacenar grandes volúmenes de documentos digitalizados.
- Calidad sin pérdida
- Ideal para archivado permanente
- Mayor consumo de almacenamiento
OPUS y FLAC para eficiencia
OPUS proporciona una compresión eficiente con buena calidad, siendo una alternativa ligera a MP3 para entornos con ancho de banda limitado. FLAC ofrece compresión sin pérdida.
Estos formatos son útiles para descargas masivas o cuando se desea optimizar el uso de recursos de servidor sin sacrificar la claridad del audio.
- OPUS: excelente relación calidad-tamaño
- FLAC: calidad sin pérdida, menor que WAV
- Optimización de ancho de banda
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.
Fuentes y lecturas adicionales
- Wikipedia
- TRON developer hub: TRC-20
- OpenAI API reference: create speech
- FFmpeg documentation
- LibriTTS-R corpus (OpenSLR 141)
- Python documentation
- IETF RFC 7845: Ogg Opus
- Creative Commons Attribution 4.0
- W3C WAI: making audio and video accessible
- LibriVox public-domain audiobooks
- curl documentation
- LibriTTS-R paper (arXiv 2305.18802)
