Documentación técnica de la API de síntesis de voz

Por equipo editorial de VozLumina · Actualizado 2026-11-19

Esta documentación técnica detalla la integración de la API de síntesis de voz de VozLumina, diseñada específicamente para ingenieros de ML y desarrolladores indie que requieren generar grandes volúmenes de audio sintético para conjuntos de datos. Encontrarás especificaciones precisas sobre el endpoint principal, autenticación y parámetros de entrada para automatizar flujos de trabajo sin fricción.

Se explican los modelos tts-1 y tts-1-hd, los 8 presets de voz disponibles y los formatos de salida compatibles. Además, se incluyen ejemplos prácticos en cURL y Python para demostrar la compatibilidad con el SDK de OpenAI, facilitando la implementación rápida y predecible de la API en tus pipelines de datos.

Documentación técnica de la API de síntesis de voz

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

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

Autenticación y clave API

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

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

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

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

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

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

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

Formatos de audio de salida

Límites y rendimiento

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

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

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

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. Tether (USDT)
  3. FFmpeg documentation
  4. openai-python on GitHub
  5. W3C WAI: making audio and video accessible
  6. LibriVox public-domain audiobooks
  7. Creative Commons Attribution 4.0
  8. curl documentation
  9. IETF RFC 7845: Ogg Opus
  10. LibriTTS-R paper (arXiv 2305.18802)
  11. OpenAI API reference: create speech
  12. ISO 639 language codes

Más en este sitio