Preguntas frecuentes
¿Qué es una clave Bearer en la API?
Es un token de autorización que envías en el encabezado Authorization: Bearer tts-... para validar tu identidad. Cada cuenta tiene una clave activa; si emites una nueva, la anterior deja de funcionar inmediatamente. Esta clave permite acceder al endpoint de generación de audio y consultar los precios o voces disponibles.
¿Puedo usar el SDK de OpenAI sin modificar el código?
Sí, la API tiene la misma forma de solicitud que el endpoint de speech de OpenAI. Solo necesitas cambiar la base_url a https://api.8155.info/v1 y usar tu clave de VoZeta. Esto permite integrar la tecnología en tus flujos de trabajo actuales sin reescribir la lógica de conexión principal.
¿Qué formato es mejor para menús en pantallas táctiles?
El formato MP3 es la opción más equilibrada para la mayoría de los reproductores web y dispositivos táctiles. También puedes elegir WAV o FLAC para máxima calidad sin pérdida, o OPUS y PCM para otros usos. Elige según la compatibilidad de tu visor de menús digitales y el ancho de banda disponible.
¿Cuántos caracteres puedo enviar en una sola petición?
Cada petición puede contener hasta 4096 caracteres de texto. Si tu menú o aviso es más largo, debes dividirlo en partes de este tamaño. La API no une las partes automáticamente; tú debes recibir los archivos de audio resultantes y unirlos en tu aplicación para reproducir el contenido completo.
¿Qué voces son mejores para anuncios de comida?
Para promociones, Felix es ideal por su tono enérgico. Para menús generales o descripciones, Aria ofrece una narración clara y cálida, mientras que Milo resulta amigable y conversacional. Atlas es neutro para avisos informativos, y Orion aporta seriedad para documentales gastronómicos. Elige según si buscas dinamismo o claridad informativa.
¿Cómo detecta la API el idioma del texto?
La API intenta adivinar el idioma basándose en el script del texto. Por defecto, el texto en latín se interpreta como inglés. Si envías texto en español, francés o alemán en latín, debes especificar el código ISO en el campo language para asegurar una pronunciación correcta y evitar errores de acentuación.
¿Es necesario especificar el idioma siempre?
No es obligatorio, pero es recomendable para textos en latinos distintos al inglés. Si no se establece, el sistema asumirá inglés para texto en latín. Para garantizar la precisión en español, árabe o japonés, indica explícitamente el código ISO del idioma en la solicitud para evitar interpretaciones incorrectas.
¿Qué pasa si el texto supera los 4096 caracteres?
Debes dividir el texto en fragmentos de máximo 4096 caracteres y enviar cada uno como una petición separada. La API devuelve un archivo de audio por cada fragmento. Tú eres responsable de unir estos archivos en tu aplicación para que el cliente escuche el mensaje completo sin interrupciones.
¿Se pueden combinar voces en un solo archivo?
No, la API genera un archivo de audio por cada petición enviada. No hay una función nativa para mezclar voces o unir pistas dentro del servicio. Debes gestionar la concatenación de los archivos resultantes desde tu lado, utilizando tu propia lógica de programación o herramientas de audio externas.
¿Cuánto tarda en generarse un audio largo?
La generación es aproximadamente en tiempo real, lo que equivale a unos 25 caracteres por segundo. Para textos largos, el tiempo total depende de la longitud del texto más cualquier espera en la cola si hay carga. Las peticiones se procesan secuencialmente, por lo que la espera puede aumentar bajo demanda.
¿Qué significa el código de error 429?
Indica que has excedido el límite de velocidad: 60 solicitudes por minuto por clave. Si es tu primera top-up, el límite es de 10 por minuto. Debes esperar a que el contador se reinicie o reducir la frecuencia de tus peticiones. Las peticiones fallidas son gratuitas.
¿Puedo cambiar la velocidad de la voz?
Sí, puedes ajustar la velocidad entre 0.25 y 4.0 mediante el campo speed. Esto permite acelerar avisos rápidos o ralentizar la lectura para mayor claridad en menús complejos. Ajustar la velocidad no afecta al precio, que se calcula únicamente por el número de caracteres procesados en la entrada.
¿Las voces tienen variaciones de entonación?
Las voces son preestablecidas con características fijas: Aria es cálida, Nova es brillante, Luna es suave, Sage es calmada, Felix es enérgica, Milo es amigable, Atlas es neutra y Orion es profunda. No hay etiquetas de emoción ni personalización de entonación. Cada archivo lleva una marca de agua sintética invisible.
¿Cómo se autentica la petición correctamente?
Debes incluir el encabezado Authorization: Bearer tts-... con tu clave única en cada solicitud POST. La clave se obtiene al registrarte en /get-api-key/. Asegúrate de que la clave esté activa y no haya sido reemplacada recientemente. Sin este encabezado, la API rechazará la petición con un error de autenticación.
Primera solicitud
curl
curl https://api.8155.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.8155.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.8155.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 utilizar la API de texto a voz, accede a /get-api-key/ y regístrate con Google o correo electrónico. La creación de cuenta es el primer paso para obtener las credenciales necesarias y visualizar el saldo disponible.
Una vez registrado, puedes generar tu clave Bearer desde el panel de control. Esta clave autenticará tus solicitudes al endpoint de la API y permitirá el uso de los servicios de síntesis de voz.
Registro en la cuenta
Accede a /get-api-key/ y elige registrarte con Google o correo electrónico. Las cuentas son independientes por sitio y el registro es inmediato.
Generación de clave Bearer
Desde tu panel, genera una clave Bearer única. Esta credencial se envía en el encabezado Authorization para autenticar cada solicitud de síntesis.
Gestión de claves activas
Puedes emitir una nueva clave en cualquier momento. Al hacerlo, la clave anterior deja de funcionar inmediatamente, garantizando un control estricto del acceso.
- Una clave activa por cuenta
- Invalidación instantánea al rotar
Primera petición con Curl
La interacción con la API de VoZeta Editorial se realiza mediante peticiones HTTP POST que aceptan texto y devuelven audio sintetizado. El formato de entrada es JSON, diseñado para ser compatible con las librerías estándar de desarrollo.
Este enfoque permite a las agencias integrar la síntesis de voz directamente en sus flujos de trabajo para menús digitales o avisos en comedores colectivos sin depender de formatos propietarios.
Estructura JSON
El cuerpo de la petición debe contener un objeto JSON con los campos necesarios para la síntesis. Cada solicitud debe especificar el modelo de voz, el texto a convertir y el formato de salida deseado.
- El campo
inputacepta hasta 4096 caracteres por petición. - Se requiere autenticación mediante un token Bearer en el encabezado.
- Los caracteres incluyen espacios y puntuación para el cálculo de saldo.
Endpoint POST
Las peticiones se envían al endpoint POST https://api.8155.info/v1/audio/speech. Este es el único punto de entrada necesario para generar archivos de audio a partir de texto plano.
La respuesta devuelve el archivo de audio directamente, listo para ser reproducido en dispositivos móviles o pantallas de hostelería.
Parámetros básicos
Los parámetros esenciales incluyen model ("tts-1" o "tts-1-hd"), voice (selección entre las 8 presets disponibles) y input (el texto a sintetizar).
Es posible ajustar la speed entre 0.25 y 4.0 para adaptar la voz a la velocidad de lectura en menús digitales.
El campo language es opcional; si no se indica, el sistema detecta el idioma automáticamente, aunque se recomienda especificarlo para textos en latín no ingleses.
- Formatos soportados: mp3, wav, opus, flac, pcm.
Uso con SDK de OpenAI
La API de texto a voz sigue el mismo esquema de peticiones que el endpoint de speech de OpenAI, lo que permite reutilizar las bibliotecas oficiales sin adaptar la lógica de negocio. Solo es necesario ajustar la URL base de la conexión.
Esta compatibilidad facilita la integración en flujos existentes de agencias que ya gestionan contenido digital para hostelería, permitiendo generar audios para menús y avisos con la misma estructura de código que estarían usando para otros servicios de IA.
Los desarrolladores pueden aprovechar las bibliotecas oficiales de OpenAI, modificando únicamente la configuración de la URL base hacia el endpoint de VoZeta Editorial. Esto elimina la necesidad de crear un cliente HTTP personalizado desde cero para la autenticación y serialización del cuerpo de la solicitud.
Cambio de base_url
Para utilizar el SDK de OpenAI con nuestra API, configura la variable base_url apuntando a https://api.8155.info/v1. Esto dirige las peticiones al endpoint correcto mientras mantiene la compatibilidad con la estructura JSON estándar de POST /v1/audio/speech.
La clave API se pasa en el encabezado Authorization: Bearer <tu-clave>, exactamente como se haría con el servicio original de OpenAI. No requiere cambios en la lógica de autenticación ni en la gestión de sesiones.
- URL base: https://api.8155.info/v1
- Encabezado de autenticación: Bearer <tue-clave>
- Formato de solicitud: JSON estándar
Compatibilidad completa
El SDK interpreta correctamente los campos model, input, voice y response_format tal como los define la especificación de speech. Soporta los modelos tts-1 y tts-1-hd con la misma engine y precio, permitiendo elegir entre calidad estándar y alta definición.
Las respuestas devuelven el archivo de audio binario directamente, lo que simplifica el almacenamiento o la reproducción inmediata en aplicaciones web o móviles para menús digitales.
No es necesario gestionar conversiones de formato adicionales si se solicita MP3, WAV, OPUS o FLAC, ya que el servicio devuelve el archivo ya codificado en el formato solicitado.
- Soporta modelos tts-1 y tts-1-hd
- Respuesta binaria directa
- Formatos: MP3, WAV, OPUS, FLAC
Ejemplo en Python
El siguiente código muestra cómo inicializar el cliente y generar audio para un aviso de menú. Asegúrate de tener instalado el paquete openai y configurar la variable de entorno OPENAI_BASE_URL o pasarla directamente al cliente.
Este ejemplo utiliza la voz nova para un tono alegre, ideal para promociones o avisos de disponibilidad. El texto se limita a 4096 caracteres por petición, lo que cubde la mayoría de los menús o descripciones de platos.
El archivo resultante se guarda localmente o puede enviarse directamente al cliente; la API no ofrece streaming en tiempo real durante la generación.
- Instalar: pip install openai
- Configurar base_url: https://api.8155.info/v1
- Enviar texto con voz 'nova'
Formatos de audio disponibles
La API devuelve el audio en formatos estándar para garantizar compatibilidad inmediata con cualquier reproductor de hostelería o sistema de menús digitales. La elección del formato depende del balance entre calidad, peso del archivo y la infraestructura de reproducción de cada cliente.
Todos los formatos se generan bajo demanda y se entregan en la respuesta de la petición sin almacenamiento adicional, lo que simplifica la integración técnica para agencias que gestionan múltiples locales.
MP3 para web
El formato MP3 es la opción por defecto y la más eficiente para la mayoría de las aplicaciones web y menús digitales. Ofrece una relación óptima entre calidad de sonido y tamaño de archivo, lo que facilita la carga rápida en dispositivos móviles y pantallas táctiles de restaurantes.
- Compatible con todos los navegadores modernos y reproductores HTML5.
- Tamaño de archivo reducido para ahorra ancho de banda.
WAV para alta calidad
El formato WAV ofrece audio sin pérdida, ideal para sistemas de avisos internos o altavoces de alta fidelidad en comedores colectivos. Aunque el tamaño del archivo es mayor que el MP3, garantiza la máxima claridad en la reproducción de la voz para anuncios de platos o alérgenos.
- Calidad sin pérdida (lossless).
- Ideal para playback en alta fidelidad.
FLAC y OPUS
FLAC es un formato comprimido sin pérdida, mientras que OPUS es un formato con pérdida eficiente, útiles para archivar o transmitir audio con alta relación de compresión. FLAC mantiene la calidad original del WAV con un tamaño menor, mientras que OPUS es excelente para entornos con limitaciones de ancho de banda.
- FLAC: compresión sin pérdida.
- OPUS: alta eficiencia para streaming o almacenamiento.
Voces y idiomas soportados
La API ofrece ocho voces predefinidas con timbres distintos, desde la narradora clara de Aria hasta el tono documental de Orion. Cada voz puede pronunciar cualquiera de los 23 idiomas soportados sin cambiar de motor.
El audio generado incluye una marca de agua inaudible que certifica su origen sintético. Las voces están basadas en grabaciones con licencia (LibriTTS-R, CC BY 4.0) y lecturas de dominio público (LibriVox).
Lista de 8 voces
Las voces están categorizadas por tono y uso editorial. Las femeninas incluyen Aria (narradora), Nova (alegre), Luna (historias) y Sage (instruccional). Las masculinas son Felix (promo), Milo (conversacional), Atlas (noticias) y Orion (documental).
23 idiomas disponibles
Soportamos árabe, chino, danés, holandés, inglés, finés, francés, alemán, griego, hebreo, hindi, italiano, japonés, coreano, malayo, noruego, polaco, portugués, ruso, español, suajili, sueco y turco. Cualquier voz puede usar cualquiera de estos idiomas.
Detección automática
Si no especificas el idioma, la API lo detecta por el guion. El texto en latino por defecto asume inglés. Para otros idiomas latinos, establece el parámetro language explícitamente.

Límites y rendimiento
Para agencias que gestionan menús digitales de alta rotación, entender los límites es clave para evitar interrupciones en la generación de avisos de platos o promociones. La API está diseñada para flujos de trabajo batch, permitiendo una planificación eficiente de la carga de audio sin sorpresas inesperas.
60 peticiones por minuto
Cada clave API tiene un límite de 60 peticiones por minuto. Este umbral es suficiente para actualizar menús diarios o generar avisos de comida en comedores colectivos sin saturar el servicio. Antes de la primera recarga, el límite es de 10 peticiones por minuto.
4096 caracteres por petición
Cada solicitud acepta un máximo de 4096 caracteres. Para menús extensos con descripciones detalladas de ingredientes y alérgenos, es necesario dividir el texto en fragmentos. La agencia debe concatenar los archivos de audio resultantes para crear el audio final coherente.
Velocidad de generación
La generación es aproximadamente en tiempo real (25 caracteres por segundo). Las frases cortas tardan unos segundos, pero bajo carga las peticiones se procesan en cola secuencialmente. Planifique las actualizaciones de menús en momentos de baja concurrencia para reducir tiempos de espera.
Manejo de errores
La API devuelve códigos de estado HTTP estandarizados para indicar el resultado de cada síntesis. Un error en la petición (4xx) suele deberse a un formato JSON incorrecto, un modelo inexistente o un límite de caracteres superado. Las respuestas 5xx son infrecuentes y pueden deberse a una carga temporal del servicio.
Es fundamental verificar el campo status en la respuesta. Si la síntesis falla, no se consume saldo. Los errores de red temporales deben gestionarse con reintentos exponenciales simples, evitando saturar el límite de 60 peticiones por minuto.
Códigos de estado HTTP
Utilizamos estándares REST claros. El estado 200 indica éxito con el audio en el cuerpo. El 400 señala parámetros inválidos, como un voice desconocido o texto vacío. El 429 se activa si excedes los 60 requests/minuto. El 402 indica saldo insuficiente.
Para menús digitales, un error 400 es crítico porque impide la carga del aviso. Verifica siempre la estructura del JSON antes de enviarlo, especialmente si generas audio desde bases de datos dinámicas de restaurantes.
- 200: Éxito, audio disponible.
- 400: Parámetros inválidos.
- 402: Saldo insuficiente.
- 429: Límite de velocidad excedido.
- 500: Error interno del servicio.
Reintento de peticiones
Implementa una lógica de reintento con backoff exponencial para errores temporales (429 o 5xx). Espera entre 1 y 2 segundos antes del primer reintento. No reintentes errores de cliente (400, 402), ya que persistirán hasta que corrijas los datos o recargues el saldo.
Dado que las peticiones se procesan en cola, un pico de demanda puede aumentar la latencia. Un tiempo de espera (timeout) de al menos 30 segundos es recomendable para evitar rupturas en la experiencia del usuario final.
Gestión de saldo
Si la síntesis falla, el cargo se devuelve íntegramente. Se facturan los caracteres de las peticiones exitosas. Revisa tu panel en /get-api-key/ para monitorizar el consumo en tiempo real.
Asegúrate de tener saldo antes de lanzar campañas masivas de avisos. El saldo no expira, pero la cuenta debe tener fondos válidos para evitar interrupciones en la generación de audio.
Ejemplo de integración para menús
Este ejemplo ilustra cómo generar audio para menús digitales en comedores colectivos. Se combina un texto descriptivo del plato principal con una instrucción clara sobre alérgenos, optimizando la experiencia del usuario sin saturar la memoria del dispositivo.
Texto de plato principal
El texto debe ser conciso. Ejemplo: "Lentejas estofadas con chorizo, acompañadas de arroz blanco y ensalada verde. Plato caliente." Este texto se envía mediante la API con la voz "sage" para un tono instruccional y calmado.
Alérgenos y voz
Se añade una segunda petición corta para los alérgenos: "Contiene gluten, soja y sésamo." Se utiliza la voz "nova" para mayor claridad y alerta. Cada petición debe respetar el límite de 4096 caracteres.
- Voz: nova (bright, upbeat)
- Texto: "Contiene gluten, soja y sésamo."
Respuesta de audio
La API devuelve archivos MP3 o WAV listos para integrarse en el menú digital. El tiempo de generación es cercano al tiempo real, permitiendo una carga rápida en pantallas de hostelería.
Escucha las 8 voces
Cada muestra a continuación fue generada por esta API a partir de la misma frase. Se utiliza para descripciones de maridajes, historias de la marca o presentaciones de alta gama donde se busca transmitir distinción y calma.
23 idiomas
Cualquier voz puede hablar cualquiera de estos idiomas.
