Preguntas frecuentes
¿Qué es la API de texto a voz?
Es un servicio en la nube que convierte texto en archivos de audio mediante una solicitud POST. Envías el texto y recibes el audio generado. Es ideal para agencias de RR. HH. que necesitan producir contenido de capacitación masivo y consistente con control técnico y costos predecibles.
¿Cómo obtengo una clave API?
Regístrate en la página /get-api-key/ usando Google o correo electrónico con contraseña. La clave se muestra en el panel junto con tu saldo y el ejemplo de curl. Cada cuenta tiene una clave activa y se emite una nueva cuando la cambias.
¿Qué es el endpoint POST /v1/audio/speech?
Es el punto final principal para generar audio. Envías texto (hasta 4096 caracteres) en formato JSON y recibes el archivo de audio. La estructura de la solicitud es idéntica al endpoint de speech de OpenAI, facilitando la integración con herramientas existentes.
¿Puedo usar el SDK de OpenAI?
Sí, los SDK oficiales de OpenAI funcionan cambiando la base_url a https://api.bets7.info/v1 y usando tu clave de CantoClaro. No es un SDK propio de CantoClaro. Esto permite utilizar la misma lógica de programación que usarías con otros servicios compatibles con este formato de solicitud.
¿Qué parámetros requiere la solicitud?
Necesitas especificar model (tts-1 o tts-1-hd), input (texto), voice (uno de 8 presets), response_format (mp3, wav, opus, flac, pcm) y speed (0.25–4.0). El idioma es opcional; si no se indica, se infiere del script o se asume inglés para texto latino.
¿Qué son los modelos tts-1 y tts-1-hd?
Son los dos modelos disponibles. Ambos utilizan el mismo motor y tienen el mismo precio por carácter. La elección entre uno u otro no afecta el costo ni la estructura de la respuesta, solo la generación.
¿Qué formatos de audio puedo solicitar?
Puedes solicitar los formatos mp3, wav, opus, flac o pcm. Estos se especifican en el campo response_format de la solicitud JSON. El audio generado se devuelve directamente en la respuesta y no se almacena, y lleva una marca de agua invisible.
¿Cuál es el límite de solicitudes por minuto?
El límite es de 60 solicitudes por minuto por clave. Antes de la primera recarga, el límite es de 10 solicitudes por minuto. Si excedes este límite, recibirás un error 429 indicando que debes esperar antes de enviar más solicitudes.
¿Qué significa un error 429?
Significa que has excedido el límite de velocidad de 60 solicitudes por minuto. Debes esperar a que el contador se reinicie antes de enviar más solicitudes. Este límite se aplica por clave API y asegura la estabilidad del servicio bajo carga.
¿Cómo funciona la autenticación Bearer?
Se utiliza el encabezado Authorization: Bearer seguido de tu clave API (que comienza con tts-...). Esta clave se obtiene al registrarte en /get-api-key/. Es la única forma de autenticación para acceder a los endpoints de generación de audio y información.
¿Puedo cambiar la clave API?
Sí, puedes emitir una nueva clave en cualquier momento desde tu panel de cuenta. Al generar una nueva, la clave anterior deja de funcionar inmediatamente. Esto es útil para rotar credenciales o revocar el acceso de un equipo específico.
¿Qué sucede con la clave anterior al cambiarla?
La clave anterior deja de funcionar al instante en el momento en que se emite la nueva. No hay período de transición ni validez simultánea. Asegúrate de actualizar tu configuración en todas las aplicaciones que utilicen la clave antigua.
Primera solicitud
curl
curl https://api.bets7.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.bets7.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.bets7.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 clave API
Acceder a la API de CantoClaro es el primer paso para automatizar la generación de material de capacitación. El proceso permite obtener las credenciales rápidamente, sin configuraciones complejas ni contratos de permanencia.
Registro en la plataforma
El registro se realiza directamente en la página /get-api-key/. Puedes crear tu cuenta utilizando tu cuenta de Google o mediante un correo electrónico y contraseña estándar. Esta flexibilidad permite que los equipos de una agencia provisionen cuentas rápidamente según sus necesidades operativas.
Generación de clave
Una vez registrado, la plataforma genera automáticamente una clave API única para tu cuenta. Esta clave es el identificador que utilizarás en las cabeceras de autorización para todas las llamadas a la API. Puedes consultarla y gestionarla desde el panel de control de tu cuenta.
Revoke y renovación
La seguridad de tus integraciones es prioritaria. Si detectas cualquier actividad inusual o simplemente deseas rotar las credenciales por política interna, puedes emitir una nueva clave en cualquier momento. Al generar una nueva, la anterior deja de funcionar de forma inmediata, garantizando un control preciso sobre el acceso.
Endpoint principal
La generación de audio se realiza mediante una única llamada HTTP a la ruta principal. El servicio acepta texto plano y devuelve un archivo de audio listo para integrarse en flujos de capacitación corporativa o plataformas LMS sin necesidad de procesamiento adicional.
Cada solicitud debe contener los parámetros esenciales para definir la calidad, el formato y la voz del sintetizador. El sistema procesa las peticiones de forma secuencial, lo que implica que bajo alta demanda puede haber una breve espera antes de la generación.
POST /v1/audio/speech
Envía el texto a sintetizar mediante el método POST al endpoint especificado. La respuesta contiene el archivo de audio binario o un error detallado si la síntesis falla, en cuyo caso no se cobra el uso.
Este punto final es el único necesario para la generación de contenido. No requiere gestión de sesiones ni conexión persistente, facilitando la integración en scripts automatizados de producción masiva de voz.
Cuerpo de la solicitud
El cuerpo debe ser un objeto JSON que incluya el texto a convertir, el modelo de voz y el formato deseado. Los campos model, input y voice son obligatorios; response_format y speed son opcionales.
La estructura es idéntica a la de la API de OpenAI, lo que permite reutilizar clientes HTTP estándar o librerías existentes sin adaptar la lógica de serialización de datos. No ofrecemos un SDK propio.
- model: "tts-1" o "tts-1-hd"
- input: texto máximo 4096 caracteres
- voice: identificador de la voz preset
- response_format: mp3, wav, opus, flac o pcm
- speed: entre 0.25 y 4.0
Parámetros obligatorios
El campo input contiene el guion de capacitación. Si el texto supera los 4096 caracteres, debe dividirse manualmente en partes y concatenarse posteriormente para mantener la coherencia narrativa.
El parámetro voice selecciona uno de los ocho presets disponibles, como aria para narración clara o atlas para tono informativo, asegurando consistencia en toda la producción de audio de la agencia.
El response_format define el contenedor del audio. Para integraciones web modernas, opus o mp3 son recomendados por su equilibrio entre calidad y tamaño de archivo.
Ejemplo con cURL
El endpoint principal acepta texto en formato JSON y devuelve un archivo de audio directamente en la respuesta. Para agilizar los flujos de capacitación, se recomienda almacenar las claves en variables de entorno y utilizar herramientas como cURL para validar la integración antes de la implementación a escala.
Comando básico
Envía una solicitud POST a https://api.bets7.info/v1/audio/speech con la cabecera Authorization: Bearer tu_clave_aqui. El cuerpo debe incluir el campo input con el texto a sintetizar, model ("tts-1" o "tts-1-hd") y voice con uno de los 8 presets disponibles.
Uso con variable
Para evitar errores de escritura, almacena tu clave API en una variable de entorno y refiérela en el comando. Esto facilita la gestión de credenciales en scripts de automatización para generar grandes volúmenes de audio sin exponer claves directamente en el código fuente.
Manejo de errores
Si la síntesis falla, la carga se devuelve íntegramente. Verifica los códigos de estado HTTP; un 401 indica clave inválida y un 429 sugiere que has excedido el límite de 60 solicitudes por minuto. Revisa el campo input para asegurar que no exceda los 4096 caracteres; si el texto es más largo, debes dividirlo en partes.
Integración con SDK OpenAI
La API es compatible con los SDK oficiales de OpenAI cambiando la base_url, lo que permite reutilizar la lógica de integración existente en los flujos de trabajo de generación de audio. Solo es necesario ajustar la URL base para apuntar a nuestros servidores, manteniendo la misma estructura de peticiones.
Este enfoque simplifica la incorporación del servicio en plataformas de e-learning o sistemas de gestión de talento, donde ya se utilizan bibliotecas estándar para comunicaciones HTTP.
Cambio de base_url
Para utilizar el SDK de OpenAI con CantoClaro, debes modificar la propiedad base_url del cliente. Configúrala como https://api.bets7.info/v1 para dirigir las solicitudes al endpoint correcto de nuestra infraestructura.
Configuración del cliente
Inicializa el cliente con tu clave API personal, que comienza con tts-. Asegúrate de que esta clave esté presente en la variable de entorno o se pase directamente al constructor. El cliente manejará la autenticación y la serialización JSON automáticamente.
Ejemplo en Python
Este script muestra cómo generar audio usando la biblioteca openai. El código es idéntico al estándar, solo cambia la URL base y la clave. El resultado se guarda como un archivo de audio local.
- Instala la dependencia:
pip install openai - Configura la variable
OPENAI_API_KEYcon tu clave de CantoClaro.
Voces y modelos
El endpoint GET /v1/voices devuelve metadatos estructurados sobre las voces disponibles, los idiomas soportados y los formatos de audio, permitiendo a las agencias validar la compatibilidad antes de generar contenido de capacitación.
El modelo tts-1 y tts-1-hd utilizan el mismo motor y tienen el mismo precio, pero tts-1-hd ofrece mayor fidelidad acústica sin alterar la estructura de la solicitud ni el precio.
GET /v1/voices
Esta llamada retorna un JSON con la lista completa de voces, sus atributos y los idiomas disponibles, facilitando la integración automatizada en flujos de trabajo de producción de audio.
Modelos tts-1 y tts-1-hd
Ambos modelos utilizan el mismo motor de síntesis y tienen un precio idéntico de $0.01 por cada 1.000 caracteres. La elección depende exclusivamente de la calidad de audio requerida para el material de entrenamiento.
Listado de voces
Se ofrecen ocho voces predefinidas con perfiles vocales distintos para variar la narrativa en los módulos de capacitación.
- Femeninas: aria (narradora clara), nova (dinámica), luna (suave), sage (instruccional).
- Masculinas: felix (energético), milo (conversacional), atlas (neutral), orion (documental).

Formatos de salida
CantoClaro ofrece cinco formatos de salida para adaptarse a las necesidades de infraestructura de tu agencia. La selección del formato afecta el tamaño del archivo y la compatibilidad con los reproductores de los sistemas de gestión del aprendizaje (LMS) que utilicen tus clientes.
MP3 y WAV
MP3 es el formato más utilizado por su equilibrio entre calidad y compresión. WAV ofrece audio sin compresión, ideal para ediciones posteriores o sistemas que requieren archivos grandes.
Ambos formatos son ampliamente compatibles con la mayoría de los reproductores de audio y plataformas LMS empresariales.
- MP3: Compresión con pérdida, archivo ligero.
- WAV: Sin pérdida, archivo más grande.
Opus y FLAC
Opus proporciona una compresión eficiente con excelente calidad a bitrates bajos, reduciendo costos de almacenamiento y ancho de banda. FLAC es audio sin pérdida con compresión sin pérdida, ideal para archivar masterizaciones.
Estos formatos son útiles cuando se manejan grandes volúmenes de capacitación para optimizar el tráfico de red sin sacrificar fidelidad.
- Opus: Alta eficiencia de compresión.
- FLAC: Sin pérdida con compresión.
PCM raw
PCM raw devuelve el audio sin codificar, útil para procesamiento personalizado o integraciones que requieren datos de audio brutos. Este formato genera archivos más grandes pero mantiene la máxima fidelidad sin overhead de códec.
Límites y errores
La API aplica un límite de 60 solicitudes por minuto por clave. Antes de la primera recarga, este límite se reduce a 10 por minuto. Esto permite un flujo estable sin saturación del servicio.
Rate limit 60 req/min
El límite estándar es de 60 solicitudes por minuto. Durante la fase inicial, con 10 solicitudes por minuto, se garantiza un control preciso del consumo.
Códigos de error HTTP
Si la síntesis falla, el cargo se devuelve íntegramente. Esto asegura que solo se pague por audio generado exitosamente.
Manejo de colas
Las solicitudes se procesan en orden secuencial. Bajo carga, las peticiones pueden esperar en una cola antes de ser atendidas, lo que puede aumentar ligeramente la latencia en picos de uso.
Autenticación
La autenticación se gestiona mediante un único token activo por cuenta. El cliente envía este token en cada solicitud para verificar la identidad y autorizar el uso del servicio.
Cabecera Authorization
Se debe incluir la cabecera HTTP Authorization en cada petición. El formato es Bearer <tu_clave>. Si falta o es inválida, la API rechaza la solicitud.
Formato Bearer
El esquema Bearer indica que la clave es un token de acceso simple. No requiere firma ni criptografía adicional, facilitando la integración con librerías HTTP estándar.
- Prefijo fijo: Bearer
- Separador: espacio único
- Token: cadena alfanumérica
Seguridad de la clave
Cada cuenta tiene una sola clave activa. Si la revocas, la anterior deja de funcionar inmediatamente. Esto permite una respuesta rápida ante posibles fugas en entornos de CI/CD.
- Una clave activa por cuenta
- Revocación inmediata al renovar
- Sin sesiones múltiples
Escucha las 8 voces
Cada muestra a continuación fue generada por esta API a partir de la misma frase. El uso de voces predefinidas asegura una calidad auditiva constante, beneficiando a empleados con dificultades de aprendizaje o lectores no nativos.
23 idiomas
Cualquier voz puede hablar cualquiera de estos idiomas.
