Documentación técnica de la API de texto a voz

Por Equipo editorial de CantoClaro · Actualizado 2026-11-19

Esta documentación técnica está diseñada para equipos de agencias de Recursos Humanos que integran CantoClaro en sus flujos de producción de capacitación masiva. Aquí encontrarás la referencia exacta para generar audio consistente mediante la API REST, con ejemplos listos para copiar y ejecutar en entornos de desarrollo.

La guía cubre desde la autenticación hasta la integración con el SDK de OpenAI, explicando parámetros de voz, formatos de salida y límites de uso. No es un SDK propio, sino una API compatible. Todo el código está orientado a escalar la generación de contenido sin dependencias de plataformas genéricas, asegurando control técnico y costos predecibles en tu infraestructura actual.

Documentación técnica de la API de texto a voz

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.mp3

Python (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
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

Obtención de la clave API

Ilustración de onda de sonido para: 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

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

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

Ilustración de onda de sonido para: 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

Ilustración de onda de sonido para: 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

Ilustración de onda de sonido para: 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_KEY con tu clave de CantoClaro.

Voces y modelos

Ilustración de onda de sonido para: 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).
Voces y modelos

Formatos de salida

Ilustración de onda de sonido para: 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

Ilustración de onda de sonido para: 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

Ilustración de onda de sonido para: 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.

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. Creative Commons Attribution 4.0
  3. openai-python on GitHub
  4. W3C WAI: making audio and video accessible
  5. FFmpeg documentation
  6. IETF RFC 7845: Ogg Opus
  7. Tether (USDT)
  8. LibriVox public-domain audiobooks
  9. ISO 639 language codes
  10. Python documentation
  11. TRON developer hub: TRC-20
  12. openai-node on GitHub

Más en este sitio