Documentación API: Leer texto en voz alta desde código

Por Equipo editorial VozCerta · Actualizado 2026-11-18

Esta documentación técnica describe la integración de la API de síntesis de voz de VozCerta para plataformas de aprendizaje y startups educativas. Aquí encontrarás la especificación exacta del endpoint, parámetros de solicitud y ejemplos de código para convertir texto en audio mediante protocolos estándar.

La guía está diseñada para desarrolladores que necesitan implementar audio accesible en sus cursos o LMS. Utiliza la estructura compatible con el SDK de OpenAI para una integración rápida y predecible, sin dependencias de librerías propietarias ni configuraciones complejas.

Documentación API: Leer texto en voz alta desde código

Preguntas frecuentes

¿Qué formato de autenticación usa la API?

La API utiliza autenticación Bearer. Debes incluir tu clave en el encabezado Authorization: Bearer tts-... de cada solicitud. Cada cuenta tiene una clave activa; si emites una nueva, la anterior deja de funcionar inmediatamente.

¿Puedo usar el SDK oficial de OpenAI?

Sí. El formato de solicitud es idéntico al endpoint de speech de OpenAI. Solo necesitas cambiar la base_url a https://api.play333a.com/v1 y usar tu clave de API. Esto permite integrar la voz sintética rápidamente en tus flujos existentes.

¿Cuál es el límite de caracteres por petición?

Cada solicitud HTTP puede contener hasta 4096 caracteres en el campo input. Si tu texto excede este límite, debes dividirlo en partes más pequeñas y generar el audio para cada fragmento por separado.

¿Qué formatos de audio puedo solicitar?

Puedes solicitar audio en los formatos mp3, wav, opus, flac o pcm. Configura el campo response_format en tu solicitud JSON para obtener el archivo de audio en el formato que requiera tu plataforma educativa.

¿Cuántas solicitudes permito por minuto?

El límite es de 60 solicitudes por minuto por clave API. Si tu cuenta no tiene saldo topado aún, el límite es de 10 solicitudes por minuto. Las solicitudes fallidas no consumen este límite.

¿Qué pasa si excedo el límite de caracteres?

Si envías más de 4096 caracteres en una sola petición, la solicitud será rechazada. Debes dividir tu texto en fragmentos menores a ese límite y realizar múltiples llamadas para obtener el audio completo.

¿Es necesario instalar una librería propia?

No. No tenemos un SDK propio. Puedes usar el SDK oficial de OpenAI o cualquier cliente HTTP estándar. Solo necesitas ajustar la URL base y usar la clave de autenticación proporcionada en tu panel.

¿Cómo manejo textos que superan 4096 caracteres?

Debes dividir el texto en partes de hasta 4096 caracteres. Realiza una solicitud por cada parte y luego une los archivos de audio resultantes. Esto asegura que cada fragmento se sintetice correctamente sin errores de límite.

Primera solicitud

curl

curl https://api.play333a.com/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.play333a.com/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.play333a.com/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

Para consumir la API de VozCerta, es obligatorio autenticar cada solicitud mediante un token Bearer. La clave se gestiona desde el panel de control en /get-api-key/, donde se visualiza el identificador único asociado a tu cuenta.

Generación de clave Bearer

Generación de clave Bearer

Al registrarte, se asigna una clave activa única. Esta credencial es el único medio para autorizar las peticiones de síntesis de voz.

Uso de Authorization header

Uso de Authorization header

Incluye la cabecera Authorization: Bearer tts-<tu_clave> en cada petición HTTP. Sin este encabezado, la API rechazará la solicitud.

Invalidación de claves

Puedes generar una nueva clave en cualquier momento desde tu panel. La clave anterior deja de ser válida instantáneamente, garantizando seguridad inmediata.

Endpoint de síntesis

Ilustración de onda de sonido para: Endpoint de síntesis

La síntesis de audio se realiza mediante una llamada HTTP POST a la ruta de la API. Este endpoint acepta texto plano y devuelve un archivo de audio binario en la respuesta.

Método POST

Se utiliza el método POST para enviar la carga útil de la solicitud. Es el método estándar para operaciones que generan recursos, en este caso, el archivo de audio a partir del texto proporcionado.

Ruta /v1/audio/speech

La URL base es https://api.play333a.com/v1. La ruta completa para la síntesis es /audio/speech. Esta ruta es compatible con el SDK oficial de OpenAI si se configura la URL base correctamente.

Formato JSON

El cuerpo de la solicitud debe ser un objeto JSON. Incluye campos como model, input, voice y response_format. El texto a convertir no puede exceder los 4096 caracteres por solicitud.

  • model: tts-1 o tts-1-hd
  • input: texto a convertir
  • voice: identificador del preset
  • response_format: mp3, wav, opus, flac o pcm

Parámetros de solicitud

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

La API acepta texto plano y lo convierte en audio mediante parámetros específicos. Cada campo define el contenido, la voz y el formato de salida del archivo generado.

Campo input (texto)

Campo obligatorio que contiene el texto a sintetizar. Debe tener un máximo de 4096 caracteres por solicitud, incluyendo espacios y puntuación.

Campo voice (presets)

Selecciona uno de los 8 presets disponibles (ej. aria, nova, atlas). Cada voz tiene un tono distinto y puede hablar cualquier idioma soportado si se especifica el código ISO.

Campo response_format

Define el formato del audio devuelto. Opciones: mp3, wav, opus, flac o pcm. MP3 es un formato comprimido; WAV, FLAC y PCM son sin compresión o sin pérdida.

Ejemplo con cURL

Ilustración de onda de sonido para: Ejemplo con cURL

Usa cURL para validar rápidamente la integración de VozCerta sin depender de librerías externas. Este método directo permite verificar la autenticación y el formato de respuesta antes de implementar la lógica completa en tu aplicación.

El ejemplo muestra una solicitud POST estándar contra el endpoint de síntesis, devolviendo el audio binario listo para ser guardado o reproducido inmediatamente en tu plataforma de aprendizaje.

Comando básico

Ejecuta la siguiente solicitud reemplazando tts-... con tu clave API. La respuesta devolverá el archivo de audio directamente en el cuerpo de la respuesta.

Manejo de archivos

Redirige la salida binaria a un archivo local usando > audio.mp3. Esto permite almacenar el contenido generado para su uso posterior en los cursos, sin necesidad de procesamiento adicional en memoria durante la solicitud.

Verificación de respuesta

Un código 200 indica éxito. Si recibes un error, revisa la autenticación o el límite de caracteres. Los errores de validación incluyen un código de estado HTTP específico y un mensaje descriptivo en formato JSON.

  • 200: Éxito, audio generado.
  • 401: Clave inválida.
  • 429: Límite de 60 RPM excedido.

Uso con SDK de OpenAI

Ilustración de onda de sonido para: Uso con SDK de OpenAI

El SDK de OpenAI funciona correctamente mediante la simple modificación de la URL base. Al cambiar base_url a https://api.play333a.com/v1, las librerías oficiales utilizan la ruta correcta para los endpoints de síntesis sin requerir cambios en la lógica de las solicitudes.

Esta configuración permite reutilizar el código existente en Python o Node.js, ajustando únicamente la credencial y la dirección del servidor. Es ideal para integraciones rápidas en plataformas educativas que ya emplean estas herramientas.

Modificación de base_url

Establece la variable de entorno o parámetro base_url a https://api.play333a.com/v1. Esto redirige las llamadas estándar al endpoint POST /v1/audio/speech de nuestra API.

No es necesario modificar la estructura del cuerpo JSON ni los nombres de los campos (model, input, voice).

Asegúrate de que la clave API (Authorization: Bearer) sea válida para este dominio específico.

  • URL base: https://api.play333a.com/v1
  • Método estándar compatible
  • Sin cambios en el payload JSON

Configuración de cliente

Inicializa el cliente de OpenAI pasando la URL base y tu clave de inicio de sesión de VozCerta.

El cliente interpretará las llamadas Audio.speech hacia nuestra infraestructura de síntesis de voz.

La autenticación se gestiona mediante el encabezado Bearer estándar.

  • Inyectar base_url en la configuración inicial
  • Usar clave tts-... de VozCerta
  • Mantener la sintaxis nativa del SDK

Compatibilidad de librerías

Las librerías oficiales de OpenAI son compatibles mediante la modificación de la URL base.

El formato de respuesta es idéntico al estándar, facilitando la integración en pipelines de audio existentes.

No se requiere una SDK propietaria ni plugins adicionales para esta integración.

  • SDK de OpenAI (Python/Node)
  • HTTP estándar (curl/requests)
  • Sin dependencias extra
Uso con SDK de OpenAI

Manejo de errores y límites

Ilustración de onda de sonido para: Manejo de errores y límites

La API impone límites técnicos precisos para garantizar la estabilidad del servicio. El texto de entrada se limita a 4096 caracteres por solicitud y la tasa máxima es de 60 solicitudes por minuto por clave activa.

Los errores devuelven códigos HTTP estándar. Las solicitudes fallidas son gratuitas y el cargo se devuelve en su totalidad.

Límite de 4096 caracteres

Cada campo input acepta un máximo de 4096 caracteres, incluyendo espacios y puntuación. Si el texto excede este límite, la API rechaza la solicitud.

  • El texto se divide en partes de 4096 caracteres y se unen los audios generados.

Límite de 60 RPM

La tasa máxima es de 60 solicitudes por minuto por clave. Antes del primer recargo, el límite es de 10 RPM.

Las solicitudes se procesan en cola; bajo carga, el tiempo de respuesta puede aumentar.

Códigos de estado HTTP

Se devuelven códigos estándar HTTP para indicar el estado de la síntesis o errores de validación.

Si la síntesis falla, no se aplica el cargo y el crédito se devuelve.

Formatos de audio soportados

Ilustración de onda de sonido para: Formatos de audio soportados

El API devuelve audio en cuatro formatos estándar: mp3, wav, opus, flac y pcm. La selección del formato depende del caso de uso, desde la distribución web hasta el procesamiento técnico.

Cada formato optimiza el equilibrio entre calidad, tamaño de archivo y compatibilidad con reproductores o pipelines de aprendizaje automático.

MP3 para web

El formato MP3 ofrece compresión con pérdida, ideal para reproducción en navegadores y dispositivos móviles. Reduce significativamente el tamaño del archivo, facilitando la entrega rápida de contenido de cursos a estudiantes sin consumir ancho de banda excesivo.

  • Amplia compatibilidad con reproductores web y aplicaciones móviles
  • Tamaño de archivo reducido para carga rápida
  • Calidad suficiente para narración de texto

WAV para alta calidad

El formato WAV proporciona audio sin compresión. Es adecuado para ediciones de audio posteriores o análisis acústico donde la fidelidad original de la síntesis es prioritaria, sin pérdida de datos por compresión.

  • Audio sin compresión
  • Preserva la fidelidad original
  • Ideal para procesamiento posterior

FLAC y PCM sin pérdida

FLAC ofrece compresión sin pérdida de datos, manteniendo la integridad exacta del audio generado. PCM es datos de audio sin compresión, proporcionando un flujo crudo listo para ingestión inmediata en sistemas de procesamiento de señal.

  • FLAC: compresión sin pérdida
  • PCM: datos crudos sin compresión
  • Integridad exacta del audio

Manejo de textos largos

Ilustración de onda de sonido para: Manejo de textos largos

Cuando el texto supera los 4096 caracteres, el servicio no genera un único archivo continuo. Es necesario dividir la entrada en fragmentos de ese límite y enviar cada uno en una solicitud independiente.

El resultado final se construye concatenando los archivos de audio recibidos en orden. Dado que las solicitudes se procesan secuencialmente, el tiempo total de generación escala linealmente con la longitud del texto, aproximadamente 25 caracteres por segundo.

División por caracteres

Cada solicitud POST debe contener un campo input de máximo 4096 caracteres. Si tu contenido excede este límite, debes fragmentarlo antes de enviarlo al endpoint.

Los espacios y la puntuación cuentan como caracteres, por lo que el conteo debe realizarse sobre la cadena exacta que se enviará.

  • Límite estricto: 4096 caracteres por request.

Unión de archivos de audio

Recibirás múltiples archivos de audio, uno por fragmento enviado. Tu sistema debe unirlos secuencialmente para reproducir el texto completo sin pausas artificiales.

El formato de unión depende del response_format seleccionado (mp3, wav, etc.).

Gestión de memoria

Las solicitudes se procesan una tras otra. Bajo carga, puede haber espera en cola, lo que alarga el tiempo total de generación para textos largos.

Asegúrate de gestionar la memoria temporal para almacenar los fragmentos de audio antes de la unión final, especialmente si usas formatos sin pérdida como FLAC.

Escucha las 8 voces

Cada muestra a continuación fue generada por esta API a partir de la misma frase. Tu plataforma de aprendizaje permite a los emprendedores escalar su conocimiento con cursos online intuitivos y modernos.

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. LibriTTS-R paper (arXiv 2305.18802)
  3. Creative Commons Attribution 4.0
  4. curl documentation
  5. OpenAI API reference: create speech
  6. W3C WAI: making audio and video accessible
  7. FFmpeg documentation
  8. ISO 639 language codes
  9. Node.js documentation
  10. TRON developer hub: TRC-20
  11. openai-python on GitHub
  12. MDN: Web Speech API

Más en este sitio