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

Por Equipo editorial ClaroHabla · Actualizado 2026-11-19

Esta documentación técnica explica cómo integrar la API de ClaroHabla en los sistemas de comunicación de transporte y anuncios públicos. Aquí encontrarás la estructura de los endpoints, los parámetros de la solicitud y ejemplos prácticos para generar audio de manera eficiente.

El contenido está diseñado para equipos técnicos que necesitan convertir avisos, rutas e instrucciones en voz clara y natural. Aprenderás a gestionar tu clave API, a interpretar los formatos de salida y a manejar los límites de uso con precisión.

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

Preguntas frecuentes

¿Qué es un endpoint en la API?

Un endpoint es la dirección URL donde envías tus solicitudes. Para generar audio, utiliza POST https://api.u31c.info/v1/audio/speech. Este punto final acepta texto en formato JSON y devuelve el archivo de audio generado, siguiendo la misma estructura que la API de OpenAI para facilitar su integración.

¿Qué formato de audio es mejor para transporte?

Para sistemas de transporte y anuncios, WAV o MP3 son opciones válidas por su amplia compatibilidad. MP3 ofrece compresión eficiente, mientras que WAV mantiene la calidad sin pérdida. Puedes especificar el formato deseado en el campo response_format de tu solicitud, eligiendo entre mp3, wav, opus, flac o pcm según tus necesidades.

¿Cómo se cambia la velocidad del audio?

Puedes ajustar la velocidad modificando el campo speed en tu solicitud JSON. El valor debe estar entre 0.25 y 4.0. Un valor de 1.0 es la velocidad normal. Aumentar este número acelera la voz, útil para avisos rápidos, mientras que reducirlo la hace más pausada para mayor claridad.

¿Se puede especificar el idioma?

Sí, puedes indicar el idioma mediante el campo language con un código ISO. Si no se especifica, el sistema lo adivina por el script, asumiendo inglés para texto latino. Para textos en español o alemán en formato latino, establece explícitamente el idioma para garantizar una pronunciación correcta.

¿Qué modelos hay disponibles?

Disponemos de dos modelos: tts-1 y tts-1-hd. Ambos utilizan el mismo motor de síntesis y tienen el mismo precio. La elección depende de tus requisitos de calidad de audio. Puedes seleccionar cualquiera de los dos en el campo model de tu solicitud sin variar el costo por carácter.

¿Cómo se maneja la autenticación?

La autenticación se realiza mediante una clave API en el encabezado Authorization: Bearer tts-... . Cada cuenta tiene una clave activa. Si necesitas renovar la seguridad, puedes emitir una nueva clave en cualquier momento; la anterior dejará de funcionar inmediatamente. Asegúrate de incluir este encabezado en cada solicitud.

¿Qué hace la ruta /v1/voices?

La ruta GET /v1/voices devuelve información sobre las voces, idiomas, formatos y precios. Utiliza este endpoint para listar las ocho voces preestablecidas (como aria, nova, felix) y verificar qué configuraciones son compatibles antes de enviar tus solicitudes de síntesis de audio a la API.

¿Puedo usar la API en JavaScript?

Sí, puedes usar la API en JavaScript. Dado que la forma de la solicitud es idéntica a la de OpenAI, puedes utilizar los SDK oficiales de OpenAI para JavaScript. Solo necesitas cambiar la base_url a https://api.u31c.info/v1 y proporcionar tu clave API para realizar las llamadas correctamente.

¿Qué significa un error 401?

Un error 401 indica que la autenticación falló. Esto ocurre si tu clave API es incorrecta, ha sido revocada o falta en el encabezado Authorization. Verifica que estás usando la clave activa de tu cuenta y que el formato Bearer tts-... es correcto. Emite una nueva clave si es necesario.

¿Qué significa un error 429?

Un error 429 significa que has excedido los límites de velocidad. El límite es de 60 solicitudes por minuto por clave (10 antes del primer recarga). Si recibes este error, espera un momento antes de reintentar. Para cargas altas, considera implementar una lógica de reintento con retroceso exponencial en tu código.

¿Cuántos caracteres puedo enviar en una solicitud?

Cada solicitud puede contener hasta 4096 caracteres de texto. Si tu aviso o ruta es más largo, debes dividirlo en fragmentos de este tamaño. Luego, une los archivos de audio generados para crear el mensaje completo. Esto asegura que cada parte se sintetice correctamente sin superar el límite del endpoint.

¿Se pueden unir fragmentos de audio?

Sí, para textos largos, divide el texto en partes de hasta 4096 caracteres y sintetiza cada una por separado. Luego, une los archivos de audio resultantes en tu aplicación cliente. La API devuelve cada fragmento individualmente, permitiéndote ensamblarlos para crear avisos continuos o rutas completas sin interrupciones perceptibles.

¿Cómo se detecta el idioma automáticamente?

Si no envías el campo language, el sistema adivina el idioma basándose en el script del texto. El texto en latín se asume por defecto como inglés. Para otros idiomas como español, alemán o francés en formato latino, es recomendable especificar explícitamente el código ISO para evitar errores de pronunciación.

¿Es compatible con curl?

Sí, la API es totalmente compatible con curl. Puedes realizar solicitudes POST enviando el JSON con el texto, voz y formato deseados. Incluye la cabecera Authorization con tu clave Bearer. La documentación incluye ejemplos listos para copiar y pegar, facilitando las pruebas rápidas.

Primera solicitud

curl

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

Accede a tu panel desde /get-api-key/ registrándote con tu cuenta de Google o con correo y contraseña. La primera opción incluye un crédito de prueba de 0,50 $ válido por 7 días.

Una vez registrado, tu clave API se muestra en el panel junto con tu saldo actual. Esta clave es el único mecanismo para autenticar tus solicitudes.

Registro con Google o correo electrónico

Registro con Google o correo electrónico

Crea una cuenta en la página de obtención de clave. El registro con Google otorga automáticamente un crédito inicial de 0,50 $ (aproximadamente 50 000 caracteres) válido durante 7 días. Si prefieres usar correo y contraseña, la cuenta se crea sin este crédito de prueba.

Las cuentas son independientes por sitio y se gestionan directamente desde la interfaz del panel. No requiere facturación previa para comenzar a probar la integración.

Ubicación de la clave en el panel

Ubicación de la clave en el panel

La clave API se visualiza claramente en la página principal de tu panel, junto con información clave como el saldo actual, el estado de la prueba y los caracteres consumidos.

Utiliza esta clave en el encabezado Authorization de tus solicitudes HTTP. Asegúrate de copiarla correctamente, ya que es el único identificador activo para tu cuenta en este momento.

  • La clave comienza por el prefijo tts-.

Emisión de una nueva clave

Puedes emitir una nueva clave API en cualquier momento desde el panel. Al generar una nueva, la clave anterior deja de funcionar de forma inmediata.

Este mecanismo es útil para mayor seguridad o si sospechas que la clave ha sido expuesta. Solo se mantiene activa una clave por cuenta simultáneamente.

Primera solicitud con curl

Ilustración de onda de sonido para: Primera solicitud con curl

Antes de integrar la API en tu sistema de anuncios, verifica el funcionamiento básico con una solicitud directa. Esto te permite confirmar que el formato de audio es correcto y que la voz seleccionada se ajusta al tono de tus avisos de transporte o rutas.

El endpoint POST /v1/audio/speech acepta texto en formato JSON. Es fundamental que el texto no supere los 4096 caracteres por petición para evitar errores de síntesis inmediata.

Estructura del cuerpo JSON

El cuerpo de la solicitud debe ser un objeto JSON que contiene los parámetros necesarios para la síntesis. Todos los campos son obligatorios excepto language y speed.

Asegúrate de que el texto esté codificado correctamente y no exceda el límite de caracteres por petición.

  • model: "tts-1" o "tts-1-hd"
  • input: el texto a convertir
  • voice: una de las 8 voces disponibles
  • response_format: mp3, wav, opus, flac o pcm
  • speed: valor entre 0.25 y 4.0
  • language: código ISO opcional

Parámetros obligatorios y opcionales

El parámetro model define la calidad del audio. Ambos modelos usan el mismo motor y precio, pero "tts-1-hd" ofrece mayor fidelidad.

Si no especificas language, el sistema intentará adivinarlo basándose en el guion (el texto en latín se asume como inglés por defecto). Para textos en otros idiomas con alfabeto latino, establece el código ISO explícitamente.

El parámetro voice debe coincidir con uno de los presets disponibles. La velocidad se ajusta con speed.

  • model: tts-1 o tts-1-hd
  • input: texto máximo 4096 caracteres
  • voice: aria, nova, luna, sage, felix, milo, atlas, orion
  • response_format: mp3, wav, opus, flac, pcm
  • speed: 0.25 a 4.0
  • language: código ISO opcional

Ejemplo completo de comando

Este comando curl envía un aviso de autobús usando la voz "atlas" en formato MP3.

La respuesta devolverá el archivo de audio binario directamente en la consola o puedes redirigirlo a un archivo.

Asegúrate de reemplazar YOUR_API_KEY con tu clave real obtenida en /get-api-key/.

  • curl -X POST "https://api.u31c.info/v1/audio/speech" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{"model": "tts-1", "input": "Próxima parada: Centro Comercial", "voice": "atlas", "response_format": "mp3"}'

Uso con SDK de OpenAI

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

La API de ClaroHabla sigue el mismo formato de solicitud que OpenAI, lo que permite reutilizar las bibliotecas oficiales sin cambiar la lógica de tu código. Solo necesitas ajustar la URL base para apuntar a nuestro servidor.

Esta compatibilidad facilita la integración rápida en flotas de transporte o sistemas de anuncios públicos, aprovechando herramientas que tu equipo ya conoce para generar avisos claros y naturales.

Cambio de base_url

Para utilizar las librerías oficiales, modifica la variable base_url de tu cliente SDK para que apunte a https://api.u31c.info/v1. Esto redirige las solicitudes directamente a nuestro endpoint sin alterar la estructura del cuerpo JSON.

Con este ajuste simple, puedes usar el mismo código de generación de voz que usarías con OpenAI, pero obteniendo los resultados de ClaroHabla con las voces y precios de nuestra red.

  • URL base: https://api.u31c.info/v1
  • Formato de solicitud idéntico al estándar de OpenAI
  • Sin necesidad de adaptar la lógica de tu aplicación

Compatibilidad con librerías oficiales

Las bibliotecas oficiales de OpenAI funcionan correctamente porque respetamos la forma de los cuerpos JSON y los encabezados de autenticación. Esto significa que puedes usar openai-python u otras SDKs compatibles con la especificación.

La única diferencia radica en la autenticación: debes proporcionar tu clave API de ClaroHabla con el prefijo tts-... en el encabezado Authorization: Bearer.

  • Compatible con openai-python y clientes HTTP estándar
  • Respuestas con archivo de audio binario
  • Funciona con las versiones más recientes de las SDK oficiales

Ejemplo de código en Python

El siguiente fragmento muestra cómo generar audio usando la librería oficial. Asegúrate de instalar la librería con pip install openai y configurar tu clave API en la variable de entorno OPENAI_API_KEY.

Recuerda que debes ajustar la base_url para que apunte a nuestro servidor en https://api.u31c.info/v1. El resto de los parámetros, como model, input y voice, se mantienen igual que en la especificación estándar.

Este ejemplo genera un archivo de audio en formato MP3, ideal para integrarse en sistemas de anuncios públicos o avisos de transporte donde la compatibilidad es clave.

  • Instalación: pip install openai
  • Configuración de base_url: https://api.u31c.info/v1
  • Generación de audio en formato MP3

Endpoints disponibles

Ilustración de onda de sonido para: Endpoints disponibles

La API de ClaroHabla expone tres endpoints principales para la generación y gestión de audio. El punto central es la conversión de texto a voz, mientras que los otros dos facilitan la verificación de capacidades disponibles sin necesidad de generar archivos.

Estos recursos permiten integrar la síntesis de voz directamente en los sistemas de avisos y rutas de transporte, asegurando que cada solicitud reciba la respuesta adecuada en formato JSON o audio binario.

None

Generación de audio: POST /v1/audio/speech

Este es el endpoint principal. Envía texto en formato JSON y recibe el archivo de audio generado. Puedes especificar el modelo, la voz, el formato de salida y la velocidad.

El texto no puede exceder los 4096 caracteres por solicitud. Si tu anuncio es más largo, debes dividirlo y unir los archivos resultantes.

  • Modelos: tts-1 o tts-1-hd
  • Voces: 8 presets disponibles
  • Formatos: mp3, wav, opus, flac, pcm
  • Rango de velocidad: 0.25 a 4.0

Listado de voces: GET /v1/voices

Obtén la lista completa de voces, idiomas soportados y formatos disponibles. Este recurso te permite verificar qué configuraciones son válidas antes de enviar una solicitud de síntesis.

Utiliza esta información para asignar la voz adecuada a cada tipo de anuncio o ruta dentro de tu flota de transporte.

  • 8 voces disponibles
  • 23 idiomas soportados
  • Precios por voz

Modelos disponibles: GET /v1/models

Consulta los modelos de síntesis de voz actualmente activos. Actualmente se ofrecen dos opciones: tts-1 y tts-1-hd, que utilizan el mismo motor y tienen el mismo precio.

Esta información es útil para verificar la disponibilidad de los servicios antes de iniciar una integración masiva en tus sistemas de comunicación pública.

  • tts-1
  • tts-1-hd

Formatos de audio soportados

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

La API de ClaroHabla permite especificar el formato de salida en cada solicitud mediante el parámetro response_format. Esto facilita la integración directa con los sistemas de reproducción de los autobuses, trenes o paneles de información, adaptándose a las necesidades técnicas de cada entorno sin necesidad de conversiones adicionales.

MP3 para compresión y compatibilidad

El formato MP3 es la opción más adecuada para la mayoría de las aplicaciones de transporte público. Ofrece un excelente equilibrio entre calidad de voz y tamaño de archivo, lo que reduce el uso de ancho de banda en sistemas que transmiten avisos frecuentes. Su amplia compatibilidad garantiza que el audio se reproduzca correctamente en cualquier reproductor o controlador de anuncios sin configuraciones complejas.

WAV para alta fidelidad

El formato WAV se utiliza cuando se requiere alta fidelidad sin pérdida de datos. Es ideal para sistemas de audio profesional o grabaciones locales donde la integridad del sonido es prioritaria. Aunque los archivos son más grandes que los MP3, garantizan una reproducción nítida y clara, especialmente útil en espacios con mucho ruido ambiente donde cada sílaba del aviso debe ser perfectamente audible para los pasajeros.

OPUS, FLAC y PCM para casos específicos

Los formatos OPUS y FLAC permiten optimizar la eficiencia o la calidad según necesidades técnicas específicas. OPUS es eficiente para transmisión, mientras que FLAC ofrece compresión sin pérdida. PCM proporciona audio sin comprimir, ideal para procesos de edición posterior o pruebas de calidad. Estos formatos adicionales permiten adaptar la salida de la API a infraestructuras de audio legacy o sistemas de almacenamiento que requieren estructuras de bits específicas sin sobrecarga de procesamiento.

Formatos de audio soportados

Límites y tasa de solicitudes

Ilustración de onda de sonido para: Límites y tasa de solicitudes

La API está diseñada para manejar cargas de trabajo variables, desde avisos puntuales hasta actualizaciones de rutas. Es importante configurar correctamente los límites de velocidad para evitar interrupciones en la generación de audio.

60 solicitudes por minuto por clave

Cada clave API permite realizar hasta 60 solicitudes por minuto una vez activado el saldo. Este límite es suficiente para la mayoría de las integraciones de anuncios públicos y notificaciones de transporte.

10 solicitudes por minuto antes del primer pago

Durante la fase inicial, antes de realizar el primer recargo, el límite se reduce a 10 solicitudes por minuto. Esto permite probar la integración sin saturar los servidores mientras se configura la cuenta.

Gestión de cola bajo carga

Las solicitudes se procesan en orden de llegada. Si se excede la capacidad de procesamiento, las peticiones adicionales se ponen en una cola interna. Esto garantiza que no se pierdan avisos, aunque la generación tarde unos segundos adicionales.

Manejo de errores comunes

Ilustración de onda de sonido para: Manejo de errores comunes

Manejar errores con precisión evita interrupciones en la difusión de avisos o rutas. La API devuelve códigos HTTP claros que indican la causa exacta del fallo, permitiendo una corrección inmediata.

Error 401: clave inválida

Este error indica que la clave Authorization: Bearer no coincide con una cuenta activa. Si emitiste una nueva clave, la anterior deja de funcionar de inmediato. Verifica que no haya espacios extra o que uses la clave correcta de tu panel.

Error 429: límite de tasa excedido

La API permite 60 solicitudes por minuto por clave. Si superas este límite, recibirás un error 429. Antes del primer pago, el límite es de 10 solicitudes por minuto. Implementa un reintentos con retard exponencial para gestionar la cola sin perder avisos críticos.

Errores de formato JSON

Si el cuerpo de la solicitud no es JSON válido o falta un campo obligatorio (como model o input), la API rechaza la petición. Asegúrate de que el texto no exceda los 4096 caracteres por request y que los valores sean del tipo esperado.

Autenticación y seguridad

Ilustración de onda de sonido para: Autenticación y seguridad

La API de ClaroHabla utiliza autenticación basada en tokens para garantizar que solo las solicitudes autorizadas generen audio. Cada cuenta posee una única clave activa que identifica la cuenta y permite el acceso a los endpoints de generación y gestión.

Uso del encabezado Authorization Bearer

Incluye el encabezado Authorization: Bearer tts-tu-clave-aqui en cada solicitud HTTP. Esta clave se genera al registrarte en /get-api-key/ y debe enviarse en cada llamada a la API para validar la identidad y cargar el saldo.

Una clave activa por cuenta

Por diseño, cada cuenta solo mantiene una clave activa simultáneamente. Esto simplifica la gestión de seguridad en equipos grandes de transporte, ya que no necesitas rotar múltiples tokens para diferentes desarrolladores o sistemas de anuncio.

Invalidación inmediata al emitir nueva clave

Al generar una nueva clave desde tu panel, la anterior deja de funcionar instantáneamente. No hay periodo de transición, por lo que debes actualizar la configuración en tus sistemas de comunicación antes de emitir la nueva clave para evitar interrupciones en los avisos públicos.

Escucha las 8 voces

Cada muestra a continuación fue generada por esta API a partir de la misma frase. Asegúrese de que su sistema de audio soporte el formato seleccionado para evitar problemas de compatibilidad.

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

Más en este sitio