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.mp3Python (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 | |
|---|---|
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
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
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
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
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
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
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
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.

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
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
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.
23 idiomas
Cualquier voz puede hablar cualquiera de estos idiomas.
