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

Por Equipo editorial de ComedorDigital · Actualizado 2026-11-18

Esta documentación técnica explica cómo integrar nuestra API de texto a voz en los sistemas de gestión de comedores colectivos. Aquí encontrarás la referencia completa de los endpoints, los parámetros de configuración y los formatos de audio soportados, diseñada para desarrolladores que necesitan convertir menús o comunicados internos en audio claro y multilingüe para grandes equipos.

La guía detalla el proceso de autenticación con claves API, el uso del SDK de OpenAI modificando la URL base y los límites de rendimiento esperados. Se incluyen ejemplos prácticos con cURL y explicaciones sobre el manejo de errores, el formato de las respuestas y las restricciones de caracteres, asegurando una implementación precisa y eficiente en entornos de alta demanda.

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

Preguntas frecuentes

¿Qué modelo debo usar: tts-1 o tts-1-hd?

Ambos modelos utilizan el mismo motor de síntesis y tienen el mismo precio. La diferencia es la calidad de audio. Para la mayoría de los casos de uso, como menús o comunicados, tts-1 es suficiente y eficiente.

¿Cuántos caracteres máximos puedo enviar?

Puedes enviar hasta 4096 caracteres por solicitud. 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 dentro de este límite.

¿Qué formato de audio es más eficiente?

El formato mp3 es generalmente el más eficiente en términos de tamaño de archivo y compatibilidad. También puedes elegir wav, opus, flac o pcm según tus necesidades de calidad o procesamiento posterior. El formato no afecta el precio ni la velocidad.

¿Cómo cambio la velocidad del audio?

Ajusta el parámetro speed en tu solicitud JSON. El valor debe estar entre 0.25 y 4.0. Un valor de 1.0 es la velocidad normal. Puedes acelerar o ralentizar la voz para adaptarla al ritmo de tu comunicación o menú.

¿Puedo usar la SDK de OpenAI directamente?

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.play7wg.com/v1 y usar tu clave de API. Las SDKs oficiales de OpenAI funcionarán sin modificaciones adicionales.

¿Qué hace la cabecera Authorization?

La cabecera Authorization: Bearer tts-... autentica tu solicitud usando tu clave API única. Cada cuenta tiene una clave activa. Si emites una nueva clave, la anterior deja de funcionar inmediatamente. Es esencial para que la API reconozca tu cuenta y cargue el saldo.

¿Qué pasa si supero el límite de solicitudes?

El límite es de 60 solicitudes por minuto por clave (o 10 antes del primer recargo). Si excedes este límite, tus solicitudes comenzarán a fallar. No se te cobrará por las solicitudes que fallen debido a estos límites o errores de servidor.

¿Es compatible con Python y Node.js?

Sí, al ser compatible con el formato de solicitud de OpenAI, puedes usar las SDKs oficiales de Python y Node.js de OpenAI. Solo necesitas configurar la URL base correctamente. También puedes realizar solicitudes HTTP directas sin necesidad de una SDK específica de ComedorDigital.

¿Cómo especifico el idioma del texto?

Incluye el código ISO del idioma en el campo language de tu solicitud JSON. Si no lo especificas, el sistema intentará adivinar el idioma basándose en el script, asumiendo inglés para texto en latín. Es recomendable establecerlo explícitamente para textos en otros idiomas.

¿Qué ocurre si el servidor está ocupado?

Las solicitudes se procesan en orden secuencial. Si hay mucha carga, tu solicitud puede esperar en una cola antes de generarse. Esto puede aumentar el tiempo de respuesta, especialmente para textos largos. El procesamiento continúa hasta que se complete la síntesis o haya un error.

¿Puedo enviar texto en varios idiomas a la vez?

Sí, puedes mezclar idiomas en un solo texto de hasta 4096 caracteres. La API detectará los cambios de idioma o usará el campo language si está definido. Esto es útil para comunicados multilingües en comedores colectivos con personal de diversas nacionalidades.

¿Cómo detecto errores en la respuesta?

La API devolverá códigos de estado HTTP estándar y un cuerpo de error JSON si ocurre una falla. Las solicitudes fallidas no se cobran. Revisa los encabezados de respuesta y el código de estado para identificar el tipo de error.

¿Se devuelve el audio en el cuerpo de la respuesta?

Sí, el archivo de audio generado se devuelve directamente en el cuerpo de la respuesta HTTP. No se almacena; solo se devuelve en la respuesta inmediata. Esto permite guardar el audio localmente o reproducirlo directamente en tu aplicación.

¿Cuántas voces diferentes puedo usar en una cuenta?

Puedes elegir entre 8 voces preestablecidas disponibles en la API. Puedes usar cualquiera de ellas en tus solicitudes, cambiando el campo voice. No hay límite en el número de voces que puedes alternar, solo en la cantidad de solicitudes por minuto.

Primera solicitud

curl

curl https://api.play7wg.com/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.play7wg.com/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.play7wg.com/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 /get-api-key/ para registrar tu cuenta mediante Google o correo electrónico. Esta acción genera una clave única que autenticará todas tus solicitudes API.

El panel muestra la clave activa, el saldo disponible y ejemplos listos para usar. Gestiona tus credenciales directamente desde esta interfaz centralizada.

Registro con Google o email

Registro con Google o email

El registro ofrece dos vías: Google (incluye $0.50 de prueba válida por 7 días) o email con contraseña (sin crédito inicial). Cada sitio opera cuentas independientes.

Ubicación de la clave en el panel

Ubicación de la clave en el panel

La clave aparece en la página /get-api-key/, junto al saldo y el uso actual. Es el identificador tts-... necesario en el header Authorization.

Emisión de nueva clave y revocación

Puedes emitir una nueva clave en cualquier momento desde el panel. La clave anterior se revoca inmediatamente, evitando accesos no deseados sin esperar al cierre de sesión.

Primera solicitud con cURL

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

Para comenzar a generar audio, utiliza curl para enviar una solicitud POST al endpoint https://api.play7wg.com/v1/audio/speech. El servicio acepta texto plano y devuelve el archivo de audio resultante, ideal para integrar en sistemas de comunicación interna de comedores colectivos.

Este método directo permite probar la integración sin dependencias externas, verificando que la configuración de autenticación y los parámetros de voz funcionen correctamente antes de escalar a volúmenes mayores.

Ejemplo completo de comando POST

Envía la solicitud especificando la clave API en la cabecera Authorization. Reemplaza TU_API_KEY con tu credencial real y ajusta los parámetros según el texto y la voz deseados para el menú o aviso.

El comando debe apuntar a la URL correcta del endpoint de síntesis, asegurando que el formato de la solicitud sea JSON válido para el procesamiento inmediato.

  • Método: POST
  • URL: https://api.play7wg.com/v1/audio/speech
  • Cabecera: Authorization: Bearer TU_API_KEY
  • Content-Type: application/json

Cuerpo JSON con parámetros requeridos

El cuerpo de la solicitud debe incluir el campo model, eligiendo entre tts-1 o tts-1-hd para el mismo motor de voz. El parámetro input contiene el texto a convertir, con un límite de 4096 caracteres por solicitud.

Especifica la voice entre las 8 opciones disponibles (como nova o atlas) y el response_format deseado (mp3, wav, etc.). El idioma es opcional; si no se indica, el sistema intenta detectarlo, pero es recomendable definirlo explícitamente para textos en lenguas minoritarias.

  • model: "tts-1" o "tts-1-hd"
  • input: texto hasta 4096 caracteres
  • voice: nombre de la voz (ej. "nova")
  • response_format: "mp3", "wav", "opus", "flac", "pcm"

Recibida respuesta con archivo de audio

Una solicitud exitosa devuelve el archivo de audio binario directamente en la respuesta HTTP. No se requiere un paso adicional para descargar el contenido, ya que el cuerpo de la respuesta contiene los datos del audio generado.

Si la síntesis falla, la carga se devuelve completamente, asegurando que no se cobre el crédito. Para textos más largos, deberás dividirlos en fragmentos menores a 4096 caracteres y unir los archivos resultantes posteriormente.

Uso con SDK de OpenAI

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

Si ya utilizas el SDK oficial de OpenAI en Python o Node.js, puedes integrar nuestra API de texto a voz modificando la URL base a https://api.play7wg.com/v1. Esto permite aprovechar la misma estructura de llamadas sin necesidad de aprender una nueva librería desde cero.

Cambio del base_url a la API

Dirige el cliente a https://api.play7wg.com/v1 en lugar del endpoint original de OpenAI. Esta ruta conserva la misma forma de solicitud JSON, lo que garantiza que las librerías oficiales funcionen sin modificaciones profundas en la lógica de tu aplicación.

Este ajuste es suficiente para que las llamadas al endpoint /v1/audio/speech se procesen correctamente a través de nuestro servidor, manteniendo la simplicidad de integración.

  • URL base: https://api.play7wg.com/v1
  • Mismo formato JSON que OpenAI

Configuración de la clave en header

Incluye tu clave API en la cabecera de autenticación usando el formato Bearer tts-.... Esta clave se obtiene al registrarte en la página de obtención de claves del panel.

Asegúrate de que la clave esté activa y asociada a tu cuenta para que las solicitudes sean validadas correctamente contra nuestros límites de tasa.

  • Header: Authorization: Bearer tts-...
  • Una clave activa por cuenta

Compatibilidad con métodos estándar

Los métodos estándar de generación de audio funcionan igual que en el ecosistema de OpenAI. Puedes especificar el modelo, la voz, el formato de salida y la velocidad de reproducción directamente en el cuerpo de la solicitud.

Esta familiaridad reduce la curva de aprendizaje para los desarrolladores que ya conocen la API de speech, permitiendo centrarse en la lógica de negocio del restaurante o comedor.

  • Método POST estándar
  • Parámetros compatibles

Parámetros de la solicitud

Ilustración de onda de sonido para: Parámetros de la solicitud

Los parámetros de entrada definen cómo se procesa el texto y se genera el audio. La configuración básica requiere especificar el modelo, la voz y el texto a sintetizar.

La API acepta caracteres en cualquier idioma soportado, limitando la entrada a 4096 caracteres por solicitud para garantizar la coherencia del audio generado.

Modelo: tts-1 o tts-1-hd

Ambos modelos utilizan el mismo motor de síntesis y tienen el mismo precio. La diferencia radica únicamente en la calidad de audio, siendo "tts-1-hd" la opción de mayor fidelidad.

Voz: selección entre 8 presets

Elige entre ocho voces predefinidas, cada una con un tono distintivo adaptado a diferentes contextos de comunicación interna o menús.

Las voces femeninas incluyen aria (narradora clara), nova (alegre), luna (suave) y sage (instruccional). Las masculinas son felix (enérgico), milo (conversacional), atlas (neutral) y orion (documental).

  • Femeninas: aria, nova, luna, sage
  • Masculinas: felix, milo, atlas, orion

Idioma: código ISO opcional

Puedes especificar el idioma mediante su código ISO de dos letras. Si no se indica, el sistema intenta adivinarlo basándose en el guion del texto (el texto latino por defecto es inglés).

  • Español: es
  • Inglés: en
  • Francés: fr
  • Alemán: de
  • Chino: zh
  • Japonés: ja

Formatos de audio soportados

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

La API devuelve el audio generado en el formato especificado por el campo response_format. La elección depende del equilibrio entre compatibilidad, tamaño de archivo y calidad requerida para la reproducción en los comedores.

MP3 para compatibilidad general

Es el formato predeterminado y más utilizado. Ofrece un equilibrio óptimo entre la calidad de audio y el tamaño del archivo, asegurando una reproducción fluida en la mayoría de los reproductores y sistemas de megafonía utilizados en grandes equipos.

WAV para alta calidad sin pérdida

Genera archivos de audio sin compresión, ideales para archivado o integración en sistemas que requieren máxima fidelidad. El tamaño de archivo es considerablemente mayor que el de MP3, por lo que debe usarse solo cuando la calidad sin pérdidas sea crítica.

OPUS, FLAC y PCM para uso específico

OPUS y FLAC ofrecen compresión eficiente con alta calidad, útiles para entornos con ancho de banda limitado o necesidad de compresión sin pérdida. PCM proporciona audio crudo sin compresión, adecuado para procesamiento inmediato o grabaciones de referencia.

Formatos de audio soportados

Límites y rendimiento

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

La API impone un límite estricto de 4096 caracteres por solicitud, lo que requiere dividir menús extensos o comunicados internos en partes para garantizar la entrega completa del audio.

El procesamiento es secuencial, lo que significa que las solicitudes se ejecutan una tras otra sin paralelismo inmediato.

Máximo 4096 caracteres por solicitud

Cada llamada POST debe contener un texto de entrada inferior a 4096 caracteres. Si el menú del día o la instrucción operativa supera este límite, es necesario fragmentar el texto y unir los archivos de audio resultantes para obtener el mensaje completo.

Límite de 60 solicitudes por minuto

Se permiten hasta 60 solicitudes por minuto por clave activa. Este límite asegura la estabilidad del servicio durante la generación simultánea de audios para varios turnos o comedores.

Antes de la primera recarga, el límite se reduce a 10 solicitudes por minuto.

Procesamiento secuencial bajo carga

Las peticiones se procesan en cola secuencial. Durante picos de uso, una solicitud puede esperar a que finalice la anterior, lo que puede extender ligeramente el tiempo total de generación para textos largos.

La velocidad típica es de aproximadamente 25 caracteres por segundo de audio generado.

Manejo de errores

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

La API devuelve códigos de estado HTTP estandarizados para indicar el resultado de cada solicitud. Un 200 indica éxito y la entrega del archivo de audio, mientras que los códigos 4xx señalan errores de cliente, como una clave inválida o exceder el límite de caracteres.

En estos casos, la solicitud no se cobra si la síntesis falla completamente, garantizando que solo se facture el trabajo exitoso.

Códigos de estado HTTP comunes

El sistema devuelve 200 para respuestas exitosas. Los errores de autenticación o parámetros devuelven 400 o 401. Si el límite de 60 solicitudes por minuto se excede, se recibe un 429. Los errores internos del servidor generan un 500.

Es fundamental verificar el código de estado antes de intentar parsear la respuesta binaria. Un error 401 indica que la clave API es incorrecta o ha sido revocada, mientras que un 429 sugiere esperar antes de reintentar.

  • 200: Éxito, audio generado correctamente.
  • 400: Parámetros inválidos o texto demasiado largo.
  • 401: Clave API incorrecta o expirada.
  • 429: Límite de tasa excedido (60 req/min).

Mensajes de error descriptivos

Esto facilita la depuración rápida sin necesidad de consultar documentación externa.

Los mensajes son claros y concisos, indicando exactamente qué campo requiere corrección. Por ejemplo, si se supera el límite de 4096 caracteres, se indica en el cuerpo de la respuesta de error.

Reintento automático recomendado

Se recomienda implementar un reintento con retroceso exponencial para errores 429 y 5xx. Dado que las solicitudes se procesan secuencialmente, la cola puede acumularse durante picos de uso.

Los errores de red temporales suelen resolverse con un reintento simple. Los errores de parámetros (4xx) no requieren reintento inmediato, ya que persistirán hasta que se corrija la solicitud.

Autenticación y seguridad

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

La seguridad de la API se basa en una clave única que autentica cada solicitud. Esta clave se genera al registrarse y se gestiona desde el panel de control de la cuenta.

El mecanismo de autenticación es estándar y requiere incluir la cabecera adecuada en cada petición HTTP para garantizar que el uso de caracteres se impute correctamente a tu cuenta.

Cabecera Authorization Bearer

Incluye la cabecera Authorization: Bearer tts-... en el encabezado HTTP de cada solicitud POST. Sin esta cabecera, la API rechazará la petición con un error de autenticación.

Formato de la clave tts-...

Las claves comienzan siempre por el prefijo tts- seguido de caracteres alfanuméricos. Se pueden emitir nuevas claves en cualquier momento desde el panel, revocando la anterior inmediatamente.

Una clave activa por cuenta

Cada cuenta mantiene una única clave activa válida. Al emitir una nueva, la anterior deja de funcionar al instante, lo que facilita la gestión de seguridad en equipos de cocina o administración.

Escucha las 8 voces

Cada muestra a continuación fue generada por esta API a partir de la misma frase. La gestión eficiente del personal y los proveedores optimiza la experiencia del cliente en nuestro sistema de restauración colectiva.

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. Python documentation
  3. curl documentation
  4. Node.js documentation
  5. IETF RFC 7845: Ogg Opus
  6. openai-python on GitHub
  7. FFmpeg documentation
  8. openai-node on GitHub
  9. MDN: Web Speech API
  10. LibriTTS-R corpus (OpenSLR 141)
  11. LibriVox public-domain audiobooks
  12. OpenAI API reference: create speech

Más en este sitio