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

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

Esta documentación describe el endpoint principal de VozCura para sintetizar voz en formato audio. Está diseñada para docentes e instructores de diseño instruccional que integran audio en lecciones y módulos LMS. La API sigue el formato estándar de OpenAI, permitiendo una migración sencilla desde otros servicios de síntesis de voz sin necesidad de adaptar la lógica de negocio.

Aquí encontrarás la especificación técnica para generar audio mediante solicitudes POST con cuerpo JSON. Se detallan los parámetros de entrada, los modelos disponibles, los formatos de salida, los límites de uso y los idiomas soportados. También se explica la autenticación con claves Bearer y se proporcionan ejemplos de integración con el SDK oficial de OpenAI en Python y Node.js para un despliegue rápido y preciso.

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

Preguntas frecuentes

¿Qué formato devuelve la API?

La API devuelve audio en formato mp3, wav, opus, flac o pcm. Estos formatos se especifican mediante el parámetro response_format en la solicitud JSON. Cada formato tiene características técnicas distintas, permitiendo elegir entre compresión o calidad sin pérdida según las necesidades de tu LMS o reproductor de audio.

¿Se puede transmitir audio en tiempo real?

No. La API no ofrece streaming ni WebSockets para audio parcial. El servicio devuelve el archivo de audio completo una vez finalizada la síntesis. Para flujos en tiempo real, deberás implementar tu propia lógica de buffer o esperar a que la respuesta HTTP contenga el archivo completo generado.

¿Cuántas solicitudes simultáneas hay?

El límite es de 60 solicitudes por minuto por clave API. Antes del primer recargo, este límite se reduce a 10 solicitudes por minuto. Las solicitudes se procesan en cola secuencialmente, por lo que bajo carga alta, una solicitud puede esperar su turno antes de iniciarse la síntesis.

¿Qué pasa si excedo los 4096 caracteres?

Cada solicitud acepta un máximo de 4096 caracteres en el campo input. Para textos más largos, debes dividirlos en partes de este tamaño y unir los archivos de audio resultantes. Esto permite gestionar textos extensos manteniendo la integridad de la solicitud y evitando errores de límite de longitud.

¿Cómo se especifica el idioma?

Puedes usar el parámetro language opcional con un código ISO. Si no se especifica, el sistema intenta adivinarlo basándose en el script; el texto latino por defecto es inglés. Para textos latinos en otros idiomas, establece explícitamente el código para evitar detecciones incorrectas y asegurar la pronunciación.

¿Es compatible con la SDK de OpenAI?

Sí, la forma de solicitud es idéntica a la de OpenAI. Solo necesitas cambiar el base_url a https://api.52d.info/v1 y usar tu clave API. Las SDKs oficiales de OpenAI funcionan directamente sin modificaciones adicionales en el código, facilitando la integración en proyectos existentes que ya usen estas librerías.

¿Dónde veo mi clave API?

Tu clave API se muestra en la página /get-api-key/ de este sitio. Allí también puedes ver tu saldo, el crédito de prueba, los caracteres restantes y el historial de uso. Si necesitas una nueva clave, puedes emitirla en cualquier momento; la anterior dejará de funcionar inmediatamente.

¿Qué es el campo model?

El campo model acepta los valores tts-1 o tts-1-hd. Ambos utilizan el mismo motor de síntesis y tienen el mismo precio por carácter. La elección entre ellos es principalmente nominal para mantener compatibilidad con la estructura de la API, sin diferencias técnicas o de costo en la generación de audio.

¿Se pueden usar acentos específicos?

No hay soporte para SSML, diccionarios de fonemas ni etiquetas de emoción. La pronunciación se basa en el modelo estándar del idioma seleccionado. Si necesitas acentos específicos, debes depender de la capacidad de detección automática del idioma o especificar el código ISO correcto para guiar la síntesis.

¿Cómo se detecta el idioma automáticamente?

Si omites el parámetro language, el sistema infiere el idioma a partir del script del texto. Por defecto, el texto en latinos se asume como inglés. Para otros idiomas en latinos, es recomendable establecer el campo language explícitamente para evitar que se asigne incorrectamente el inglés y garantizar la voz adecuada.

¿Hay límite de caracteres por archivo?

Sí, el límite es de 4096 caracteres por solicitud. Si tu texto excede este número, debes dividirlo manualmente en fragmentos y unir los archivos de audio generados. Esta limitación se aplica al campo input de cada solicitud individual enviada a la API para garantizar la estabilidad del servicio.

¿Qué código de error indica fallo de pago?

Si la síntesis falla, la carga se devuelve íntegramente. Los problemas de saldo se gestionan mediante la falta de fondos, deteniendo la generación hasta que se realice un recargo.

¿Se puede cambiar la velocidad después?

La velocidad se define en el momento de la solicitud mediante el parámetro speed, con un rango de 0.25 a 4.0. No es posible modificar la velocidad del audio una vez generado el archivo. Debes ajustar este valor antes de enviar la solicitud si necesitas una velocidad de reproducción diferente.

¿Cuál es la latencia de respuesta?

La generación es aproximadamente en tiempo real, procesando unos 25 caracteres por segundo. Las frases cortas tardan unos segundos. Las solicitudes se procesan en cola; bajo carga, puede haber espera. No hay garantía de latencia fija, ya que depende del estado del servidor y la cola de procesamiento activa.

Primera solicitud

curl

curl https://api.52d.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.52d.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.52d.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

Ilustración de onda de sonido para: Autenticación y clave

La API de VozCura utiliza autenticación basada en tokens. Debes incluir tu clave única en el encabezado Authorization de cada solicitud HTTP. Esta clave identifica tu cuenta para la facturación de los caracteres generados.

Formato de la clave Bearer

Formato de la clave Bearer

Incluye el encabezado Authorization: Bearer tts-tu_clave_aqui en tus peticiones. La clave debe enviarse en cada solicitud para validar el acceso y la facturación.

Un error de autenticación devuelve un código HTTP 401. Asegúrate de que la clave no contenga espacios adicionales ni saltos de línea.

Reemplazo inmediato de claves

Reemplazo inmediato de claves

Puedes generar una nueva clave en cualquier momento desde tu panel de control. Al emitir una nueva, la anterior deja de funcionar inmediatamente.

Este mecanismo permite revocar el acceso a claves expuestas en tiempo real sin necesidad de esperar a la siguiente sesión o reinicio del servicio.

Visualización en panel de control

En la página /get-api-key/ encontrarás tu clave actual, el saldo disponible y el historial de uso. También se muestra un ejemplo de comando curl listo para copiar.

El panel refleja el estado de tu clave activa y el saldo restante tras cada solicitud exitosa o fallida.

Endpoint principal

Ilustración de onda de sonido para: Endpoint principal

La síntesis de voz se ejecuta enviando una solicitud HTTP POST al endpoint principal de la API. Este punto de entrada es el único necesario para convertir texto en audio, siguiendo una estructura JSON estandarizada compatible con los SDKs oficiales de OpenAI tras ajustar la URL base.

El servicio procesa la entrada y devuelve el archivo de audio generado directamente en la respuesta, sin necesidad de endpoints adicionales para la descarga. Este flujo simplifica la integración en sistemas de aprendizaje (LMS) o plataformas de video educativo.

Método POST /v1/audio/speech

Utilice el método POST para enviar la solicitud de síntesis. La URL completa es https://api.52d.info/v1/audio/speech. Este endpoint acepta únicamente solicitudes con cuerpo JSON que contengan los parámetros definidos en la especificación técnica.

Cuerpo JSON estándar

El cuerpo de la solicitud debe incluir los campos model, input, voice y response_format; speed y language son opcionales. El campo input acepta hasta 4096 caracteres por petición. Si el texto excede este límite, debe dividirlo en partes y concatenar los resultados posteriormente.

  • model: "tts-1" o "tts-1-hd"
  • input: texto a sintetizar (máx. 4096 caracteres)
  • voice: identificador de una de las 8 voces disponibles
  • response_format: mp3, wav, opus, flac o pcm

Respuesta con archivo de audio

Una vez procesada la solicitud, la API devuelve el archivo de audio binario correspondiente. Si la síntesis falla, no se realiza ningún cargo y la respuesta indica el error. Los archivos generados no se almacenan en nuestros servidores tras la entrega.

Parámetros de entrada

Ilustración de onda de sonido para: Parámetros de entrada

La API utiliza el campo model para seleccionar el motor de síntesis. Ambos valores, tts-1 y tts-1-hd, emplean el mismo motor de generación y tienen idéntico precio, por lo que la elección depende exclusivamente del formato de salida requerido.

El campo input acepta hasta 4096 caracteres por solicitud. Los espacios y la puntuación cuentan como caracteres. Para textos más largos, se recomienda dividir el contenido en fragmentos dentro del límite y unir los archivos de audio resultantes.

Modelo tts-1 o tts-1-hd

El parámetro model determina el motor utilizado para la síntesis. Actualmente, tanto tts-1 como tts-1-hd operan con el mismo motor subyacente y el mismo costo por carácter. No existe diferencia técnica en la calidad base ni en el precio entre ambos valores al momento de enviar la solicitud.

Campo input con texto

El campo input debe contener el texto plano que se convertirá en audio. El límite estricto es de 4096 caracteres por solicitud. Si su lección o módulo excede esta longitud, debe fragmentar el texto en partes manejables y concatenar los archivos de audio generados.

  • Máximo 4096 caracteres por solicitud.
  • Espacios y puntuación cuentan como caracteres.
  • Texto plano; no soporta SSML.

Voice y response_format

El campo voice selecciona uno de los 8 presets disponibles (ej. aria, nova, atlas). Este parámetro es obligatorio y define la timbre de la voz sintetizada. Si no se especifica language, el sistema intenta detectarlo; para textos en latinos distintos al inglés, se recomienda establecerlo manualmente.

  • 8 voces disponibles: aria, nova, luna, sage, felix, milo, atlas, orion.
  • Campos obligatorios para definir la salida.
  • No admite clonación personalizada de voces.

Velocidad y formato

Ilustración de onda de sonido para: Velocidad y formato

Ajusta la velocidad de síntesis entre 0.25 y 4.0 para sincronizar el audio con el ritmo de una lección o presentación. Este control permite adaptar la voz artificial a diferentes contextos pedagógicos sin alterar la claridad del texto.

Rango 0.25 a 4.0

El parámetro speed acepta valores decimales dentro del rango especificado. Un valor de 1.0 corresponde a la velocidad base. Valores superiores aceleran la voz, útil para repasos rápidos, mientras que valores inferiores mejoran la comprensión en conceptos complejos.

  • Mínimo: 0.25 (voz lenta)
  • Máximo: 4.0 (voz rápida)
  • Valor estándar: 1.0

Formatos mp3, wav, opus, flac

Selecciona el formato de salida mediante response_format. MP3 y OPUS son ideales para web y LMS por su eficiencia. WAV y FLAC ofrecen calidad sin pérdida para archivar o editar en estudios de audio.

  • mp3: compatible universal
  • wav: sin compresión
  • opus: alta compresión
  • flac: calidad lossless

Calidad PCM sin compresión

El formato PCM proporciona audio crudo sin compresión, garantizando fidelidad exacta para procesamiento posterior. Es adecuado cuando se requiere la máxima integridad de la señal generada por la API.

Idiomas y voces

Ilustración de onda de sonido para: Idiomas y voces

La API permite especificar el idioma de forma explícita mediante el campo language con un código ISO. Si no se establece, el sistema infiere el idioma según el script; el texto en latín predeterminado es inglés. Para textos en español o portugués con caracteres latinos, configure language explícitamente para evitar errores de pronunciación.

Campo language opcional

Definir el idioma garantiza la precisión fonética en lecciones y módulos de LMS. Si el texto contiene caracteres no latinos, la detección automática es suficiente, pero para texto latino no inglés, la especificación manual es necesaria.

Detección por script

El sistema detecta automáticamente el idioma basándose en los caracteres del texto de entrada. Esta función simplifica la integración para textos en árabe, japonés o coreano, donde el script es distintivo.

Lista de 8 voces disponibles

Selecciona la voz adecuada para el tono pedagógico o narrativo de tu contenido. Todas las voces soportan los 23 idiomas listados.

  • Aria: Narradora clara y cálida.
  • Nova: Brillante y enérgica.
  • Luna: Suave, para contar historias.
  • Sage: Calma, para instrucciones.
  • Felix: Energético, para promociones.
  • Milo: Amigable, conversacional.
  • Atlas: Neutral, para noticias.
  • Orion: Profundo, para documentales.
Idiomas y voces

Límites y rendimiento

Ilustración de onda de sonido para: Límites y rendimiento

La API aplica un límite de 60 solicitudes por minuto por clave. Antes de la primera recarga, el límite se reduce a 10 requests por minuto.

El procesamiento es secuencial: las solicitudes se ejecutan una tras otra, por lo que bajo carga una petición puede esperar en cola. Para textos largos, se deben dividir en fragmentos de máximo 4096 caracteres.

60 requests por minuto

El límite estándar es de 60 solicitudes por minuto por clave. Si la cuenta no ha realizado una recarga, el límite inicial es de 10 requests por minuto.

Cola de procesamiento secuencial

Las solicitudes se procesan en orden secuencial. Bajo alta demanda, las nuevas solicitudes pueden entrar en una cola de espera antes de comenzar la síntesis.

Límite de 4096 caracteres

Cada solicitud acepta un máximo de 4096 caracteres de texto. Para lecciones más extensas, debe dividir el contenido en partes y unir los archivos de audio resultantes.

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 síntesis. Un 200 OK confirma que el audio se generó correctamente. Los errores de cliente (4xx) indican problemas con la solicitud, mientras que los errores del servidor (5xx) señalan interrupciones temporales en la infraestructura.

Es fundamental verificar el código de estado antes de procesar la respuesta. Si la solicitud falla, no se consume saldo. Esto garantiza que los costos en proyectos educativos con alto volumen de lecciones sean predecibles y exactos.

Códigos HTTP de respuesta

Utilizamos estándares REST para la comunicación. Un código 200 indica éxito. Los códigos 400-499 representan errores de validación o autenticación. Los códigos 500-599 indican fallos transitorios del servidor.

En caso de error, el cuerpo de la respuesta contiene un mensaje descriptivo que facilita la depuración rápida en entornos de desarrollo de LMS.

  • 200: Éxito, audio disponible en la respuesta.
  • 400: Error de validación o formato JSON incorrecto.
  • 401: Clave API inválida o expirada.
  • 429: Límite de 60 requests/minuto excedido.
  • 500: Error interno del servidor (reintentar).

Solicitudes fallidas sin cargo

Si la síntesis falla por cualquier motivo (error de servidor o timeout), el cargo se devuelve íntegramente a la cuenta. No se deducen caracteres del saldo disponible.

Esta política aplica tanto para la prueba gratuita como para los fondos recargados vía USDT. Las solicitudes exitosas se cobran independientemente del tiempo de procesamiento.

Validación de cuerpo JSON

El cuerpo de la solicitud debe ser un objeto JSON válido. Si la estructura no coincide con el esquema esperado (campos faltantes o tipos incorrectos), se devuelve un error 400 inmediatamente.

Asegúrese de que el campo input no exceda los 4096 caracteres. El campo voice debe ser uno de los 8 presets listados. El campo model debe ser tts-1 o tts-1-hd.

Integración con SDK

Ilustración de onda de sonido para: Integración con SDK

La API es compatible con los SDK oficiales de OpenAI al modificar la URL base. Esto permite reutilizar el código existente ajustando la URL base.

Uso con OpenAI SDK

Utilice las bibliotecas oficiales de OpenAI para Python o Node.js. Configure la URL base para apuntar a https://api.52d.info/v1 en lugar del servicio estándar.

  • Cambio mínimo de configuración.
  • Código reutilizable sin reescribir lógica.

Cambio de base_url

Establezca la variable de entorno o parámetro de inicialización base_url a https://api.52d.info/v1. Las llamadas a /v1/audio/speech siguen el mismo formato JSON que el endpoint de OpenAI.

  • URL: https://api.52d.info/v1
  • Formato JSON idéntico al de OpenAI.

Ejemplo en Python y Node

Inicialice el cliente pasando la clave API y la URL base. Envíe el texto y el ID de la voz. Reciba el archivo de audio binario directamente en la respuesta.

Este enfoque elimina la necesidad de manejar cabeceras manualmente o parsear respuestas JSON complejas para la generación de audio.

Escucha las 8 voces

Cada muestra a continuación fue generada por esta API a partir de la misma frase. Formato sin pérdida que conserva toda la información del 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. openai-node on GitHub
  3. TRON developer hub: TRC-20
  4. W3C WAI: making audio and video accessible
  5. Python documentation
  6. LibriTTS-R corpus (OpenSLR 141)
  7. openai-python on GitHub
  8. curl documentation
  9. IETF RFC 7845: Ogg Opus
  10. OpenAI API reference: create speech
  11. LibriTTS-R paper (arXiv 2305.18802)
  12. FFmpeg documentation

Más en este sitio