Preguntas frecuentes
¿Qué es una API de texto a voz?
Es un servicio en la nube que convierte texto en archivos de audio. Envías un texto y recibes el audio generado. Está diseñada para convertir menús, instrucciones y comunicados internos en audio claro y multilingüe para grandes equipos de restaurantes y comedores colectivos.
¿Cómo se envía el texto a la API?
Se envía mediante una solicitud POST al endpoint /v1/audio/speech. El cuerpo de la solicitud debe ser en formato JSON e incluir el texto (input), el modelo, la voz, el formato de respuesta y la clave de autorización en el encabezado.
¿Qué formato tiene la respuesta?
La respuesta contiene el archivo de audio generado. Puedes solicitar los formatos mp3, wav, opus, flac o pcm. El audio se devuelve directamente en la respuesta de la solicitud HTTP, listo para su reproducción o almacenamiento.
¿Puedo usar la API desde cualquier programa?
Sí, la API funciona mediante HTTP estándar. Puedes usarla desde cualquier lenguaje o entorno que pueda enviar solicitudes HTTP POST y recibir respuestas, sin necesidad de un SDK propietario. Las SDKs oficiales de OpenAI también son compatibles cambiando la base_url.
¿Qué significa base_url en la integración?
Es la dirección base de la API. Para usar las SDKs de OpenAI, debes cambiar la base_url a https://api.play7wg.com/v1. Esto permite que las librerías existentes funcionen con nuestra API simplemente ajustando esta configuración de conexión.
¿Es necesario programar para usar la API?
No es estrictamente necesario, pero es lo habitual. Puedes usar herramientas como cURL o Postman para enviar solicitudes manualmente. Sin embargo, para integrarla en aplicaciones o flujos de trabajo automáticos en comedores, se requiere algún nivel de programación.
¿Cómo funciona la detección de idioma?
Si no especificas el idioma, la API lo adivina según el guion (por ejemplo, texto en latín se asume inglés). Para textos en otros idiomas con caracteres latinos, debes establecer el campo 'language' explícitamente para asegurar la pronunciación correcta.
¿Qué pasa si el texto tiene más de 4096 caracteres?
Debes dividir el texto en partes de hasta 4096 caracteres y enviar cada parte en una solicitud separada. Luego, debes unir los archivos de audio generados para obtener el audio completo del texto original.
¿Se puede ajustar la velocidad del habla?
Sí, puedes ajustar la velocidad entre 0.25 y 4.0. Esto permite acelerar o ralentizar la voz para adaptarla a diferentes contextos, como instrucciones rápidas en cocina o narraciones más pausadas para menús.
¿Qué es una voz preset?
Son ocho voces predefinidas con características distintas, como 'aria' (narradora clara) o 'felix' (energética). Son grabaciones con licencia o de dominio público. Cada voz puede hablar cualquier idioma soportado sin necesidad de configuración adicional.
¿Cuántas solicitudes puedo hacer simultáneamente?
Las solicitudes se procesan una tras otra. Si hay carga, una solicitud puede esperar en cola. El límite es de 60 solicitudes por minuto por clave, lo que permite generar audio de forma continua para comunicados internos.
¿La API funciona en tiempo real?
No es streaming ni tiempo real estricto. La generación tarda aproximadamente un segundo por cada 25 caracteres. Para textos largos, el tiempo total es similar a la duración del audio, pero las solicitudes se encolan bajo carga.
¿Qué es el rate limit de 60 solicitudes?
Es el límite de 60 solicitudes por minuto por clave de API. Antes de la primera recarga, el límite es de 10 solicitudes por minuto. Si excedes el límite, las solicitudes adicionales pueden tardar más o fallar.
¿Cómo sé que la solicitud fue exitosa?
Una solicitud exitosa devuelve el archivo de audio en la respuesta HTTP. Si la síntesis falla, la carga se devuelve íntegramente. Puedes verificar el estado de la solicitud mediante el código de respuesta HTTP y los encabezados.
Solicitud y respuesta
La integración comienza con una solicitud POST al endpoint /v1/audio/speech. Se envía el texto del menú o aviso en formato JSON, especificando el modelo (tts-1 o tts-1-hd) y la voz deseada. Este formato es compatible con los SDKs oficiales de OpenAI ajustando la URL base.
Envío de texto en formato JSON
La estructura de la petición es idéntica a la de OpenAI. Debes incluir la clave de API en el encabezado Authorization y definir el campo input con el texto a sintetizar, como el nombre de un plato o una instrucción de servicio.
- Método: POST
- Endpoint: /v1/audio/speech
- Cuerpo: JSON con campos model, input, voice
Procesamiento en el servidor
El servidor recibe la solicitud y verifica la autenticación y el saldo disponible. El motor de síntesis genera el audio en tiempo real, aplicando la velocidad y el idioma especificados. Las solicitudes se procesan en cola bajo carga.
Recepción del archivo de audio generado
La respuesta contiene el archivo de audio binario en el formato solicitado (mp3, wav, opus, flac o pcm). Si la síntesis falla, no se cobra y se devuelve un código de error HTTP para que tu sistema pueda reintentar la operación.
Selección de voz y tono
A la hora de adaptar el audio a las necesidades de un comedor colectivo, la elección de la voz determina cómo se recibe la información. Las voces femeninas ofrecen claridad narrativa ideal para la lectura de menús o descripciones de platos, mientras que las masculinas proporcionan un tono firme adecuado para instrucciones operativas o avisos de servicio.
Voces femeninas para narración clara
Las voces ARIA, NOVA, LUNA y SAGE están optimizadas para una dicción precisa y un ritmo natural. Son recomendables para la lectura de listas de ingredientes, comunicados internos o la presentación de las opciones del día, donde la comprensión rápida es clave para el personal de sala y cocina.
- ARIA: narradora cálida y clara
- NOVA: tono brillante y dinámico
- LUNA: suave, ideal para storytelling
- SAGE: calma, perfecta para instrucciones
Voces masculinas para instrucciones firmes
Las voces FELIX, MILO, ATLAS y ORION aportan presencia y autoridad. ATLAS resulta neutro para noticias o avisos generales, mientras que ORION ofrece un tono profundo para documentales o informes. FELIX es energético para promociones, y MILO mantiene una conversación amigable para recordatorios de tareas.
Estas voces son efectivas para anunciar cambios de menú, indicar tiempos de preparación o dirigir turnos en zonas de alta actividad, asegurando que el mensaje se entienda sobre el ruido ambiente típico de una cocina o comedor.
- FELIX: energético, ideal para promos
- MILO: amigable y conversacional
- ATLAS: neutro, estilo noticias
- ORION: profundo, estilo documental
Ajuste de velocidad entre 0,25 y 4,0
Puedes modificar la velocidad de reproducción entre 0,25 y 4,0 para adaptarla al contexto. En momentos de mayor actividad, aumentar la velocidad permite comunicar más información en menos tiempo sin perder la inteligibilidad. Para instrucciones críticas o nuevas, reducir la velocidad asegura que cada palabra sea entendida por el equipo.
Manejo de textos largos
La API limita cada solicitud a 4096 caracteres. Cuando un menú o comunicado excede este límite, la lógica de integración debe dividir el texto en bloques manejables antes del envío.
La integración debe recibir los fragmentos y concatenarlos secuencialmente. Este proceso es transparente para la aplicación que consume la API.
División automática en bloques de 4096 caracteres
Cada petición JSON acepta un máximo de 4096 caracteres. Si el texto es más largo, la lógica de integración debe dividir el contenido en partes que respeten este límite técnico.
- Límite estricto de 4096 caracteres por solicitud.
- Los espacios y puntuación cuentan como caracteres.
Unión de fragmentos de audio
El servidor devuelve un archivo de audio por cada solicitud procesada. La integración debe recibir estos fragmentos y concatenarlos secuencialmente para reproducir el mensaje completo sin pausas artificiales.
Coherencia en la lectura completa
Al unir los archivos, la reproducción mantiene la fluidez natural de la voz seleccionada. Aunque las solicitudes se procesan una tras otra, el resultado final es un audio continuo listo para altavoces en cocina o comedor.
Detección de idioma
El sistema identifica el idioma del texto enviado basándose en el script utilizado. Esta detección automática permite que la API procese correctamente la pronunciación sin necesidad de configuraciones adicionales para casos comunes.
Sin embargo, el sistema asume inglés por defecto para cualquier texto en caracteres latinos si no se especifica lo contrario. Esto significa que una receta en español podría leerse con acento inglés si no se indica el idioma correctamente.
Detección automática por script
La API analiza los caracteres del texto para inferir el idioma. Si el texto contiene caracteres específicos de japonés, chino o coreano, la API detecta el idioma y aplica las reglas de pronunciación correspondientes.
- Identifica scripts latinos, cirílicos, asiáticos y semitas
- Funciona sin parámetros adicionales en la mayoría de los casos
Predeterminado inglés para texto latino
Si el texto está en caracteres latinos y no se indica el idioma, la API lo tratará como inglés. Esto puede resultar en una pronunciación incorrecta para menús en español o francés.
Por ejemplo, palabras como "menú" o "café" se pronunciarían con acento inglés si no se especifica el idioma correctamente.
Ajuste manual con código ISO
Para garantizar una pronunciación correcta, se recomienda especificar el idioma mediante el campo language en la solicitud. Utiliza códigos ISO de dos letras, como es para español o fr para francés.
Esto asegura que la voz seleccione las reglas fonéticas adecuadas, especialmente importante en comedores multilingües donde se leen instrucciones en varios idiomas.
Velocidad de generación
La velocidad de generación depende de la longitud del texto y la carga del servidor. Para textos largos, el proceso se aproxima al tiempo real, generando aproximadamente 25 caracteres por segundo de audio. Esto permite una sincronización eficiente en sistemas de comedores colectivos donde la inmediatez es crucial para la operación diaria.
Aproximadamente tiempo real para textos largos
La generación de audio sigue una tasa constante de unos 25 caracteres por segundo. Esta métrica asegura que menús extensos o comunicados largos se produzcan en un tiempo proporcional a su duración, facilitando la planificación de las transmisiones en las salas de comedor.
Retardo inicial en frases cortas
Las frases breves pueden tardar unos segundos en completarse. , por lo que se recomienda anticipar la reproducción de avisos rápidos o instrucciones de cocina para evitar silencios incómodos.
Cola de procesamiento bajo carga
Las solicitudes se procesan en secuencia. Bajo alta demanda, las peticiones pueden entrar en una cola de espera, lo que incrementa el tiempo total de respuesta. Es útil monitorizar este comportamiento para ajustar la frecuencia de envío de textos durante las horas punta del servicio.
El límite de 60 solicitudes por minuto por clave ayuda a gestionar esta cola. Si se supera el umbral, las peticiones adicionales se retrasan hasta que se libere capacidad, manteniendo la estabilidad del servicio sin interrupciones bruscas.
Uso en sistemas de comedor
La API se integra directamente con los menús digitales y sistemas de gestión de comedores, convirtiendo texto plano en audio claro sin necesidad de hardware especializado. Este flujo permite distribuir información culinaria y operativa a todo el personal.
La automatización reduce la carga de comunicación manual, asegurando que las instrucciones críticas sobre alérgenos o cambios de menú se escuchen con precisión, independientemente de la ubicación del empleado en la planta.
Integración con menús digitales
Los menús digitales pueden enviar solicitudes POST a la API para generar audios de platos o descripciones. Esto permite que las pantallas de servicio o los dispositivos móviles del personal accedan a la información textual convertida en voz natural.
La integración es agnóstica al formato: cualquier sistema que pueda enviar JSON y recibir un archivo de audio puede aprovechar la tecnología para mejorar la accesibilidad y la eficiencia de la lectura.
- Envío de texto de menú mediante JSON estándar
- Recibido audio listo para reproducción inmediata
- Compatible con cualquier sistema que soporte HTTP
Avisos automáticos en cocina
Las instrucciones de preparación o cambios de menú pueden traducirse automáticamente a audio para sonar en las estaciones de cocina. Esto asegura que las normas de seguridad alimentaria o los ajustes de servicio se comuniquen claramente sin depender de la lectura visual.
El uso de voces como Felix para anuncios energéticos o Sage para instrucciones calmadas ayuda a distinguir entre tipos de avisos, manteniendo la claridad en entornos ruidosos.
- Generación instantánea de avisos por cambios de menú
- Claro sobre el ruido de fondo de la cocina
- Sin necesidad de personal dedicado a leer avisos
Comunicados para equipos de servicio
Los comunicados internos, como turnos o recordatorios de higiene, pueden distribuirse como archivos de audio a los dispositivos de los empleados. Esto facilita la recepción de información crítica incluso cuando las manos están ocupadas con la preparación de platos.
La capacidad de ajustar la velocidad entre 0,25 y 4,0 permite adaptar la velocidad de lectura a las necesidades del equipo, acelerando la transmisión de información rutinaria o ralentizándola para instrucciones complejas.
- Distribución de comunicados a dispositivos móviles
- Ajuste de velocidad para diferentes contextos
- Acceso a información sin necesidad de mirar pantallas
Formatos de salida
La API permite seleccionar el formato de audio que mejor se adapte a la infraestructura de cada comedor, garantizando la correcta reproducción en los dispositivos de difusión o en las aplicaciones de los empleados.
MP3 para reproducción general
El formato MP3 es la opción predeterminada para la mayoría de los sistemas de comunicación en comedores. Ofrece un equilibrio adecuado entre calidad de sonido y tamaño de archivo, facilitando su reproducción en reproductores básicos, altavoces de cocina o dispositivos móviles sin consumir ancho de banda excesivo.
WAV para alta fidelidad
Se recomienda WAV cuando la integridad del audio es crítica o se requiere una calidad sin pérdidas. Este formato sin compresión es ideal para sistemas de audio profesional o para archivado de comunicados institucionales, aunque genera archivos más grandes que requieren más espacio de almacenamiento en los servidores del comedor.
OPUS para eficiencia en red
OPUS ofrece una compresión eficiente que reduce significativamente el uso de ancho de banda, lo que resulta útil para la transmisión en redes con conectividad limitada o para la distribución masiva de avisos a múltiples dispositivos simultáneamente. Mantiene una claridad de voz suficiente para la comprensión inmediata en entornos ruidosos.

Limitaciones técnicas
La API devuelve el archivo de audio completo al finalizar la síntesis, sin ofrecer transmisión en tiempo real ni conexión WebSocket para recibir fragmentos parciales. Esto significa que no hay reproducción progresiva durante el procesamiento.
Sin streaming ni WebSocket
El cliente debe esperar a que el servidor termine de generar todo el audio antes de recibir la respuesta. No hay flujo de datos continuo que permita escuchar partes del mensaje mientras se sigue procesando.
Sin SSML ni etiquetas de emoción
La entrada se limita a texto plano. No es posible controlar pausas, énfasis o velocidad de palabras individuales mediante etiquetas SSML. Tampoco se pueden marcar emociones como alegría o seriedad en el tono.
Sin diccionario de pronunciación personalizado
No existe la capacidad de subir un diccionario propio para corregir la pronunciación de términos específicos, nombres de platos o jerga interna del comedor. La voz sigue su regla de pronunciación estándar por defecto.
Seguridad de datos
La privacidad es fundamental para las operaciones diarias del comedor. Al utilizar nuestra API, el texto que introduces se procesa exclusivamente para generar el archivo de audio solicitado. Este contenido no se utiliza para entrenar modelos ni se almacena indefinidamente, garantizando que las instrucciones de cocina o los comunicados internos permanezcan confidenciales durante el ciclo de vida de la solicitud.
Una vez entregado el archivo de audio en la respuesta, no se conserva ninguna copia del contenido generado en nuestros servidores. Esta política asegura que la información auditiva producida para tu equipo no quede registrada, minimizando el riesgo de exposición de datos sensibles en caso de auditorías o accesos externos.
Texto no usado para entrenamiento
El texto enviado a través de la API se utiliza estrictamente para la síntesis de voz. No se incorpora a nuestros conjuntos de datos para mejorar o entrenar futuros modelos de IA, lo que mantiene el origen de la información bajo tu control exclusivo.
Audio no almacenado tras la respuesta
Los archivos de audio generados se entregan directamente en la respuesta de la solicitud y no se archivan en nuestro sistema de almacenamiento persistente. Una vez que el cliente ha recibido el archivo, no conservamos una copia del audio producido para ese texto específico.
Metadatos guardados solo para facturación
Se retienen únicamente los metadatos necesarios para la gestión de la cuenta: la hora de la solicitud, la cantidad de caracteres procesados y el estado de la petición (éxito o fallo). Esta información es esencial para calcular el coste exacto y verificar el historial de uso, sin almacenar el contenido textual ni de audio en sí.
Estos datos de facturación no incluyen el texto original de los menús o comunicados, asegurando que la información comercial del comedor permanezca aislada de los registros de consumo.
Escalabilidad para grandes equipos
ComedorDigital está diseñado para entornos de alta densidad donde varios dispositivos pueden generar audio simultáneamente. La arquitectura de la API gestiona las peticiones de manera eficiente, permitiendo que grandes equipos de restaurantes utilicen la herramienta sin necesidad de contratar licencias adicionales por cada persona.
Gestión de claves por cuenta
Cada cuenta de ComedorDigital dispone de una única clave API activa. Esta clave autoriza todas las peticiones de generación de audio desde cualquier dispositivo conectado a la plataforma, simplificando la administración técnica en comedores colectivos.
- Una clave activa por cuenta
- La nueva clave invalida a la anterior inmediatamente al emitir una renovación
- Autenticación mediante cabecera
Authorization: Bearer
Control de límite por minuto
El sistema procesa las solicitudes con un límite de 60 peticiones por minuto por clave. En fases iniciales o tras la creación de la cuenta, el límite es de 10 peticiones por minuto hasta realizar el primer recargo de saldo.
- Límite estándar: 60 solicitudes/minuto
- Límite inicial: 10 solicitudes/minuto
- Procesamiento secuencial bajo carga
Sin límites de usuarios en la cuenta
No existe un costo adicional por número de empleados o dispositivos. Todos los usuarios del comedor pueden compartir la misma cuenta y clave API para generar instrucciones, menús o comunicados, sin restricciones de usuarios concurrentes en la licencia.
- Sin coste por usuario
- Uso compartido de la clave API
- Ideal para turnos rotativos
Errores comunes
Los errores de implementación suelen derivar de suposiciones sobre la capacidad de la API. Entender los límites técnicos evita interrupciones en la difusión de menús o instrucciones en comedores colectivos.
Texto demasiado largo sin dividir
La API acepta un máximo de 4096 caracteres por solicitud. Si se envía un menú completo o un comunicado extenso sin segmentación previa, la solicitud fallará.
- Divide textos superiores a 4096 caracteres en fragmentos lógicos antes de enviarlos.
- La API devuelve un archivo por fragmento; la integración debe unirlos para garantizar coherencia.
Voz no soportada o mal especificada
Solo existen 8 voces predefinidas (Aria, Nova, Luna, Sage, Felix, Milo, Atlas, Orion). Solicitar una voz inexistente o mal escrita provoca un error inmediato. Además, la voz es neutra respecto al idioma; no hay voces específicas para español o chino, sino configuraciones de velocidad y tono.
- Verifica la lista de voces disponibles en GET /v1/voices antes de integrar.
- Usa el parámetro
languagepara forzar la pronunciación correcta si la detección automática falla.
Clave de API incorrecta o expirada
La autenticación requiere un token Bearer válido. Si se emite una nueva clave, la anterior deja de funcionar inmediatamente. Usar una clave obsoleta resulta en errores de autorización 401, interrumpiendo la reproducción de avisos en cocina o salones.
- Renueva la clave desde el panel /get-api-key/ si se sospecha una filtración.
- Monitorea el estado de la clave, ya que no hay aviso previo de expiración automática.
Mejores prácticas
Optimiza la entrada de texto eliminando saltos de línea innecesarios y caracteres especiales que no aporten valor semántico. Esto reduce el conteo de caracteres y evita errores de sintaxis en la generación de audio, manteniendo la claridad para los equipos de servicio.
Selecciona la voz según el propósito: una voz calmada como Sage para instrucciones de seguridad, o una voz enérgica como Felix para avisos de menú. Ajustar el tono reduce la fatiga auditiva en ambientes ruidosos de comedor.
Enviar texto limpio sin formato HTML
Envía solo el texto plano. La API no interpreta etiquetas HTML, por lo que incluir <b> o <br> cuenta como caracteres facturables sin mejorar la pronunciación. Limpia los datos antes de enviarlos para ahorrar crédito y tiempo de procesamiento.
- Elimina saltos de línea dobles.
- Reemplaza símbolos por palabras completas si es necesario.
Usar la voz adecuada para el contexto
Alinea el timbre de la voz con la urgencia del mensaje. Usa voces neutrales como Atlas para comunicados oficiales y voces más cálidas como Aria para menús diarios. Esto mejora la comprensión en equipos grandes donde el ruido ambiental es alto.
- Atlas para avisos de cocina.
- Luna para instrucciones de servicio.
Monitorizar el consumo de caracteres
Revisa el panel de control para ver el uso actual y el saldo restante. Cada carácter, incluido el espacio, cuenta para la facturación. Controlar el volumen te permite ajustar la longitud de los avisos antes de que se agote el crédito.
- Verificar saldo en /get-api-key/.
- Ajustar longitud de textos largos.
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.
