Preguntas frecuentes
¿Cómo se obtiene la clave API?
Regístrate en /get-api-key/ con Google o correo electrónico. La página muestra tu clave única y un ejemplo cURL listo. Cada cuenta tiene una clave activa; si emites una nueva, la anterior deja de funcionar inmediatamente. No se requiere suscripción ni tarjeta de crédito para comenzar.
¿Qué modelo elegir para producción?
Elige entre 'tts-1' o 'tts-1-hd'. Ambos utilizan el mismo motor de síntesis y tienen el mismo precio. La diferencia es solo el nombre del modelo, ya que usan el mismo motor y precio. Para conjuntos de datos de ML, cualquiera es suficiente.
¿Cuál es el límite de caracteres por request?
El campo 'input' acepta hasta 4096 caracteres por solicitud. Si tu texto excede este límite, debes dividirlo en partes más pequeñas y unir los archivos de audio resultantes. Los espacios y la puntuación cuentan como caracteres. Esta limitación es estricta para cada llamada a la API.
¿Se puede ajustar la velocidad de voz?
Sí, el parámetro 'speed' permite valores entre 0.25 y 4.0. Esto es útil para normalizar la duración de los audios en tus datasets. Ajustar la velocidad no cambia la calidad del motor, solo la tasa de reproducción. Es una operación programática directa en la solicitud JSON.
¿Qué formato usar para ML?
Para ingeniería de datos, 'pcm' o 'flac' son ideales por ser sin pérdida y fáciles de procesar. 'wav' también es válido. Usa 'pcm' para manipulación directa sin decodificación. Todos los formatos están disponibles mediante el parámetro 'response_format' en la API.
¿Cuántas solicitudes se permiten por minuto?
El límite es de 60 solicitudes por minuto por clave API. Antes de la primera recarga, este límite es de 10 por minuto. Las solicitudes se procesan en cola, por lo que bajo carga pueden tardar más. Monitorea el uso en tu panel de cuenta para evitar errores 429.
¿Qué pasa si excedo el límite?
Las solicitudes adicionales recibirán un error de límite de tasa. No se te cobrará por estas solicitudes fallidas. Si excedes el límite, espera a que el contador se reinicie. Las solicitudes fallidas por error del servidor también son gratuitas.
¿Se pueden enviar textos largos?
Sí, pero debes dividir el texto en fragmentos de máximo 4096 caracteres. Envía cada fragmento como una solicitud independiente y une los archivos de audio resultantes en tu pipeline. La generación es aproximadamente en tiempo real, así que textos muy largos tomarán tiempo proporcional a su duración.
¿Cómo se especifica el idioma?
Usa el parámetro opcional 'language' con un código ISO. Si no se especifica, el sistema intenta adivinarlo desde el script, asumiendo inglés para texto latino. Para idiomas como alemán o francés, establece explícitamente el código para evitar errores de pronunciación. Solo los 23 idiomas listados son compatibles.
¿La respuesta es binaria o base64?
La API devuelve el archivo de audio directamente en el cuerpo de la respuesta como datos binarios. No se usa codificación base64 por defecto. Puedes guardar el stream de respuesta directamente en un archivo en tu servidor o sistema de archivos. El encabezado 'Content-Type' indica el formato del audio.
¿Hay SDK oficial propio?
No. Utiliza el SDK oficial de OpenAI cambiando el 'base_url' a https://api.vs777.info/v1. También puedes usar HTTP simple. No ofrecemos un SDK nativo propio, ni móvil, ni para WordPress. La integración es estándar mediante llamadas HTTP POST con el cuerpo JSON especificado.
¿Se soporta SSML?
No. La API no soporta marcadores SSML ni diccionarios de pronunciación personalizados. Envía texto plano. Si necesitas control fino sobre la entonación, debes ajustar la velocidad o elegir la voz adecuada. No hay etiquetas para pausas o énfasis dentro del texto enviado al endpoint de síntesis.
¿Qué errores comunes existen?
Los errores comunes incluyen exceder los 4096 caracteres, usar un modelo o voz inválida, o superar el límite de 60 rpm. Asegúrate de que la clave API esté en el encabezado 'Authorization'. Los errores de sintaxis JSON también son frecuentes. Revisa la documentación para los códigos de estado HTTP específicos.
¿Cómo se revoca la clave?
Emite una nueva clave desde tu panel de cuenta. La clave anterior deja de funcionar inmediatamente al generar la nueva. No hay un botón de 'revocar' independiente; la emisión de una nueva actúa como revocación automática. Puedes emitir nuevas claves tantas veces como necesites sin costo adicional.
Primera solicitud
curl
curl https://api.vs777.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.vs777.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.vs777.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 |
Autenticación y clave API
La autenticación se realiza mediante un token Bearer enviado en el encabezado Authorization. Cada cuenta mantiene una única clave activa que se gestiona directamente desde el panel de control de la API.
Uso del token Bearer
Incluye Authorization: Bearer <tu-clave> en cada solicitud HTTP. La clave se emite al registrarte y debe enviarse en cada petición para verificar la cuenta y deducir el saldo.
Gestión de claves únicas
Solo existe una clave activa por cuenta. Si la revocas, la anterior deja de funcionar inmediatamente. Puedes generar una nueva en cualquier momento desde la configuración de la cuenta.
Revocación instantánea
La revocación es inmediata. Al generar una nueva clave, la anterior se invalida al instante, asegurando que solo el nuevo token sea válido para las solicitudes entrantes.
Endpoint principal de síntesis
El endpoint principal /v1/audio/speech acepta una solicitud POST con un cuerpo JSON para convertir texto en audio. La estructura es idéntica a la API de OpenAI, lo que permite reutilizar clientes existentes cambiando solo la base_url a https://api.vs777.info/v1.
Este es el punto de entrada único para la síntesis. Envía el texto, el modelo y la voz deseados, y la API procesa la solicitud para devolver el archivo de audio generado.
Método POST y JSON
Envía una solicitud POST a https://api.vs777.info/v1/audio/speech. El cuerpo debe ser un objeto JSON válido que contenga los parámetros de síntesis. No se requiere streaming ni conexión WebSocket; es una petición simple de enviar y recibir.
Campos requeridos y opcionales
El campo input es obligatorio y limita el texto a 4096 caracteres por solicitud. model debe ser tts-1 o tts-1-hd. voice selecciona uno de los 8 presets disponibles. response_format determina el tipo de archivo (mp3, wav, opus, flac, pcm). speed ajusta la velocidad entre 0.25 y 4.0. language es opcional; si no se especifica, el sistema intenta adivinarlo, pero se recomienda establecerlo explícitamente para textos en latinos fuera del inglés.
- input: texto a sintetizar (máx. 4096 caracteres)
- model: "tts-1" o "tts-1-hd"
- voice: ID de la voz (ej. "aria", "nova")
- response_format: mp3, wav, opus, flac o pcm
- speed: 0.25 a 4.0
- language: código ISO (opcional)
Formato de respuesta
La respuesta contiene el archivo de audio binario directamente en el cuerpo. No hay metadatos JSON adicionales en la respuesta de éxito. Si la síntesis falla, no se cobra el crédito.
Modelos y voces disponibles
La API ofrece dos identificadores de modelo, tts-1 y tts-1-hd, que utilizan el mismo motor de síntesis y tienen el mismo precio por carácter. La distinción es puramente semántica para compatibilidad con SDKs, ya que utilizan el mismo motor y precio.
8 presets de voz
Cada voz está basada en grabaciones con licencia de LibriTTS-R (CC BY 4.0) y lecturas de dominio público. Todas las voces pueden hablar los 23 idiomas soportados; el idioma se detecta por el script o se fuerza con el campo language.
Las voces incluyen opciones femeninas como Aria (narradora) o Nova (alegre), y masculinas como Felix (energética) o Atlas (neutral). Cada archivo generado contiene una marca de agua inaudible que lo identifica como voz sintética.
- Aria: narradora cálida y clara
- Nova: tono brillante y animado
- Luna: suave, ideal para historias
- Sage: calmada, instruccional
- Felix: enérgica, promocional
- Milo: conversacional y amigable
- Atlas: neutral, estilo noticiero
- Orion: profunda, documental
Selección por ID
Para generar audio, debes especificar el voice en la carga útil JSON de la solicitud POST. Los valores válidos son nombres en minúsculas: aria, nova, luna, sage, felix, milo, atlas u orion.
tts-1 y tts-1-hd
Ambos modelos devuelven el mismo audio. Usa tts-1 o tts-1-hd indistintamente según prefieras la convención de nomenclatura de tu biblioteca cliente, sin afectar el costo ni la latencia.
Parámetros de entrada
La API acepta texto plano como cuerpo principal de la solicitud. El campo input admite hasta 4096 caracteres por llamada; textos más largos deben dividirse previamente en fragmentos de este tamaño y concatenarse posteriormente.
Para optimizar el uso de caracteres en conjuntos de datos masivos, considera que los espacios y la puntuación cuentan como caracteres individuales. Esto afecta directamente el costo de $0.01 por cada 1.000 caracteres consumidos.
Input de texto (4096 chars)
Envía el texto a sintetizar en el campo input. La API procesa hasta 4096 caracteres por solicitud individual. Si tu texto excede este límite, debes segmentarlo manualmente antes de enviar las solicitudes y unir los archivos de audio resultantes.
El procesamiento es secuencial bajo carga, por lo que solicitudes consecutivas pueden esperar en cola. Para flujos de trabajo de ML, pre-procesa y batchea tus requests para minimizar la latencia percibida.
- Límite máximo: 4096 caracteres por request.
- Espacios y puntuación cuentan como caracteres.
- Texto plano, sin formato SSML.
Velocidad (0.25–4.0)
Ajusta la velocidad de habla mediante el campo speed, con un rango válido de 0.25 a 4.0. El valor predeterminado es 1.0. Valores superiores a 1.0 aceleran la síntesis, mientras que valores inferiores la ralentizan.
Esto es útil para adaptar la salida a diferentes usos, como resúmenes rápidos o pruebas de pronunciamiento.
- Rango mínimo: 0.25x.
- Rango máximo: 4.0x.
- Aplica a todos los modelos y voces.
Idioma opcional
El campo language es opcional pero recomendado para textos en latín que no sean inglés. Si no se especifica, el sistema adivina el idioma basándose en el script, asumiendo inglés para texto en caracteres latinos por defecto.
Para textos en danés, holandés o sueco (todos en latín), establece explícitamente el código ISO del idioma para evitar la síntesis en inglés.
- Soporta 23 idiomas específicos.
- Adivina inglés si no se especifica.
- Usa códigos ISO 639-1.
Formatos de audio de salida
La API devuelve audio en cinco formatos: MP3, WAV, OPUS, FLAC y PCM. Cada uno optimiza la relación entre tamaño de archivo y fidelidad, permitiendo elegir según el consumo de almacenamiento y la latencia de decodificación del cliente.
MP3, WAV, OPUS, FLAC, PCM
WAV y FLAC ofrecen calidad sin pérdida, ideales para validación o archives maestros. MP3 y OPUS proporcionan compresión con pérdida, reduciendo significativamente el tamaño. PCM entrega datos de audio sin comprimir, útil para procesamiento inmediato.
- MP3: Alta compresión, bajo uso de ancho de banda.
- WAV: Sin pérdida, compatible universalmente.
- OPUS: Formato eficiente con compresión.
- FLAC: Sin pérdida, compresión eficiente.
- PCM: Datos crudos sin compresión.
Compresión vs calidad
La compresión reduce el tamaño del archivo pero puede introducir artefactos auditivos. FLAC mantiene la calidad original con menos espacio que WAV. MP3 y OPUS sacrifican detalles de alta frecuencia para lograr ratios de compresión superiores.
Elección según uso
Para conjuntos de datos de ML, MP3 o OPUS suelen ser suficientes por su eficiencia. Si necesitas análisis espectral preciso, elige WAV o FLAC. Usa PCM si tu pipeline consume audio crudo sin necesidad de decodificación.

Límites y rendimiento
La API de VozLumina está diseñada para procesar solicitudes de forma secuencial, lo que implica que las peticiones se encolan automáticamente bajo carga. Aunque el límite de tasa es de 60 solicitudes por minuto por clave, la velocidad de generación varía según la longitud del texto y la cola activa.
60 solicitudes por minuto
Cada clave API tiene un límite de 60 solicitudes por minuto. Las cuentas nuevas comienzan con 10 solicitudes por minuto hasta la primera recarga. Si excedes este límite, las solicitudes adicionales se encolan hasta que haya capacidad disponible.
Cola de procesamiento
Las solicitudes se procesan en orden de llegada. Bajo alta demanda, una solicitud puede esperar en cola antes de comenzar la síntesis. Esto asegura la integridad del procesamiento secuencial sin pérdida de datos, pero introduce latencia variable.
Velocidad real aproximada
La generación tarda aproximadamente 25 caracteres de texto por segundo de audio generado en textos largos. Las frases cortas pueden tardar unos segundos adicionales debido a la sobrecarga inicial. Esta velocidad es consistente con el tiempo real de audio.
Manejo de errores
La API devuelve códigos de estado HTTP estándar para indicar el resultado de cada solicitud. Un 200 confirma que el audio se generó correctamente, mientras que errores de cliente (4xx) indican problemas como autenticación incorrecta o límites excedidos, y errores de servidor (5xx) señalan fallas transitorias en la infraestructura.
Los fallos en la síntesis son gratuitos. Si la solicitud falla, se devuelve el crédito en su totalidad, por lo que no se cobra por intentos que no producen audio.
Códigos de estado HTTP
Utiliza los siguientes códigos para controlar el flujo de tu aplicación:
• 200 OK: Audio generado correctamente.
• 401 Unauthorized: Clave API inválida o ausente.
• 429 Too Many Requests: Has excedido el límite de solicitudes por minuto.
• 500 Internal Server Error: Fallo temporal del servidor.
Fallos y reembolso
Si la síntesis falla por razones técnicas (por ejemplo, error de servidor), la solicitud no se cobra. El crédito se mantiene en tu cuenta sin necesidad de acción manual.
Retries recomendados
Implementa reintentos con backoff exponencial para códigos 5xx y 429. Dado que las solicitudes se procesan en cola, un breve retraso entre reintentos mejora la tasa de éxito sin penalizar tu saldo.
Integración con OpenAI SDK
La API de VozLumina mantiene la misma estructura de solicitud que el endpoint de OpenAI, lo que permite reutilizar clientes existentes sin modificaciones complejas en la lógica de negocio.
Solo es necesario ajustar la URL base y proporcionar la clave API propia para que las bibliotecas oficiales funcionen con total normalidad.
Cambio de base_url
Para utilizar VozLumina con el SDK de OpenAI, basta con modificar la propiedad base_url del cliente. Esta debe apuntar a https://api.vs777.info/v1, reemplazando el dominio predeterminado de OpenAI por el de nuestra API.
Este ajuste permite que todas las llamadas posteriores utilicen la infraestructura de VozLumina sin cambiar la lógica de serialización JSON.
Misma estructura de solicitud
El formato JSON sigue siendo idéntico al de OpenAI: campos como model, input, voice y response_format se envían exactamente igual.
El SDK se encarga de la serialización, por lo que tu código Python o Node.js permanece limpio y predecible.
Ejemplo de código Python
Aquí tienes un fragmento mínimo para generar audio. Asegúrate de tener instalado openai e importar la clase OpenAI.
El código establece la URL base y realiza la solicitud estándar.
```python from openai import OpenAI client = OpenAI( base_url="https://api.vs777.info/v1", api_key="tts-tu-clave-aqui" ) audio = client.audio.speech.create( model="tts-1", voice="nova", input="Generando audio para conjuntos de datos de ML." ) audio.stream_to_file("output.mp3") ```
Escucha las 8 voces
Cada muestra a continuación fue generada por esta API a partir de la misma frase. Puedes revocar la clave actual y emitir una nueva en cualquier momento desde el mismo panel; la anterior dejará de funcionar inmediatamente.
23 idiomas
Cualquier voz puede hablar cualquiera de estos idiomas.
Fuentes y lecturas adicionales
- Wikipedia
- Tether (USDT)
- FFmpeg documentation
- openai-python on GitHub
- W3C WAI: making audio and video accessible
- LibriVox public-domain audiobooks
- Creative Commons Attribution 4.0
- curl documentation
- IETF RFC 7845: Ogg Opus
- LibriTTS-R paper (arXiv 2305.18802)
- OpenAI API reference: create speech
- ISO 639 language codes
