Documentación técnica para tu restaurante

Por equipo editorial RestoVoice · Actualizado 2026-11-19

Aquí encontrarás la documentación técnica para integrar nuestra API de texto a voz en tu restaurante. Aprenderás a generar tu clave, enviar solicitudes con cURL o el SDK de OpenAI (cambiando la base_url), y gestionar voces y formatos de audio sin complicaciones.

Esta guía está diseñada para equipos de startups hosteleras que necesitan audio rápido y natural. Cubre desde la configuración inicial hasta el manejo de errores, límites de velocidad y privacidad de tus datos, para que integres avisos o menús digitales con claridad.

Documentación técnica para tu restaurante

Preguntas frecuentes

¿Qué es un endpoint en esta API?

Es la dirección web donde envías tus peticiones. Para generar audio, usa POST en https://api.kb44.info/v1/audio/speech con un cuerpo JSON. También puedes consultar voces y modelos en GET /v1/voices y GET /v1/models. Este endpoint es el punto de conexión principal para recibir tus archivos de audio generados.

¿Puedo usar el SDK de Python de OpenAI?

Sí, el formato de solicitud es idéntico al de OpenAI. Solo necesitas cambiar la base_url a https://api.kb44.info/v1 y usar tu clave API de RestoVoice. Esto permite reutilizar tu código existente sin modificaciones mayores en la lógica de integración con la API de texto a voz.

¿Cuál es la diferencia entre tts-1 y tts-1-hd?

Ambos modelos utilizan el mismo motor de síntesis y tienen el mismo precio. La elección entre 'tts-1' y 'tts-1-hd' no afecta el costo ni la calidad perceptible del audio generado, por lo que puedes usar cualquiera de los dos indistintamente para tus menús digitales o avisos.

¿Qué formatos de audio son más ligeros?

Puedes solicitar MP3, OPUS, FLAC o PCM. MP3 y OPUS son formatos comprimidos que reducen el tamaño del archivo, ideales para menús digitales o avisos rápidos. FLAC ofrece compresión sin pérdida, mientras que WAV y PCM son archivos sin comprimir.

¿Cuántos caracteres caben en una solicitud?

Cada solicitud acepta hasta 4096 caracteres. Si tu texto es más largo, debes dividirlo en partes de este tamaño y unir los archivos de audio resultantes. Los espacios y la puntuación cuentan como caracteres, así que planifica tu contenido para optimizar el uso de tu saldo.

¿Qué significa la velocidad 1.0?

La velocidad 1.0 representa la velocidad natural de la voz. Puedes ajustarla entre 0.25 y 4.0 para hacer la lectura más lenta o rápida. Esto es útil para avisos en comedores o contenido promocional donde necesitas adaptar el ritmo de la voz a la situación específica.

¿Puedo especificar el idioma manualmente?

Sí, puedes usar el campo 'language' con un código ISO para forzar un idioma. Si no lo especificas, la API lo adivina, pero el texto en latín se asume como inglés por defecto. Es recomendable establecerlo explícitamente para textos en español, francés o alemán para evitar errores.

¿Cómo sé si mi solicitud fue exitosa?

La API devuelve el archivo de audio directamente en la respuesta si la síntesis es exitosa. Si falla, no se cobra y recibes un código de error. Puedes verificar el estado mediante los códigos HTTP de la respuesta. Los errores se manejan mediante los códigos HTTP estándar de la API.

Primera solicitud

curl

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

Obtén tu clave API

Ilustración de onda de sonido para: Obtén tu clave API

Accede a tu clave API desde /get-api-key/ registrándote con Google o email. La clave te permite autenticar tus solicitudes al endpoint de síntesis.

Registro con Google o email

Registro con Google o email

El registro crea una cuenta independiente por sitio. Si usas Google, recibes $0.50 de crédito válido por 7 días. Con email, comienzas sin saldo.

Necesitas top-up con USDT (TRC-20) para generar audio tras agotar el saldo.

  • Registro inmediato con Google o email
  • Crédito inicial de $0.50 solo con Google
  • Sin suscripciones ni contratos mensuales

Panel de control y métricas

Panel de control y métricas

La página de tu clave muestra el balance actual, los caracteres restantes y el historial de uso.

Puedes ver métricas básicas como el estado de tu clave y el consumo acumulado.

Generación de nueva clave

Puedes emitir una nueva clave en cualquier momento desde el panel.

La clave anterior deja de funcionar inmediatamente al generar la nueva.

Primera solicitud con cURL

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

Para generar audio, envía una solicitud POST a https://api.kb44.info/v1/audio/speech con el texto y la voz deseados. El cuerpo debe ser un objeto JSON que especifique el modelo, el texto de entrada y el formato de salida deseado.

La autenticación se maneja mediante un token Bearer en la cabecera HTTP. Asegúrate de reemplazar TU_API_KEY con tu clave única generada en el panel de control para validar tu cuenta y deducir el saldo.

Estructura del JSON

El cuerpo de la solicitud requiere los campos model, input, voice y response_format. El campo input contiene el texto a sintetizar, con un límite de 4096 caracteres por petición. El modelo tts-1 o tts-1-hd usa el mismo motor y precio, mientras que voice selecciona entre las 8 opciones disponibles.

Adicionalmente, puedes incluir speed para ajustar la velocidad entre 0.25 y 4.0, y language para forzar un idioma si el texto está en latín pero no es inglés. Si omites el idioma, el sistema intentará adivinarlo, pero especificarlo evita errores en textos como "Gracias por su visita" en español.

  • model: "tts-1" o "tts-1-hd"
  • input: texto máximo 4096 caracteres
  • voice: nombre de la voz (ej. "nova")
  • response_format: "mp3", "wav", "opus", "flac" o "pcm"
  • speed: número entre 0.25 y 4.0 (opcional)
  • language: código ISO (opcional)

Cabecera de autorización

Incluye la cabecera Authorization: Bearer TU_API_KEY en cada solicitud. Esta clave se genera en tu panel de control y se descuenta automáticamente al procesarse una síntesis exitosa. Si la solicitud falla, no se realiza el cargo.

Ejemplo completo listo

Copia y pega este comando en tu terminal, reemplazando la clave y el texto según tu menú o aviso. La respuesta devolverá el archivo de audio binario directamente en la consola o se guardará en un archivo si rediriges la salida.

```bash curl -X POST https://api.kb44.info/v1/audio/speech \ -H "Authorization: Bearer TU_API_KEY" \ -H "Content-Type: application/json" \ -d '{"model": "tts-1", "input": "Bienvenidos a nuestra mesa digital", "voice": "nova", "response_format": "mp3"}' \ -o menu_audio.mp3 ```

Uso con SDK de OpenAI

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

Integra RestoVoice en tus apps de hostelería reutilizando el SDK de OpenAI. Solo necesitas ajustar la URL base para que apunte a nuestro endpoint y usar tu clave API personalizada. Esto te permite aprovechar la familiaridad de las librerías oficiales sin aprender una nueva sintaxis.

Cambio de base_url

Configura tu cliente SDK apuntando a https://api.kb44.info/v1. Este cambio permite que las llamadas estándar al endpoint de audio funcionen directamente con RestoVoice.

Compatibilidad con librerías

El formato de solicitud es idéntico al de la API de OpenAI. Puedes usar las librerías oficiales de OpenAI en Python, Node.js o Go cambiando la base_url.

Configuración sencilla

Define la variable base_url en tu código y autentica con tu clave tts-.... El flujo de generación de audio se mantiene igual, facilitando la migración desde otros proveedores.

Modelos y voces disponibles

Ilustración de onda de sonido para: Modelos y voces disponibles

RestoVoice ofrece dos modelos con el mismo motor de síntesis: tts-1 y tts-1-hd. Ambos generan audio de alta calidad y tienen el mismo precio, por lo que puedes elegir el que mejor se adapte a tu flujo de trabajo sin preocuparte por costos adicionales.

tts-1 y tts-1-hd

El campo model acepta tts-1 o tts-1-hd. Dado que no hay diferencia en el motor ni en el precio, puedes usar cualquiera de los dos para tus menús digitales o avisos en comedores.

8 voces predefinidas

Selecciona entre ocho voces basadas en grabaciones licenciadas de libros audibles de dominio público. Cada voz tiene un carácter distintivo adecuado para diferentes contextos de hostelería.

  • Felix: enérgico y promocional.
  • Milo: amigable y conversacional.
  • Aria: narradora clara y cálida.
  • Luna: suave y narrativa.

Selección por tono

Elige la voz que mejor represente tu marca. Por ejemplo, Atlas para noticias neutras o Orion para un tono documental profundo. Las voces son multilingües y pueden hablar los 23 idiomas soportados.

Formatos de audio soportados

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

La API devuelve audio en cinco formatos estándar: mp3, wav, opus, flac y pcm. Elige el que mejor se adapte a tu infraestructura de menús digitales o sistemas de avisos sin complicaciones técnicas adicionales.

mp3, wav, opus, flac, pcm

Puedes solicitar mp3 para una compresión eficiente, wav para máxima compatibilidad nativa, opus para un equilibrio entre calidad y peso, o flac y pcm si necesitas audio sin pérdidas o datos sin procesar para tu sistema.

  • mp3: compresión ligera, ideal para menús digitales.
  • wav: sin comprimir, alta compatibilidad.
  • opus: eficiente para ancho de banda reducido.
  • flac: sin pérdidas, calidad de estudio.
  • pcm: datos crudos sin codificar.

Elección según necesidad

Para menús digitales en pantallas o avisos en comedores, el mp3 suele ser suficiente por su equilibrio entre peso y calidad. Si tu sistema de voz (PBX) o app requiere archivos sin comprimir, elige wav o pcm.

Calidad y tamaño variables

El tamaño del archivo final depende del formato seleccionado y la duración del audio generado. Los formatos sin pérdidas como flac ocuparán más espacio en tu almacenamiento temporal.

Formatos de audio soportados

Límites y rendimiento

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

Tu clave API tiene un límite de 60 solicitudes por minuto para garantizar un servicio estable. Este umbral es suficiente para la mayoría de los escenarios de hostelería.

60 solicitudes por minuto

Una vez superado este límite, las nuevas peticiones se procesarán según su orden de llegada.

Límite inicial de 10 req/min

Al crear tu cuenta, el límite inicial es de 10 solicitudes por minuto. Este valor aumenta a 60 req/min tras la primera recarga de saldo.

Procesamiento secuencial

Las solicitudes se procesan una tras otra. En textos largos, esto puede generar una cola de espera si hay alta demanda. Para la mayoría de los usos, como avisos breves o lecturas de menú, el tiempo de respuesta es rápido y predecible.

Manejo de errores comunes

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

Los errores son parte del uso normal de la API. Identificarlos rápidamente evita interrupciones en tus menús digitales o avisos de comedor.

Error 401 clave inválida

Indica que tu token no es válido o ha caducado. Verifica que uses el formato Bearer tts-... en la cabecera de autorización.

  • Revisa que no haya espacios extra en la clave.

Error 429 límite excedido

Significa que superaste los 60 requests por minuto (o 10 si es tu primera solicitud). Reduce la frecuencia o espera un momento.

Errores de formato JSON

Si el cuerpo de la solicitud no es JSON válido o falta el campo input, recibirás un error de sintaxis. Asegúrate de que el texto no supere los 4096 caracteres.

Datos y privacidad

Ilustración de onda de sonido para: Datos y privacidad

El texto que envías a la API se utiliza exclusivamente para generar el archivo de audio y no se incorpora a nuestros conjuntos de datos para entrenamiento de modelos. Una vez que recibes el audio en la respuesta, este no se almacena en nuestros servidores.

Texto no usado para entrenamiento

Mantienes el control total sobre tu contenido. Si envías ingredientes especiales o nombres de platos, esa información se procesa en tiempo real y desaparece tras la síntesis, sin quedar registrada para futuros modelos.

Audio no almacenado

El archivo de audio generado se devuelve directamente en la respuesta de la API y no se guarda en nuestra infraestructura. No conservamos copias de tus avisos o menús para uso posterior.

Metadatos para facturación

Guardamos metadatos básicos (hora, número de caracteres y estado) únicamente para calcular tu consumo con precisión y garantizar la facturación correcta. Esta información no se vincula con el contenido del audio generado.

Escucha las 8 voces

Cada muestra a continuación fue generada por esta API a partir de la misma frase.

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. openai-node on GitHub
  3. LibriVox public-domain audiobooks
  4. IETF RFC 7845: Ogg Opus
  5. TRON developer hub: TRC-20
  6. Python documentation
  7. FFmpeg documentation
  8. W3C WAI: making audio and video accessible
  9. Tether (USDT)
  10. OpenAI API reference: create speech
  11. LibriTTS-R corpus (OpenSLR 141)
  12. ISO 639 language codes

Más en este sitio