Preguntas frecuentes
¿Qué es una API key y cómo se usa?
Es una credencial única que autentifica tus solicitudes. Debes incluirla en el encabezado Authorization: Bearer tts-... de cada petición. Puedes generar una nueva en cualquier momento desde tu panel; la anterior dejará de funcionar inmediatamente. Cada cuenta tiene una sola clave activa válida para realizar las llamadas a la API.
¿Puedo usar la API con Python o JavaScript?
Sí, la API es compatible con los SDKs oficiales de OpenAI. Solo necesitas cambiar la base_url a https://api.carong.info/v1 y utilizar tu clave de API. Esto permite integrar la generación de voz directamente en tus aplicaciones o scripts educativos sin necesidad de desarrollar un cliente personalizado desde cero.
¿Cuántos caracteres puedo enviar por solicitud?
Cada solicitud acepta un máximo de 4096 caracteres en el campo input. Si tu texto es más largo, debes dividirlo en partes de este tamaño y unir los archivos de audio resultantes. Los espacios y la puntuación cuentan como caracteres dentro de este límite establecido.
¿Qué formato de audio es mejor para web?
El formato MP3 es la opción más equilibrada para la web, ofreciendo buena calidad y tamaño reducido. También puedes elegir WAV, OPUS, FLAC o PCM según tus necesidades. La elección depende del reproductor que utilices en tu plataforma educativa.
¿Qué ocurre si excedo el límite de solicitudes?
El límite es de 60 solicitudes por minuto por clave (10 antes del primer recargo). Si excedes este límite, las solicitudes adicionales recibirán un error de límite de velocidad. Las solicitudes fallidas no se cobran, por lo que puedes reintentar sin costo si la síntesis falla.
¿Cómo obtengo la lista de voces disponibles?
Realiza una petición GET al endpoint /v1/voices. Esta ruta devuelve información detallada sobre las 8 voces disponibles, los idiomas soportados y los formatos de audio. También puedes consultar /v1/models para ver los modelos de síntesis actuales compatibles con tu cuenta.
¿La API devuelve el audio directamente?
Sí, la respuesta contiene directamente el archivo de audio generado. No se almacena en nuestros servidores; el audio se devuelve en la respuesta HTTP. Puedes guardarlo o reproducirlo inmediatamente. El archivo incluye una marca de agua inaudible que identifica el contenido como voz sintética.
¿Se puede especificar la velocidad de lectura?
Sí, puedes ajustar la velocidad entre 0.25 y 4.0 mediante el campo speed. Esto permite ralentizar la narración para niños que están aprendiendo a leer o acelerarla para resúmenes rápidos. El valor predeterminado es 1.0, que simula una velocidad de habla natural.
¿Qué modelo tts-1 o tts-1-hd debo usar?
Ambos modelos, tts-1 y tts-1-hd, utilizan el mismo motor de síntesis y tienen el mismo precio. No hay diferencia funcional ni de precio entre los modelos. Puedes elegir cualquiera de los dos indistintamente según la compatibilidad con tu SDK o configuración preferida.
¿Cómo se manejan los errores de sintaxis?
Si la solicitud falla, la API devuelve un código de error HTTP y no se realiza ningún cargo. El error se devuelve en formato JSON con detalles sobre la causa, como un texto vacío o un formato inválido. Puedes reintentar la solicitud sin costo adicional.
¿Es necesario codificar la respuesta en base64?
No es necesario. La API devuelve el archivo de audio binario directamente en el cuerpo de la respuesta HTTP. Puedes guardar este flujo de bytes directamente en un archivo o reproducirlo en un reproductor de audio. No requiere transformación adicional para su uso estándar.
¿Puedo auditar el uso de caracteres?
Sí, tu panel de control muestra el saldo, el crédito de prueba y los caracteres consumidos. También se guardan metadatos de las solicitudes (tiempo, caracteres, estado) para facturación. Puedes ver el historial de uso y el costo acumulado directamente en la interfaz de tu cuenta.
¿Cómo se gestiona la autenticación?
Se gestiona mediante una clave API única por cuenta. Debes enviarla en el encabezado Authorization: Bearer <tu_clave> en cada petición POST. Si necesitas una nueva clave, puedes generarla en cualquier momento desde tu panel, invalidando inmediatamente la clave anterior para mayor seguridad.
¿Hay documentación para otros lenguajes?
La documentación oficial se basa en el uso de los SDKs de OpenAI, que están disponibles para Python, JavaScript, Go, Java y otros lenguajes. Solo necesitas configurar la URL base correcta. No ofrecemos un SDK propietario ni documentación específica por lenguaje, ya que utilizamos los SDKs de OpenAI.
Primera solicitud
curl
curl https://api.carong.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.carong.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.carong.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 |
Obtención de la API key
Accede a la sección /get-api-key/ de la plataforma para crear tu cuenta. Puedes registrarte con tu cuenta de Google o con un correo electrónico y contraseña. Esta es la única vía para obtener la credencial que autenticará tus solicitudes de síntesis de voz.
Registro en la plataforma
El registro es inmediato y no requiere facturación inicial. Si usas Google, recibirás $0.50 de crédito de prueba (aproximadamente 50.000 caracteres) válido por 7 días. Con email y contraseña, la cuenta se crea sin crédito inicial.
Visualización de la clave
Una vez registrado, la página muestra tu clave API única (formato tts-...). Copia esta cadena; es el identificador que debes incluir en el encabezado Authorization: Bearer de cada solicitud HTTP que realices.
Gestión de claves activas
Solo hay una clave activa por cuenta. Si la comprometes o necesitas reiniciar el acceso, puedes emitir una nueva clave en cualquier momento desde el panel. La clave anterior dejará de funcionar inmediatamente.
Primera solicitud con curl
Para probar la API, envía una solicitud POST a https://api.carong.info/v1/audio/speech con un cuerpo JSON. Este método permite generar audio directamente desde la terminal sin necesidad de librerías adicionales.
La solicitud debe incluir la clave API en la cabecera Authorization y especificar el modelo, el texto a sintetizar y la voz deseada. La respuesta contiene el archivo de audio listo para reproducirse o guardarse.
Estructura JSON del cuerpo
El cuerpo de la solicitud debe ser un objeto JSON con los campos model, input, voice y response_format. El campo input acepta hasta 4096 caracteres, incluyendo espacios y puntuación.
Por ejemplo, para narrar un cuento infantil breve, estructura el JSON especificando el modelo tts-1 y la voz luna para un tono narrativo suave.
Parámetros necesarios
Los parámetros obligatorios son model ("tts-1" o "tts-1-hd"), input (texto) y voice (uno de los 8 presets). El parámetro response_format es opcional por defecto a mp3.
Puedes ajustar la speed entre 0.25 y 4.0 o especificar un language si el texto no está en inglés para evitar la detección automática incorrecta.
- model: tts-1 o tts-1-hd
- input: cadena de texto (máx. 4096 chars)
- voice: aria, nova, luna, sage, felix, milo, atlas, orion
- response_format: mp3, wav, opus, flac, pcm
Respuesta con archivo de audio
La API devuelve el archivo de audio binario directamente en el cuerpo de la respuesta HTTP con el formato solicitado. Si la síntesis falla, se devuelve un código de error y no se cobra el crédito.
Para guardar el archivo, redirige la salida de curl a un archivo local. El audio generado lleva una marca de agua inaudible que indica que es síntesis artificial.
Integración con SDK de OpenAI
La API de Voces de Aula adopta la misma estructura de solicitudes que el endpoint de OpenAI, lo que permite reutilizar librerías oficiales sin modificar la lógica de tu aplicación. Solo necesitas ajustar la URL base para dirigir las peticiones a nuestro servidor en lugar de al de OpenAI.
Esta compatibilidad facilita la integración en proyectos educativos existentes, permitiendo a los docentes generar narraciones de cuentos infantiles utilizando código familiar y probado, sin necesidad de aprender una sintaxis de API completamente nueva desde cero.
Modificación de base_url
Para utilizar la API, configura la propiedad base_url de tu cliente SDK apuntando a https://api.carong.info/v1. Esto redirige las solicitudes al endpoint correcto sin alterar la forma del cuerpo JSON ni los parámetros enviados.
Una vez ajustada la URL, el cliente utilizará la clave API proporcionada para autenticar cada solicitud de síntesis de voz contra nuestros servidores.
- URL base: https://api.carong.info/v1
- Formato de solicitud idéntico a OpenAI Speech
- Autenticación mediante cabecera Bearer estándar
Uso de librerías oficiales
Dado que la forma de la solicitud es la misma, puedes utilizar las librerías oficiales de OpenAI (como openai-python) directamente. Solo es necesario apuntar la URL base a nuestro servicio y proporcionar tu clave de API propia.
Esto permite generar audio de forma sencilla utilizando funciones como client.audio.speech.create(), manteniendo la simplicidad de código que ya conoces para tus aplicaciones educativas.
Compatibilidad de endpoints
La integración no se limita al endpoint de generación de audio. También puedes utilizar el SDK para consultar los endpoints disponibles, como GET /v1/voices para listar las 8 voces disponibles o GET /v1/models para verificar los modelos soportados.
Esto facilita la creación de interfaces donde los docentes puedan seleccionar voces específicas para sus narraciones antes de generar el audio final.
Formatos de audio soportados
La API permite elegir entre cuatro formatos de audio para adaptar la entrega a las necesidades técnicas del aula. La selección depende del equilibrio entre calidad, tamaño de archivo y compatibilidad del reproductor que utilizarán los estudiantes o el sistema de gestión del aprendizaje.
MP3 para reproducción web
El formato MP3 es la opción predeterminada y más compatible. Ofrece un buen equilibrio entre calidad de audio y tamaño de archivo, lo que facilita la reproducción inmediata en navegadores modernos sin necesidad de complementos adicionales.
WAV para alta calidad
WAV proporciona audio sin compresión, ideal para archivos que se descargarán para edición o reproducción en reproductores estándar. Es útil cuando se requiere la máxima fidelidad para analizar fonemas o usar en materiales impresos de alta gama.
- Tamaño de archivo mayor que MP3.
- Calidad sin pérdida de datos.
OPUS y FLAC para eficiencia
OPUS ofrece una compresión eficiente con buena calidad, reduciendo el uso de ancho de banda. FLAC es un formato sin pérdida con compresión, ideal para archivar voces sin ocupar tanto espacio como WAV, manteniendo la integridad del audio para uso educativo futuro.
- OPUS: menor ancho de banda.
- FLAC: sin pérdida, comprimido.
Límites de velocidad y carga
La API de Voces de Aula está diseñada para generar audio de forma eficiente, pero requiere gestionar los límites de velocidad para garantizar la estabilidad del servicio. Cada clave API tiene un límite de 60 solicitudes por minuto, lo que permite procesar textos educativos de manera continua sin sobrecargar el sistema.
60 solicitudes por minuto
Cada cuenta puede realizar hasta 60 peticiones por minuto. Si la tasa de solicitudes supera este límite, las peticiones adicionales se retrasarán en la cola de procesamiento. Este límite es por clave API, por lo que es importante monitorear el uso en tiempo real.
- Límite estándar: 60 solicitudes por minuto por clave API
- Límite inicial: 10 solicitudes por minuto hasta la primera recarga
- Monitoreo en tiempo real del uso de la API
Cola de procesamiento
Las solicitudes se procesan en orden de llegada. Si hay múltiples peticiones simultáneas, estas se colocan en una cola y se procesan secuencialmente. Esto asegura que cada solicitud se complete correctamente antes de pasar a la siguiente.
Velocidad real aproximada
La velocidad de generación es de aproximadamente 25 caracteres por segundo para textos largos. Para frases cortas, la generación puede tomar unos segundos adicionales. Este tiempo puede variar según la carga del servidor y la complejidad del texto.

Manejo de errores comunes
La API devuelve códigos de error específicos para facilitar la depuración. Los problemas más frecuentes suelen relacionarse con la autenticación, el tamaño del texto o la selección de voz.
Asegúrate de verificar la clave y los parámetros antes de implementar en producción. La mayoría de los errores se resuelven ajustando la estructura de la solicitud.
Clave incorrecta
Si la clave Authorization no coincide o ha sido revocada, la API responde con 401. Recuerda que solo hay una clave activa por cuenta; emitir una nueva invalida la anterior inmediatamente.
Límite de caracteres excedido
Cada solicitud acepta un máximo de 4096 caracteres. Si el texto de tu cuento infantil es más largo, debes dividirlo en partes y unir los archivos de audio resultantes.
Formato de voz inválido
El campo voice debe ser uno de los 8 presets disponibles (ej. aria, nova, luna). Si se envía un nombre inexistente, la solicitud fallará sin costo.
Estructura de la respuesta
La API devuelve el archivo de audio generado directamente en el cuerpo de la respuesta HTTP, eliminando la necesidad de realizar una segunda petición para descargar el recurso. Este flujo simplifica la integración para docentes que necesitan integrar narraciones en sus aplicaciones educativas sin complicaciones de gestión de archivos temporales.
El formato del contenido y los metadatos asociados se gestionan mediante cabeceras estándar, asegurando que los navegadores y clientes API reconozcan inmediatamente el tipo de dato recibido.
Audio binario en respuesta
El cuerpo de la respuesta contiene los bytes crudos del audio sintetizado. No se devuelve un JSON con una URL, sino el archivo mismo, listo para ser reproducido o guardado. Esto es ideal para aplicaciones de lectura de cuentos infantiles que requieren una integración sencilla.
- El audio se entrega inmediatamente tras la síntesis completa
- No se requiere almacenamiento intermedio en el servidor
- Compatible con reproductores HTML5 estándar
Cabeceras de contenido
La cabecera Content-Type indica el formato del audio (ej. audio/mpeg para MP3, audio/wav para WAV). Esto permite a los clientes determinar cómo manejar los bytes recibidos sin necesidad de analizar el contenido binario manualmente.
Códigos de estado HTTP
Un estado 200 OK indica que el audio se generó correctamente. Si la clave es inválida o hay un error de formato, se devuelve un código 4xx con un mensaje descriptivo en formato JSON, facilitando la depuración en entornos educativos.
Ejemplo de código en Python
Este ejemplo muestra cómo usar la biblioteca openai en Python para integrar la API en tus herramientas educativas. Configura el cliente apuntando a la base URL correcta y autenticando con tu clave.
El script maneja textos largos dividiéndolos en bloques de 4096 caracteres, genera el audio y lo guarda localmente para su uso en clase.
Configuración de cliente
Importa la librería openai e inicializa el cliente con la clave y la base URL de Carong. Esto permite usar los mismos métodos que con OpenAI.
Envío de texto largo
Divide el cuento en fragmentos menores a 4096 caracteres. Envía cada fragmento en una solicitud separada para evitar errores de límite.
Descarga y guardado de audio
Guarda el archivo binario resultante en formato MP3 o WAV. Este archivo puede reproducirse directamente en el aula sin conexión adicional.
Escucha las 8 voces
Cada muestra a continuación fue generada por esta API a partir de la misma frase. Esto asegura que la基底 acústica cumple con los estándares de calidad sin riesgos de derechos de autor sobre la grabación original.
23 idiomas
Cualquier voz puede hablar cualquiera de estos idiomas.
