Documentación Técnica de la API de Síntesis

Por Equipo editorial de VozNube · Actualizado 2026-11-19

Esta guía técnica describe la integración de la API de VozNube para desarrolladores indie que necesitan síntesis de voz predecible en aplicaciones SaaS. Aquí aprenderás a autenticar, enviar texto y recibir audio mediante endpoints REST estándar, sin dependencias de infraestructura compleja.

El documento cubre los parámetros de petición, el uso con SDKs de OpenAI y el manejo de errores. Es ideal para quienes buscan una solución económica y directa, con soporte limitado por email y sin características adicionales como streaming o SSML.

Documentación Técnica de la API de Síntesis

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

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

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

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

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

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

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

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

Ilustración de onda de sonido para: 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 o tts-1-hd para alta definición.
  • Define voice con uno de los 8 presets disponibles.
  • Especifica response_format como 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.
Ejemplo con cURL

Uso con SDK OpenAI

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

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

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

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. W3C WAI: making audio and video accessible
  4. TRON developer hub: TRC-20
  5. OpenAI API reference: create speech
  6. LibriTTS-R paper (arXiv 2305.18802)
  7. Python documentation
  8. Node.js documentation
  9. openai-python on GitHub
  10. LibriVox public-domain audiobooks
  11. ISO 639 language codes
  12. LibriTTS-R corpus (OpenSLR 141)

Más en este sitio