Documentación técnica de la API de texto a voz

Por Equipo editorial VozCulta · Actualizado 2026-11-19

Esta documentación técnica describe la API de síntesis de voz de VozCulta, diseñada para agilizar la digitalización de documentos en agencias gubernamentales y organizaciones sin fines de lucro. Aquí encontrarás la estructura exacta de los endpoints, los parámetros necesarios y ejemplos prácticos para integrar la generación de audio en tus flujos de trabajo existentes sin depender de infraestructura compleja.

La guía cubre desde la obtención de tu clave API hasta el manejo de límites de uso y formatos de audio, incluyendo la estructura de los endpoints y ejemplos prácticos. Es útil para desarrolladores que necesitan convertir textos largos a audio de forma programática, utilizando estándares compatibles con el SDK de OpenAI y soportando 23 idiomas clave para mejorar la accesibilidad en sus servicios públicos o proyectos institucionales.

Documentación técnica de la API de texto a voz

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.mp3

Python (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
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 API

Ilustración de onda de sonido para: 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

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

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

Ilustración de onda de sonido para: 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

Ilustración de onda de sonido para: 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

Ilustración de onda de sonido para: 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

Ilustración de onda de sonido para: 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
Listado de voces y modelos

Manejo de errores

Ilustración de onda de sonido para: 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

Ilustración de onda de sonido para: 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

Ilustración de onda de sonido para: 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.

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 API reference: create speech
  4. FFmpeg documentation
  5. LibriTTS-R corpus (OpenSLR 141)
  6. Python documentation
  7. IETF RFC 7845: Ogg Opus
  8. Creative Commons Attribution 4.0
  9. W3C WAI: making audio and video accessible
  10. LibriVox public-domain audiobooks
  11. curl documentation
  12. LibriTTS-R paper (arXiv 2305.18802)

Más en este sitio