Preguntas frecuentes
¿Qué modelo debo usar para mejor calidad?
El modelo tts-1-hd ofrece mayor fidelidad que tts-1. Ambos modelos comparten el mismo motor de síntesis y precio. Usa tts-1 para ahorrar recursos o tts-1-hd para mayor fidelidad. La diferencia es perceptible en detalles de entonación, pero ambos son válidos para menús o avisos de restaurantes.
¿La API soporta streaming de audio?
No, la API no soporta streaming ni WebSockets. Envías el texto y recibes el archivo de audio completo al finalizar. Esto es ideal para procesos batch en sistemas de gestión gastronómica. No hay audio parcial disponible durante la generación, lo que simplifica la integración técnica con SDKs estándar.
¿Se puede enviar texto superior a 4096 caracteres?
Sí, pero debes dividir el texto en partes de hasta 4096 caracteres. La API procesa cada parte por separado. Luego, debes unir los archivos de audio generados para obtener el resultado final. Esto permite generar menús largos o avisos extensos sin limitaciones de longitud por solicitud.
¿Cómo cambio la velocidad de la voz?
Ajusta el parámetro speed en la solicitud JSON. El rango permitido es de 0.25 a 4.0. Un valor de 1.0 es la velocidad normal. Esto permite acelerar avisos rápidos o ralentizar la lectura para mayor claridad. La velocidad se aplica directamente a la síntesis sin afectar la calidad del audio.
¿Qué formato es mejor para móviles?
El formato opus es una opción válida para móviles. También puedes usar mp3 para máxima compatibilidad general. wav y flac ofrecen calidad sin pérdida pero archivos más grandes. Elige opus para ahorrar ancho de banda o mp3 para asegurar la reproducción en cualquier reproductor de audio móvil estándar.
¿La API devuelve el audio en base64 o binary?
La API devuelve el archivo de audio directamente en la respuesta. No se usa codificación base64 por defecto. Recibes el archivo binario o codificado según el formato solicitado. Esto facilita el manejo directo en aplicaciones sin necesidad de decodificar cadenas de texto adicionales en tu flujo de trabajo de desarrollo.
¿Qué hago si mi clave deja de funcionar?
Puedes emitir una nueva clave desde tu panel de cuenta. La clave anterior deja de funcionar inmediatamente al generar la nueva. Solo hay una clave activa por cuenta. Esto asegura seguridad inmediata sin esperar renovaciones. Puedes gestionar tus credenciales directamente desde la sección de configuración de tu cuenta en la plataforma.
¿Hay límite de tiempo en las respuestas?
No hay garantía de latencia fija. Las solicitudes se procesan en cola bajo carga. Textos largos pueden tardar más debido a la generación secuencial. El tiempo varía según la longitud del texto y la carga del servidor.
Primera solicitud
curl
curl https://api.abaje.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.abaje.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.abaje.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
Para comenzar a generar audio de menús o avisos, necesitas una clave API. Regístrate en /get-api-key/ usando Google o tu correo electrónico. La página mostrará tu clave, saldo y un ejemplo de curl listo para usar.
La clave se presenta en formato tts-... y se usa en el encabezado Authorization: Bearer. Asegúrate de copiarla correctamente para evitar errores de autenticación en tus solicitudes.
Registro en /get-api-key/
El registro es rápido y directo. Si usas Google, recibes una prueba de $0.50 válida por 7 días. Con correo electrónico, empiezas sin crédito de prueba. Tu saldo y uso se muestran en tiempo real.
Una clave activa por cuenta
Solo puedes tener una clave activa por cuenta. Esto simplifica la gestión de acceso para tus sistemas de gestión gastronómica o aplicaciones indie. Si pierdes la clave, puedes reemitirla.
Reemisión de clave
Puedes emitir una nueva clave en cualquier momento desde tu panel. La clave anterior deja de funcionar inmediatamente. Esto es útil si la compartiste con un servicio o la expusiste accidentalmente.
Primera solicitud con cURL
Para generar audio desde la línea de comandos, envía una solicitud POST a la ruta de síntesis. Este método directo es ideal para pruebas rápidas o integración en scripts de gestión de menús sin dependencias externas complejas.
Comando POST básico
Dirige tu solicitud a https://api.abaje.info/v1/audio/speech utilizando el método POST. Asegúrate de incluir tu clave API en el encabezado Authorization como Bearer tts-... para autenticar la petición correctamente.
- Método: POST
- URL: /v1/audio/speech
- Header: Authorization: Bearer <tu_clave>
Body JSON estándar
El cuerpo de la solicitud debe ser un objeto JSON que especifique el modelo, el texto a convertir y la voz deseada. Por ejemplo, usa tts-1 para la generación estándar o tts-1-hd para alta calidad. El texto no puede exceder los 4096 caracteres.
- model: "tts-1" o "tts-1-hd"
- input: texto máximo 4096 caracteres
- voice: nombre de la voz preset
- response_format: mp3, wav, opus, flac, pcm
Respuesta de audio
La API devuelve el archivo de audio binario directamente en el cuerpo de la respuesta. Para restaurantes o aplicaciones indie, guarda este flujo en un archivo local o envíalo directamente al cliente. Si la síntesis falla, el cargo se devuelve en su totalidad.
- Formato binario directo
- Sin almacenamiento en servidor
- Cobro solo si es exitoso
Uso con SDK de OpenAI
Para usar este servicio con las librerías oficiales de OpenAI, solo necesitas ajustar la URL base. Apunta tu cliente a https://api.abaje.info/v1 en lugar de los servidores de OpenAI. Esto permite que cualquier SDK compatible con la API de OpenAI funcione inmediatamente sin modificar la lógica de tu código.
Cambio de base_url
Configura la variable de entorno OPENAI_API_BASE o el parámetro base_url en tu cliente HTTP. Esto redirige las peticiones al endpoint correcto de la API. Es el único cambio necesario para que las bibliotecas oficiales de OpenAI funcionen.
Compatibilidad de client
Dado que seguimos la forma de solicitud de la API de OpenAI, las bibliotecas estándar como openai en Python o openai-node funcionan directamente. Solo necesitas asegurarte de que tu clave API se envíe correctamente en el encabezado de autorización.
- SDKs oficiales de OpenAI (Python, Node.js, etc.)
- Clientes HTTP compatibles con la estructura JSON
Configuración simple
Inicializa el cliente con tu clave tts-... y la URL base ajustada. El resto de los parámetros (model, input, voice) se pasan igual que en la API original. Esto facilita la integración rápida en tus sistemas de gestión gastronómica sin aprender una nueva sintaxis.
Parámetros de solicitud
Los parámetros de solicitud definen cómo se procesa tu texto. Puedes elegir entre dos modelos de motor de síntesis, configurar la voz específica para tu mensaje y ajustar la velocidad de lectura para adaptarla al contexto de tu aplicación o menú digital.
Modelo tts-1 y tts-1-hd
Ambos modelos utilizan el mismo motor y tienen el mismo precio. La diferencia radica en la calidad de audio generada, permitiendo elegir entre eficiencia estándar o mayor fidelidad según las necesidades de tu proyecto.
Voces disponibles
Puedes seleccionar entre ocho voces preestablecidas, ya sean femeninas o masculinas. Cada una tiene un tono distintivo, desde narradoras cálidas hasta voces neutrales para noticias, ideales para leer menús o avisos.
- aria: narradora clara y cálida
- nova: brillante y animada
- luna: suave, ideal para historias
- sage: calmada y de instrucciones
- felix: enérgica, buena para promos
- milo: amigable y conversacional
- atlas: neutral, estilo noticias
- orion: profunda, estilo documental
Velocidad ajustable
Puedes modificar la velocidad de habla entre 0.25 y 4.0. Esto permite acelerar la lectura de listas largas de precios o ralentizarla para mayor claridad en avisos importantes, sin perder la naturalidad del audio generado.
Formatos de audio
El formato de salida se define mediante el campo response_format en el cuerpo JSON de la solicitud. La API devuelve el archivo de audio completo en la respuesta.
La elección del formato depende del caso de uso: desde la optimización de ancho de banda en menús digitales hasta la preservación de la fidelidad original para archivado o edición posterior en sistemas de gestión gastronómica.
MP3 para web
Es el formato estándar para la reproducción en navegadores y aplicaciones móviles. Ofrece un equilibrio óptimo entre calidad audible y tamaño de archivo reducido, ideal para menús digitales o avisos de voz en pantallas de restaurantes.
- Compatible con todos los navegadores modernos y reproductores nativos.
- Tamaño de archivo eficiente para carga rápida en conexiones móviles.
WAV para alta calidad
Proporciona audio sin pérdida de compresión. Es la opción recomendada si necesitas integrar el audio en sistemas de audio profesional o si deseas maximizar la fidelidad antes de una posible edición posterior.
- Sin compresión, preservando toda la información de audio original.
- Archivo de mayor tamaño comparado con MP3.
FLAC y PCM
FLAC ofrece compresión sin pérdida, reduciendo el tamaño del archivo sin sacrificar calidad. PCM devuelve el audio crudo sin encabezados, útil para procesamiento directo en buffers de audio o herramientas de edición que requieren datos brutos.
- FLAC: compresión sin pérdida, ideal para archivado eficiente.
- PCM: datos de audio sin comprimir ni codificar.

Límites y tasas
Para mantener la estabilidad del servicio y garantizar que la síntesis de audio fluya sin interrupciones para tus menús digitales, la API impone límites claros de uso. Entender estas restricciones te permite diseñar tus flujos de generación de voz de manera eficiente, evitando errores inesperados durante la carga.
60 req/min por clave
Cada clave API permite un máximo de 60 solicitudes por minuto. Este límite se aplica por cuenta y es suficiente para la mayoría de las integraciones estándar. Si tu aplicación genera avisos o lectura de menús en tiempo real, asegúrate de no exceder esta tasa para evitar la denegación del servicio.
Límite de 4096 caracteres
Cada solicitud soporta hasta 4096 caracteres de texto, incluyendo espacios y puntuación. Si tu menú es más largo, debes dividirlo en partes y unir los archivos de audio resultantes. Este límite asegura que la generación sea rápida y predecible, manteniendo la calidad del audio sintetizado.
Cola de procesamiento
Las solicitudes se procesan una tras otra. Si excedes los límites o hay alta demanda, tu solicitud puede entrar en una cola de espera. El tiempo de generación es aproximadamente de 25 caracteres por segundo para textos largos, pero las frases cortas pueden tardar unos segundos adicionales debido a la cola.
- El límite inicial para cuentas nuevas es de 10 req/min hasta que realices tu primer recargo.
Manejo de errores
La API devuelve códigos HTTP estándar para indicar el estado de la síntesis. Un error 4xx suele señalar un problema en la solicitud, como un formato inválido o una clave inválida, mientras que un 5xx indica un fallo temporal del servidor.
Errores comunes
Los errores más frecuentes incluyen el exceso de longitud del texto (más de 4096 caracteres) o el uso de una voz no disponible. Si la síntesis falla, la respuesta contiene un código de error claro para facilitar la depuración rápida.
- Texto excedido (máx. 4096 caracteres)
- Clave API inválida o revocada
- Formato de audio no soportado
Solicitudes fallidas gratis
Si la síntesis falla, el cargo se devuelve en su totalidad. La cantidad se devuelve automáticamente a tu saldo, asegurando que solo pagues por audio generado con éxito.
Códigos de estado
Utiliza los códigos HTTP estándar para manejar la lógica de tu aplicación. Un 200 indica éxito y devuelve el archivo de audio. Otros códigos como 401 o 429 requieren atención inmediata a tu cuenta o límites de velocidad.
- 200: Éxito, audio devuelto
- 400: Solicitud mal formada
- 401: Clave incorrecta
- 429: Límite de velocidad excedido
- 500: Error interno del servidor
Ejemplos de código
Estos ejemplos prácticos demuestran cómo integrar la API de PlatoHabla en tus flujos de trabajo habituales. Puedes generar audio de menús o avisos con la herramienta que ya conoces, ya sea mediante scripts simples o bibliotecas estándar.
La compatibilidad con el formato de la API de OpenAI facilita la migración o la creación de nuevos servicios de audio para sistemas de gestión gastronómica sin necesidad de aprender una nueva sintaxis de peticiones.
Python con OpenAI SDK
Instala la librería openai y configura el cliente apuntando a tu base URL. Usa el método audio.speech.create pasando el modelo tts-1-hd, la voz nova y el texto del menú. El SDK maneja la descarga del archivo de audio binario directamente a tu disco o memoria.
JavaScript fetch
Utiliza fetch estándar para enviar un objeto JSON con model, voice, input y response_format. Asigna tu clave API en la cabecera Authorization. Para recibir el audio, convierte la respuesta en un Blob y crea una URL temporal para reproducirlo o guardarlo.
Curl bash
Envía una petición POST a /v1/audio/speech con el texto codificado en JSON. Es la forma más rápida de probar la generación de audio desde la línea de comandos durante el desarrollo de tu integración con sistemas de pedidos o menús digitales.
Escucha las 8 voces
Cada muestra a continuación fue generada por esta API a partir de la misma frase. Su tono relajado acompaña perfectamente los postres, invitando a una pausa tranquila sin prisa.
23 idiomas
Cualquier voz puede hablar cualquiera de estos idiomas.
