Documentación de la API de síntesis de voz para desarrolladores

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

Esta documentación explica cómo integrar la API de texto a voz de PlatoHabla en tu sistema de gestión gastronómica. Aquí encontrarás comandos cURL listos para copiar, ejemplos en Python y JavaScript, y la referencia completa de parámetros para generar audio de menús o avisos sin complicaciones.

La guía está pensada para desarrolladores indie que necesitan una solución técnica, económica y fácil de integrar. No importa si usas el SDK de OpenAI o peticiones HTTP directas; aquí aprenderás a manejar claves, límites y errores para automatizar la síntesis de voz en tus aplicaciones.

Documentación de la API de síntesis de voz para desarrolladores

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

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

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/

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

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

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

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

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

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

Límites y tasas

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

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

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

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. W3C WAI: making audio and video accessible
  3. IETF RFC 7845: Ogg Opus
  4. curl documentation
  5. openai-node on GitHub
  6. OpenAI API reference: create speech
  7. openai-python on GitHub
  8. Python documentation
  9. MDN: Web Speech API
  10. LibriVox public-domain audiobooks
  11. LibriTTS-R paper (arXiv 2305.18802)
  12. FFmpeg documentation

Más en este sitio