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.mp3Python (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 | |
|---|---|
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
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
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
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
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
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
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
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_urlen 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

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
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
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.
23 idiomas
Cualquier voz puede hablar cualquiera de estos idiomas.
Fuentes y lecturas adicionales
- Wikipedia
- LibriTTS-R paper (arXiv 2305.18802)
- Creative Commons Attribution 4.0
- curl documentation
- OpenAI API reference: create speech
- W3C WAI: making audio and video accessible
- FFmpeg documentation
- ISO 639 language codes
- Node.js documentation
- TRON developer hub: TRC-20
- openai-python on GitHub
- MDN: Web Speech API
