Preguntas frecuentes
¿Cuál es la estructura del JSON de entrada?
El cuerpo de la petición POST debe contener los campos model ("tts-1" o "tts-1-hd"), input (texto máximo 4096 caracteres), voice, response_format y speed opcional. La estructura es idéntica al endpoint de speech de OpenAI, lo que facilita la integración inmediata con clientes existentes.
¿Qué modelos de voz están disponibles?
Existen dos modelos: "tts-1" y "tts-1-hd", que utilizan el mismo motor y tienen el mismo precio. Ambos soportan las 8 voces predefinidas (Aria, Nova, Luna, Sage, Felix, Milo, Atlas, Orion) y permiten ajustar la velocidad entre 0.25 y 4.0.
¿Cómo cambio la velocidad del audio?
Añade el campo speed al JSON de entrada con un valor numérico entre 0.25 y 4.0. Este parámetro ajusta la velocidad de síntesis sin afectar la calidad del audio ni el costo por carácter generado.
¿Es compatible con el SDK oficial de OpenAI?
Sí. El SDK oficial de OpenAI funciona cambiando el base_url a https://api.wasp66.info/v1 y usando tu clave API. La forma de la petición es idéntica, por lo que puedes reutilizar tu código de integración actual sin modificaciones mayores.
¿Qué formato devuelve la API por defecto?
Si no se especifica el campo response_format, la API devuelve audio en formato MP3. También puedes solicitar WAV, OPUS, FLAC o PCM directamente en la petición JSON según tus necesidades de almacenamiento o reproducción en tu aplicación SaaS.
¿Cómo se manejan los textos largos?
Debes dividir el texto en partes de máximo 4096 caracteres. Realiza una petición POST por cada fragmento y une los archivos de audio resultantes en tu lado del cliente o servidor para obtener el archivo completo. Cada petición se cobra individualmente.
¿Qué hago si mi clave deja de funcionar?
Puedes emitir una nueva clave API en cualquier momento desde tu panel de cuenta. La clave anterior dejará de funcionar inmediatamente al generar la nueva. Solo tienes una clave activa por cuenta, lo que simplifica la gestión de seguridad.
¿Cuántas peticiones puedo hacer por segundo?
El límite es de 60 peticiones por minuto por clave (10 antes del primer recargo). Esto equivale a aproximadamente 1 petición por segundo en promedio. Las solicitudes se procesan en cola, por lo que bajo carga podría haber pequeñas esperas.
¿Se pueden especificar voces por idioma?
Las 8 voces soportan los 23 idiomas listados. Si no envías el campo language, el sistema lo adivina (por defecto inglés para texto latino). Para textos en otros idiomas con script latino, especifica el código ISO para garantizar la pronunciación correcta.
¿Qué ocurre si el servidor devuelve error 5xx?
Si la síntesis falla, la carga se devuelve completamente. No se te cobra por las peticiones fallidas. Puedes reintentar la petición sin costo adicional, asegurando que solo pagas por el audio generado con éxito.
¿Cómo se audita el uso de caracteres?
El panel de cuenta muestra el balance, el crédito de prueba y los caracteres restantes. La API mantiene metadatos de tiempo, caracteres y estado para facturación. Puedes consultar el endpoint GET /v1/voices para ver precios y detalles de las voces.
¿Es necesario el campo 'input' siempre?
Sí, el campo input es obligatorio y contiene el texto a sintetizar. Debe tener un máximo de 4096 caracteres por petición. Sin este campo, la API devolverá un error de validación y no generará audio.
¿Puedo usar SSL en mis peticiones?
Sí, todas las peticiones a https://api.wasp66.info/v1 utilizan HTTPS de forma predeterminada. Esto asegura que tu texto y clave API se transmitan de forma segura a través de la red, sin necesidad de configuraciones adicionales.
¿Dónde encuentro la lista de voces?
Realiza una petición GET al endpoint https://api.wasp66.info/v1/voices. Esta ruta devuelve la lista completa de voces disponibles, los idiomas soportados, los formatos de audio y los precios asociados a cada configuración.
Primera solicitud
curl
curl https://api.wasp66.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.wasp66.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.wasp66.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 Claves
La API de VozNube utiliza autenticación estándar mediante un token Bearer. Debes incluir la cabecera Authorization: Bearer <tu-clave> en cada solicitud para validar tu identidad y facturar los caracteres generados correctamente.
Formato Bearer Token
Incluye tu clave API en el encabezado de autorización de cada petición POST. El formato es estrictamente Authorization: Bearer tts-.... Sin este encabezado, la API devolverá un error 401 Unauthorized antes de procesar el texto.
Reemplazo de clave activa
Puedes emitir una nueva clave en cualquier momento desde tu panel de control. Al generar la clave nueva, la anterior queda inválida de forma inmediata. Esto es útil si sospechas que tu clave ha sido expuesta o si deseas rotarla por seguridad sin perder acceso.
Emisión de nueva clave
La emisión se realiza desde la sección de configuración de tu cuenta. Una vez emitida, la nueva clave comienza a funcionar al instante. Asegúrate de actualizar el valor en tu variable de entorno o configuración de SDK antes de realizar la siguiente solicitud.
Endpoint Principal
El endpoint principal /v1/audio/speech acepta una solicitud POST con el texto a sintetizar y devuelve el archivo de audio resultante. Es el único punto de entrada necesario para generar voz, siguiendo la estructura estándar de la API.
POST /v1/audio/speech
Envía la carga útil JSON al URL https://api.wasp66.info/v1/audio/speech. La API procesa la solicitud y retorna el archivo de audio generado directamente en la respuesta, sin necesidad de polling adicional.
Cuerpo JSON estándar
El cuerpo de la petición debe incluir los campos model, input, voice y response_format. El campo input acepta hasta 4096 caracteres por solicitud. Si el texto excede este límite, debes dividirlo y unir los archivos resultantes.
- model: "tts-1" o "tts-1-hd"
- input: texto plano (máx. 4096 chars)
- voice: nombre del preset (ej. "aria")
- response_format: mp3, wav, opus, flac o pcm
Respuesta con archivo de audio
La respuesta contiene el archivo de audio binario correspondiente al formato solicitado. Si la síntesis falla, se devuelve un código de error y el cargo se reembolsa automáticamente en tu saldo.
Parámetros de Petición
La API acepta dos modelos idénticos en motor y precio: tts-1 y tts-1-hd. Puedes especificar cualquiera de los dos en el campo model sin impacto en la facturación ni en la calidad base del audio generado.
Ambos modelos procesan texto plano hasta 4096 caracteres por solicitud. La selección entre ellos es puramente nominal para compatibilidad con SDKs, ya que el motor subyacente es el mismo.
Modelos tts-1 y tts-1-hd
Los parámetros model y voice son obligatorios. Al igual que input, que contiene el texto a sintetizar.
El precio es uniforme: $0.01 por cada 1.000 caracteres, independientemente del modelo seleccionado.
tts-1tts-1-hd
Voces disponibles y presets
Selecciona una de las 8 voces predefinidas mediante el campo voice. Cada voz tiene un tono distintivo optimizado para diferentes contextos de uso.
Las voces son independientes del idioma; todas pueden hablar los 23 idiomas soportados si se especifica el language correcto.
- aria: narradora clara
- nova: dinámica
- luna: suave
- sage: instruccional
- felix: enérgica
- milo: conversacional
- atlas: neutral
- orion: documental
Formatos: mp3, wav, opus, flac, pcm
El campo response_format determina el codec del audio devuelto. Las opciones válidas son mp3, wav, opus, flac y pcm.
Elige wav o flac si necesitas audio sin pérdida para edición posterior, o pcm para procesamiento binario directo.
- mp3 (default)
- wav
- opus
- flac
- pcm
Configuración Avanzada
La API permite ajustar la velocidad de síntesis entre 0.25 y 4.0, facilitando la adaptación del audio a diferentes contextos de aplicación sin necesidad de post-procesamiento.
El idioma se gestiona mediante un código ISO opcional. Si no se especifica, el sistema detecta el script del texto, asumiendo inglés por defecto para texto en latín.
Control de velocidad (0.25–4.0)
Ajusta el parámetro speed para modular la velocidad de generación. Valores bajos ralentizan la voz para mayor claridad, mientras que valores altos aceleran la síntesis. Esto es útil para sincronizar narraciones con interfaces visuales o ahorrar tiempo en audio de larga duración.
- Rango aceptado: 0.25 a 4.0
Código de idioma ISO opcional
Envía el campo language con el código ISO (ej. 'es', 'de', 'ja') para forzar la pronunciación correcta. Esto evita errores cuando el texto contiene palabras ambiguas o mezclas de idiomas, asegurando que la voz sintetice con la fonética precisa requerida.
Detección automática de script
Si omites el campo language, la API infiere el idioma basándose en el script del texto. El texto en latín se asume como inglés por defecto. Para textos en latín que no sean inglés, es obligatorio especificar el código de idioma para evitar una pronunciación incorrecta.
Ejemplo con cURL
La integración más directa se logra mediante cURL, enviando el texto y la configuración en una única petición JSON. Este método es ideal para pruebas rápidas o scripts de automatización que no requieren una librería específica.
La respuesta contiene el archivo de audio binario, listo para ser guardado o transmitido. No hay metadatos adicionales en el cuerpo de la respuesta, solo el flujo de datos del audio generado.
Comando POST básico
Envía una petición POST al endpoint /v1/audio/speech con el texto en el campo input y la voz deseada. El cuerpo debe ser JSON válido, respetando el límite de 4096 caracteres por solicitud.
- Usa
model: "tts-1"para el estándar otts-1-hdpara alta definición. - Define
voicecon uno de los 8 presets disponibles. - Especifica
response_formatcomo mp3, wav, opus, flac o pcm.
Inclusión de clave Bearer
Autentica cada petición incluyendo tu clave API en el encabezado Authorization. La clave comienza con tts- y se emite desde tu panel de control.
- Header:
Authorization: Bearer tts-tu_clave_aqui - Un error 401 indica una clave inválida o expirada.
Manejo de respuesta binaria
El servidor devuelve el archivo de audio directamente en el cuerpo de la respuesta HTTP. No hay JSON de envoltura; los datos binarios son el audio final.
- Guarda la respuesta en un archivo local con
> output.mp3. - Verifica el código de estado 200 para confirmar la síntesis exitosa.

Uso con SDK OpenAI
La API de VozNube mantiene una interfaz compatible con el estándar de OpenAI, lo que permite a los desarrolladores integrar la síntesis de voz utilizando las librerías oficiales sin necesidad de un cliente personalizado.
Esta compatibilidad facilita la migración y el uso de herramientas ya conocidas en el ecosistema de desarrollo de aplicaciones SaaS.
Cambio de base_url
Para utilizar la API, simplemente configura la propiedad base_url en tu cliente SDK a https://api.wasp66.info/v1. Esto redirige todas las solicitudes al endpoint de síntesis de voz de VozNube.
Compatibilidad con librerías oficiales
Las librerías oficiales de OpenAI funcionan directamente con esta configuración. No se requiere una implementación de cliente propia ni SDK específico de VozNube.
Mismo formato de payload
El cuerpo JSON de la solicitud es idéntico al endpoint de speech de OpenAI. Utiliza los mismos campos: model, input, voice y response_format.
Manejo de Errores
La API devuelve códigos de estado HTTP estándar para indicar el resultado de la solicitud. Los errores 4xx señalan problemas con la entrada o la autenticación, mientras que los 5xx son transitorios.
Es fundamental verificar el estado de la respuesta antes de procesar el archivo de audio binario. Un código 200 indica éxito y la entrega del audio generado.
Códigos de estado HTTP
Utilizamos estándares REST para la comunicación. Un código 200 OK confirma que la síntesis se completó y el audio está listo para ser descargado en la respuesta.
Los errores 400 indican parámetros inválidos, mientras que los 401 o 403 reflejan problemas de autenticación. Los errores 5xx son transitorios y pueden ocurrir durante picos de carga en el servidor.
- 200 OK: Síntesis completada con éxito.
- 400 Bad Request: Formato JSON o parámetros incorrectos.
- 401 Unauthorized: Clave API inválida o expirada.
- 503 Service Unavailable: Cola de procesamiento saturada.
Errores de validación JSON
Si el cuerpo de la petición no cumple con el esquema esperado, la API devuelve un 400 con un mensaje descriptivo. Asegúrate de que el texto no exceda los 4096 caracteres y que el formato sea válido.
Los campos requeridos como model e input deben estar presentes. Valores fuera de rango, como una velocidad inferior a 0.25 o superior a 4.0, también generarán errores de validación inmediatos.
- Campos faltantes o nulos.
- Exceso de caracteres en el texto de entrada.
- Valores numéricos fuera del rango permitido.
Reembolso automático en fallos
Si la síntesis falla por un error interno del servidor (5xx) o la solicitud no se completa, no se cobra el crédito. El reembolso se aplica automáticamente a tu saldo.
Esta política asegura que solo pagues por audio generado exitosamente. Los errores de validación (4xx) tampoco consumen saldo, ya que la petición no se procesa.
- Créditos devueltos inmediatamente tras un fallo.
- Sin consumo de saldo en errores 5xx.
- Verifica tu balance en el panel de usuario.
Límites y Rendimiento
La API de VozNube está diseñada para integraciones SaaS con límites claros y predecibles. Cada clave API permite un máximo de 60 solicitudes por minuto, lo que facilita la planificación del tráfico sin necesidad de infraestructura compleja de caché para cargas moderadas.
60 peticiones por minuto
El límite estándar es de 60 peticiones por minuto por clave. Antes de la primera recarga, el límite se reduce a 10 peticiones por minuto. Esto permite probar la integración sin costo, pero requiere ajustar la lógica de reintento si se supera el umbral.
Límite de 4096 caracteres
Cada solicitud POST acepta un máximo de 4096 caracteres en el campo input. Los espacios y la puntuación cuentan como caracteres. Para textos más largos, es necesario dividir la entrada en partes de este tamaño y unir los archivos de audio resultantes en el lado del cliente.
Cola de procesamiento bajo carga
Las solicitudes se procesan en orden secuencial. Bajo alta demanda, las peticiones pueden entrar en una cola de espera. Esto implica que el tiempo de respuesta puede variar; en general, el audio se genera a una velocidad cercana al tiempo real (aproximadamente 25 caracteres por segundo).
Escucha las 8 voces
Cada muestra a continuación fue generada por esta API a partir de la misma frase. Esto evita errores de validación y permite un control preciso sobre la longitud de cada segmento de audio generado.
23 idiomas
Cualquier voz puede hablar cualquiera de estos idiomas.
Fuentes y lecturas adicionales
- Wikipedia
- Tether (USDT)
- W3C WAI: making audio and video accessible
- TRON developer hub: TRC-20
- OpenAI API reference: create speech
- LibriTTS-R paper (arXiv 2305.18802)
- Python documentation
- Node.js documentation
- openai-python on GitHub
- LibriVox public-domain audiobooks
- ISO 639 language codes
- LibriTTS-R corpus (OpenSLR 141)
