Preguntas frecuentes
¿Qué es un endpoint en la API?
Un endpoint es una URL específica que tu aplicación consulta para realizar una acción. En VozLegal API, el endpoint principal es POST https://api.vty15.info/v1/audio/speech para generar audio. También existen GET /v1/voices para listar voces y GET /v1/models para ver modelos disponibles. Estos puntos finales definen cómo se estructura la comunicación con la API.
¿Cómo se obtiene la clave API?
Regístrate en la página /get-api-key/ usando Google o correo electrónico. La clave se muestra en el panel junto con el saldo y el ejemplo de curl. Cada cuenta tiene una clave activa; puedes emitir una nueva en cualquier momento, lo que invalida la anterior inmediatamente. No hay clave por defecto.
¿Se puede usar el SDK de OpenAI?
Sí. La API tiene la misma estructura de solicitud que el endpoint de speech de OpenAI. Solo necesitas cambiar el base_url a https://api.vty15.info/v1 y usar tu clave de VozLegal API. Esto permite utilizar las SDKs oficiales de OpenAI sin modificar la lógica de tu código.
¿Qué parámetros requiere la solicitud?
La solicitud POST requiere el campo model ("tts-1" o "tts-1-hd"), input (texto hasta 4096 caracteres), voice (uno de 8 presets), response_format (mp3, wav, opus, flac, pcm) y speed (0.25–4.0). El campo language es opcional; si no se envía, se detecta automáticamente o se asume inglés para texto en latín.
¿Qué es el modelo tts-1-hd?
tts-1-hd es uno de los dos modelos disponibles, junto con tts-1. Ambos utilizan el mismo motor de síntesis y tienen el mismo precio. La elección entre ambos no afecta el costo ni la calidad base, sino que permite especificar el modelo en la solicitud JSON.
¿Cuántos caracteres permite la entrada?
Cada solicitud acepta un máximo de 4096 caracteres en el campo input. Si tu texto es más largo, debes dividirlo en partes de este tamaño y unir los archivos de audio resultantes. Los espacios y la puntuación cuentan como caracteres. El límite es estricto por solicitud individual.
¿Qué formatos de audio se pueden pedir?
Puedes solicitar los formatos mp3, wav, opus, flac o pcm. Estos se especifican en el campo response_format de la solicitud JSON. La elección del formato depende de tus necesidades de almacenamiento y reproducción. Todos los formatos se generan bajo demanda y se devuelven directamente en la respuesta de la API.
¿Qué error devuelve si exceden el límite?
Sin embargo, la solicitud fallará si se envían más de 4096 caracteres. Las solicitudes fallidas son gratuitas y el cargo se devuelve en caso de error de síntesis.
¿Cuántas solicitudes se permiten por minuto?
El límite es de 60 solicitudes por minuto por clave. Antes de la primera recarga, el límite es de 10 solicitudes por minuto. Las solicitudes se procesan en cola, por lo que bajo carga pueden esperar. Si excedes el límite, las solicitudes adicionales se gestionarán según la cola disponible.
¿Se puede usar autenticación con token?
Sí. La autenticación se realiza mediante una clave API que actúa como token. Debes incluir la cabecera Authorization con el formato Bearer seguido de tu clave (tts-...). Cada cuenta tiene una clave activa que identifica tu saldo y límites de uso.
¿Qué es la cabecera Authorization?
Es una cabecera HTTP estándar que envía tu clave API para autenticar la solicitud. El formato es Authorization: Bearer tts-... donde ... es tu clave única. Esta cabecera debe incluirse en todas las solicitudes POST al endpoint de speech y GET a otros endpoints para validar tu cuenta.
¿Cómo se listan las voces disponibles?
Realiza una solicitud GET a /v1/voices. Este endpoint devuelve información sobre las 8 voces disponibles, sus idiomas, formatos soportados y precios. Las voces son: aria, nova, luna, sage, felix, milo, atlas y orion. Puedes usar este endpoint para verificar la disponibilidad antes de generar audio.
¿Hay un endpoint para ver el balance?
No hay un endpoint dedicado exclusivamente para ver el balance en la documentación de endpoints listados. El balance se muestra en la página /get-api-key/ después de iniciar sesión. Allí también puedes ver el crédito de prueba, caracteres restantes y uso. La información de facturación se mantiene para auditoría.
Primera solicitud
curl
curl https://api.vty15.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.vty15.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.vty15.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
La obtención de la clave API es el primer paso para integrar VozLegal API en el flujo de publicación de documentos legales de tu startup. El proceso se inicia accediendo a la página de registro, donde debes establecer tus credenciales de acceso para obtener el token de autorización necesario.
Registro en /get-api-key/
Accede a la ruta /get-api-key/ desde la interfaz principal del sitio. Aquí encontrarás el formulario dedicado a la creación de la cuenta de desarrollador. Este es el punto único donde se asocia tu identidad con la clave Bearer que utilizarás para todas las solicitudes subsiguientes.
Autenticación con Google o email
Puedes autenticarte utilizando tu cuenta de Google para una configuración rápida, o bien registrarte con una dirección de correo electrónico y una contraseña. Si eliges el método de correo, tu cuenta se crea sin crédito de prueba inicial; la autenticación con Google sí incluye un crédito de $0.50 válido por 7 días.
Generación de clave Bearer
Una vez completado el registro, el sistema genera una clave Bearer única (formato tts-...). Esta credencial se muestra en tu panel y debe incluirse en la cabecera Authorization de cada solicitud. Puedes emitir una nueva clave en cualquier momento; la anterior dejará de ser válida de forma inmediata.
- Formato: Bearer tts-...
- Una clave activa por cuenta
- Revocación inmediata al emitir nueva
Ejemplo de solicitud con cURL
Aquí tienes un ejemplo completo de una solicitud cURL para generar audio desde texto. Este comando envía una petición POST al endpoint correspondiente, incluyendo la autenticación y el cuerpo de la solicitud en formato JSON.
Este ejemplo ilustra el uso básico de la API para convertir un fragmento de texto legal en un archivo de audio. Asegúrate de reemplazar TU_API_KEY con tu clave real obtenida en /get-api-key/.
Método POST al endpoint /v1/audio/speech
La solicitud se dirige a https://api.vty15.info/v1/audio/speech utilizando el método POST. Este es el único endpoint necesario para la síntesis de audio.
Cuerpo JSON con parámetros requeridos
El cuerpo de la solicitud debe contener el texto a convertir y la voz deseada. Por ejemplo, para generar un aviso legal en voz de 'aria' (narradora clara), el JSON sería:
- ```json
- {
- "model": "tts-1",
- "input": "Este documento es propiedad de su startup.",
- "voice": "aria",
- "response_format": "mp3"
- }
- ```
Autenticación con cabecera Authorization
Incluye tu clave API en la cabecera Authorization como un token Bearer. Sin esta cabecera, la solicitud devolverá un error 401.
- -
Authorization: Bearer TU_API_KEY
Uso con SDK oficial de OpenAI
La API de VozLegal es compatible con los SDK oficiales de OpenAI, lo que facilita la integración en aplicaciones existentes. Solo requiere ajustar la URL base y proporcionar la clave de API generada en /get-api-key/.
Instalación del paquete
Instale la biblioteca de OpenAI utilizando su gestor de paquetes preferido. Por ejemplo, en entornos Python o Node.js, añada la dependencia oficial que permite comunicarse con endpoints compatibles con el formato de speech.
Modificación de base_url
Configure la variable de entorno o el parámetro de cliente para apuntar a https://api.vty15.info/v1. Esta modificación permite reutilizar la misma lógica de autenticación y serialización de datos que usa el cliente nativo de OpenAI.
Uso del mismo método de speech
Invoca el método de generación de audio pasando el texto, la voz seleccionada (de los 8 disponibles) y el formato deseado. El SDK maneja la serialización JSON y la cabecera Authorization con la clave Bearer de VozLegal.
Parámetros de la solicitud
La API acepta dos modelos de síntesis, tts-1 y tts-1-hd, que utilizan el mismo motor de procesamiento y tienen el mismo precio. La selección del modelo no altera la estructura de la solicitud ni el coste por carácter.
El campo input recibe el texto a sintetizar, con un límite estricto de 4096 caracteres por solicitud. Los espacios y la puntuación cuentan como caracteres. Para textos más extensos, es necesario dividir el contenido y unir los archivos resultantes.
Modelo: tts-1 o tts-1-hd
Ambos modelos generan audio mediante el mismo motor. La elección entre tts-1 o tts-1-hd es indiferente para la facturación, que se calcula a $0.01 por cada 1000 caracteres procesados, independientemente del modelo seleccionado.
Entrada: texto hasta 4096 caracteres
El campo input admite cadenas de texto de hasta 4096 caracteres. Se cuenta cada espacio, puntuación y carácter especial. Si el documento legal supera este límite, debe dividirse en partes que se sintetizarán por separado.
Voz: selección entre 8 presets
El campo voice requiere uno de los 8 presets disponibles, que incluyen tonos femeninos como aria o nova, y masculinos como atlas o milo. Cada voz puede generar audio en cualquiera de los 23 idiomas soportados.
Si no se especifica el campo language, el sistema intenta adivinarlo basándose en el script, asumiendo inglés para texto en latín. Para documentos legales en otros idiomas, se debe establecer el código ISO explícitamente.
- aria: narradora clara y cálida
- nova: tono brillante y enérgico
- luna: suave, ideal para narración
- sage: calmada, instructiva
- felix: dinámica, promocional
- milo: amigable y conversacional
- atlas: neutral, estilo noticias
- orion: profunda, documental
Formatos de respuesta soportados
La API devuelve el audio sintetizado directamente en el cuerpo de la respuesta. El formato se especifica mediante el parámetro response_format en el cuerpo JSON de la solicitud. Esto permite integrar el resultado directamente en flujos de trabajo de cumplimiento normativo sin conversiones adicionales.
MP3 para compresión estándar
El formato MP3 ofrece la compresión más eficiente para la mayoría de los casos de uso. Es ideal para la publicación de documentos legales en plataformas web y aplicaciones móviles donde el ancho de banda y el almacenamiento son críticos. Asegura una carga rápida sin sacrificar la inteligibilidad del habla.
WAV para calidad sin pérdida
El formato WAV proporciona audio sin pérdida, manteniendo la fidelidad exacta de la voz sintética. Este formato es recomendado para archivos de auditoría, donde la integridad del contenido de voz es prioritaria para la transparencia normativa. Ocupa más espacio que MP3 pero garantiza que no haya pérdida de datos.
OPUS, FLAC y PCM para casos específicos
OPUS ofrece una excelente relación calidad-tamaño. FLAC es para archivado de alta fidelidad sin compresión con pérdida. PCM es útil para procesamiento de audio posterior o integración con sistemas legacy que requieren datos crudos sin codificación adicional.
- OPUS: eficiente para streaming y baja latencia.
- FLAC: archivado de alta fidelidad.
- PCM: datos de audio sin codificar.

Manejo de errores comunes
El API devuelve códigos de estado HTTP claros para diagnosticar fallos. Los errores 401, 429 y 400 indican problemas de autenticación, límites de tasa o formato de solicitud respectivamente.
Error 401 por clave inválida
Ocurre cuando la cabecera Authorization: Bearer <key> está ausente o es incorrecta. Cada cuenta tiene una única clave activa; si se emite una nueva, la anterior deja de funcionar inmediatamente.
- Verifique que la clave no haya sido revocada.
- Compruebe el formato exacto de la cabecera.
Error 429 por límites de tasa
Se retorna al exceder 60 solicitudes por minuto con una clave activa, o 10 por minuto si la cuenta no tiene recarga. Las solicitudes se procesan en cola bajo carga.
- Implemente reintento con backoff exponencial.
- Monitoree el balance antes de despliegues masivos.
Error 400 por formato JSON incorrecto
Se produce si el cuerpo de la solicitud no cumple la estructura esperada o supera los 4096 caracteres en un solo campo input. Asegúrese de que el texto esté codificado correctamente en UTF-8.
- Valide la longitud del texto antes de enviar.
- Verifique que
modelyvoicesean válidos.
Límites de tasa y rendimiento
El sistema procesa las solicitudes de síntesis de voz en cola secuencial, lo que garantiza un orden estricto de entrega pero puede introducir latencia durante picos de tráfico. La velocidad de generación se aproxima al tiempo real en textos largos, procesando aproximadamente 25 caracteres por segundo de audio generado, mientras que las frases cortas requieren unos segundos adicionales de procesamiento inicial.
Estos límites son fijos por clave de API y no varían según el plan, ya que no existen suscripciones. Para aplicaciones legales que generan documentos extensos, se recomienda implementar lógica de partición del texto en fragmentos de 4096 caracteres y gestionar la cola de solicitudes para evitar bloqueos por exceso de concurrencia.
60 solicitudes por minuto por clave
Cada clave activa permite un máximo de 60 solicitudes por minuto una vez que la cuenta ha sido recargada. Este límite es estricto y se aplica independientemente del modelo seleccionado (tts-1 o tts-1-hd). Si se excede, las solicitudes posteriores recibirán un error 429 hasta que el periodo de 60 segundos se reinicie.
- Límite estándar: 60 req/min tras recarga.
- Aplica a todas las voces y formatos.
- La cuota se restablece cada 60 segundos.
10 solicitudes por minuto sin recarga
Las cuentas nuevas sin un depósito previo de USTR (mínimo $5) operan con un límite reducido de 10 solicitudes por minuto. Esta restricción asegura la estabilidad del servicio durante la fase de prueba. Una vez que se procesa una transferencia TRC-20, el límite se eleva automáticamente a 60 req/min.
- Límite base: 10 req/min.
- Se mantiene hasta la primera recarga.
- No requiere confirmación manual.
Procesamiento secuencial bajo carga
Bajo alta demanda, las solicitudes se encolan y se procesan una tras otra. Esto significa que el tiempo de respuesta puede aumentar significativamente si hay múltiples peticiones simultáneas. Para cumplir con normativas de accesibilidad, se recomienda pre-generar los audios de los documentos legales fuera del horario pico de uso.
- Cola de procesamiento único por instancia.
- Latencia variable según carga del servidor.
- Recomendado: generación asíncrona para documentos largos.
Endpoints adicionales disponibles
Además del endpoint principal de síntesis, la API expone rutas específicas para consultar metadatos del servicio y gestionar la cuenta sin necesidad de generar audio.
GET /v1/voices para listar voces
Devuelve el catálogo completo de voces disponibles, incluyendo idiomas soportados y formatos de audio. Permite validar la compatibilidad antes de generar solicitudes.
GET /v1/models para información técnica
Retorna la información técnica de los modelos disponibles, confirmando que tanto "tts-1" como "tts-1-hd" utilizan el mismo motor de síntesis y tienen el mismo coste por carácter.
Consultas de balance y uso
Accede a información detallada sobre tu cuenta, incluyendo saldo actual, caracteres consumidos y estado del período de prueba. Estos datos son esenciales para el control presupuestario en entornos corporativos.
La consulta es inmediata y refleja el estado actual de tu clave Bearer, facilitando la integración con sistemas de facturación interna.
Escucha las 8 voces
Cada muestra a continuación fue generada por esta API a partir de la misma frase. El proceso es directo: se envía el texto, se especifican las preferencias y se recibe el archivo de audio generado.
23 idiomas
Cualquier voz puede hablar cualquiera de estos idiomas.
Fuentes y lecturas adicionales
- Wikipedia
- MDN: Web Speech API
- TRON developer hub: TRC-20
- Creative Commons Attribution 4.0
- LibriTTS-R corpus (OpenSLR 141)
- OpenAI API reference: create speech
- ISO 639 language codes
- openai-node on GitHub
- W3C WAI: making audio and video accessible
- Python documentation
- FFmpeg documentation
- LibriTTS-R paper (arXiv 2305.18802)
