Preguntas frecuentes
¿Qué es una API de texto a voz?
Es un servicio en la nube que recibe texto y devuelve un archivo de audio mediante una petición POST. Envías el texto al endpoint y recibes el audio listo para reproducirse en tus dispositivos, sin necesidad de gestionar servidores de síntesis.
¿Qué es un dispositivo IoT?
Un objeto físico con capacidad de conexión a internet que puede recibir y procesar datos. En domótica, estos dispositivos ejecutan comandos como reproducir audio de notificaciones o respuestas de voz generadas por la API para interactuar con el usuario.
¿Qué es sin código en IoT?
Es un enfoque que permite conectar y programar dispositivos IoT mediante interfaces visuales o configuraciones predefinidas, sin escribir código complejo. Ideal para usuarios que buscan integrar la API de texto a voz mediante simples llamadas o flujos lógicos.
¿Cómo se conecta la API a un sensor?
El sensor no se conecta directamente; un intermediario (como un hub o script) recibe la señal, genera el texto y lo envía a la API. La API devuelve el audio, que el intermediario envía al dispositivo de salida para su reproducción.
¿Qué es un hub domótico?
Es un dispositivo central que coordina la comunicación entre sensores, actuadores y servicios en la nube. Recibe alertas, las convierte a texto, las envía a la API de texto a voz y reproduce el audio resultante en altavoces inteligentes conectados.
¿Qué es cURL?
Una herramienta de línea de comandos para transferir datos usando protocolos como HTTP. Permite probar la API enviando peticiones POST con texto y recibiendo el audio, útil para verificar la integración antes de implementarla en sistemas automatizados.
¿Qué es el SDK de OpenAI?
Es una librería oficial que facilita las llamadas a la API. Puedes usarlo cambiando la URL base a https://api.onebox63.info/v1 y autenticando con tu clave, reutilizando código familiar para integrar la síntesis de voz en tus aplicaciones.
¿Qué es un endpoint REST?
Es la dirección URL específica donde se envían las peticiones. Para este servicio, el endpoint es POST https://api.onebox63.info/v1/audio/speech, que acepta texto en formato JSON y devuelve el archivo de audio generado.
¿Qué es un header de autenticación?
Es una cabecera HTTP que incluye tu clave API para validar la solicitud. Debe enviarse como Authorization: Bearer tts-... en cada petición, asegurando que solo cuentas autorizadas puedan generar audio y consumir créditos de la API.
¿Qué es un formato binario?
Es un tipo de archivo que contiene datos no legibles directamente como texto, como WAV, FLAC o MP3. La API devuelve el audio en estos formatos binarios para que los dispositivos IoT puedan reproducirlo mediante sus reproductores integrados.
¿Qué es la latencia en IoT?
Es el tiempo entre enviar el texto y recibir el audio. La API procesa las solicitudes secuencialmente; textos largos tardan aproximadamente 25 caracteres por segundo de audio generado, mientras que frases cortas pueden demorar unos segundos adicionales.
¿Qué es el consumo de datos?
Se refiere al uso de tu saldo basado en caracteres enviados. El costo es $10 por millón de caracteres. Los espacios y puntuación cuentan como caracteres, y las peticiones fallidas no se cobran, optimizando el uso de recursos.
Requisitos previos
Para integrar la API de VozHoja en tu ecosistema IoT, primero necesitas una cuenta en onebox63.info. Regístrate mediante Google o correo electrónico para obtener acceso a la plataforma. Ten en cuenta que las cuentas son independientes por sitio y, si usas correo, no recibirás crédito de prueba inicial.
Cuenta en la plataforma
Accede a la página de registro para crear tu identificador único. Una vez verificado, tendrás acceso al panel de control donde gestionarás tu saldo y claves.
No se requieren suscripciones mensuales ni facturación con IVA. El saldo no expira y se recarga únicamente mediante USDT en la red TRON (TRC-20).
API Key activa
La autenticación se realiza mediante un token Bearer que comienza con tts-. Este identificador es el único activo por cuenta; si emites uno nuevo, el anterior deja de funcionar inmediatamente.
- Formato:
Authorization: Bearer tts-... - Se gestiona directamente desde el panel de usuario tras el inicio de sesión.
Conocimiento básico de JSON
La API espera cuerpos de solicitud en formato JSON estándar. Debes construir el payload con los campos model, input, voice y response_format para que los dispositivos IoT o gateways puedan procesar la solicitud correctamente.
Configuración del endpoint
La integración en dispositivos IoT comienza con la configuración del punto final de la API. Utiliza el método POST para enviar solicitudes de síntesis de voz desde tu hardware o gateway domótico, asegurando una conexión directa y eficiente con el servicio.
La URL base para las operaciones es https://api.onebox63.info/v1. Este endpoint maneja la conversión de texto a audio, permitiendo que tus dispositivos reciban archivos de audio listos para la reproducción sin necesidad de infraestructura adicional compleja.
URL de la API
Configura tu cliente IoT para apuntar a https://api.onebox63.info/v1/audio/speech. Esta ruta específica procesa la solicitud de síntesis y devuelve el archivo de audio generado.
La estructura sigue el estándar de la API de OpenAI, lo que facilita la integración usando librerías comunes en entornos embebidos o gateways de hogar inteligente.
- Base URL: https://api.onebox63.info/v1
- Endpoint de síntesis: POST /v1/audio/speech
- Endpoint de voces: GET /v1/voices
Método POST
Envía el texto a convertir en el cuerpo JSON de la solicitud. El dispositivo debe formatear los datos incluyendo el modelo ('tts-1' o 'tts-1-hd'), el texto de entrada y la voz seleccionada.
La solicitud es stateless, lo que permite que cada dispositivo IoT realice llamadas independientes sin mantener sesiones persistentes, optimizando el uso de recursos en redes IoT.
- Método HTTP: POST
- Cuerpo: JSON con 'input', 'model', 'voice'
- Formato de salida configurable (mp3, wav, opus)
Headers de autenticación
Incluye el encabezado Authorization: Bearer tts-... con tu clave activa obtenida en la plataforma. Esta clave autentica cada solicitud y permite el cobro basado en el uso.
Es esencial que el dispositivo mantenga esta clave actualizada. Si se emite una nueva clave, la anterior deja de funcionar inmediatamente, garantizando seguridad en la red IoT.
El header debe enviarse en cada solicitud POST para asegurar que el servicio reconozca tu cuenta y asigne los caracteres consumidos correctamente.
- Header: Authorization: Bearer tts-...
- Clave única por cuenta
- Invalidación inmediata al renovar
Envío de texto
Para generar audio, envía el texto mediante un método POST al endpoint de la API. El cuerpo de la solicitud debe ser un objeto JSON que contenga el campo input con el texto a sintetizar, limitado a 4096 caracteres por petición. Ten en cuenta que los espacios y la puntuación cuentan como caracteres.
Input de texto
El campo input acepta cualquier string de texto plano. Si tu mensaje supera los 4096 caracteres, debes dividirlo en partes más pequeñas y unir los archivos de audio resultantes posteriormente. Esto asegura una síntesis estable y predecible.
Selección de voz
Incluye el campo voice con uno de los ocho preset disponibles, como aria para narración clara o atlas para noticias. Puedes especificar opcionalmente el campo language con un código ISO si el texto no está en inglés para evitar que el sistema adivine el idioma incorrectamente.
- Aria, Nova, Luna, Sage (femeninas)
- Felix, Milo, Atlas, Orion (masculinas)
Formato de respuesta
Especifica el formato deseado en response_format entre mp3, wav, opus, flac o pcm. La API devolverá el archivo de audio binario directamente en la respuesta HTTP. Asegúrate de que tu dispositivo IoT esté preparado para decodificar el formato seleccionado sin latencia adicional.
Manejo de respuestas
La API devuelve el archivo de audio directamente en el cuerpo de la respuesta. Dependiendo del formato seleccionado (mp3, wav, opus, flac o pcm), los dispositivos IoT recibirán datos binarios listos para ser reproducidos por los altavoces integrados o guardados como archivos de audio.
Los códigos de estado HTTP indican el resultado de la síntesis. Un estado 200 confirma que el audio se generó correctamente y se entregó. Cualquier código 4xx o 5xx indica un fallo en la solicitud o en el servidor, deteniendo la entrega del audio binario.
Audio binario
El archivo generado se envía como flujo binario. Los dispositivos deben leer este flujo sin interpretarlo como texto JSON. El formato elegido determina la compatibilidad con los reproductores de hardware IoT.
- Formatos soportados: mp3, wav, opus, flac, pcm
- El audio no se almacena en servidores tras la entrega
- El archivo incluye una marca de agua inaudible que identifica el contenido como síntesis
Códigos de estado
El estado 200 OK indica éxito. Los errores de cliente (4xx) suelen deberse a claves inválidas o límites de caracteres excedidos. Los errores del servidor (5xx) son temporales y pueden reintentarse.
Manejo de errores
Si la síntesis falla, no se cobra el crédito. La respuesta incluirá un mensaje de error JSON explicando la causa, como un formato de voz inválido o un problema de autenticación. Revisa la documentación para los códigos específicos.
Integración con sensores
La integración con sensores permite activar la síntesis de voz mediante eventos específicos, como la detección de movimiento o cambios de temperatura. Al recibir la señal, el sistema envía un texto breve al endpoint, generando audio instantáneo para notificaciones locales sin intervención humana.
La latencia es crítica en domótica. Con una velocidad de generación de aproximadamente 25 caracteres por segundo, las frases cortas se procesan en segundos. Si la cola está ocupada, puede haber una ligera espera, pero la respuesta es inmediata para la mayoría de los comandos simples.
Activación por evento
Los sensores IoT pueden desencadenar solicitudes API directamente desde el edge device o mediante un script ligero. Cada evento válido envía una petición POST con el texto predefinido, asegurando que la respuesta de audio sea contextual y relevante para la situación detectada.
- Detectores de movimiento activan anuncios de seguridad.
- Sensores de puerta generan avisos de apertura.
- Termostatos anuncian cambios de temperatura programados.
Latencia de respuesta
La generación de audio es asíncrona pero rápida para textos cortos. Aunque las peticiones se procesan en secuencia, la carga mínima en dispositivos IoT suele mantener los tiempos de espera por debajo de unos pocos segundos, manteniendo la fluidez de la interacción usuario-dispositivo.
Consumo de datos
El formato de respuesta permite elegir MP3 para optimizar el ancho de banda. Al recibir el archivo binario, el dispositivo IoT lo reproduce localmente, minimizando el tráfico de red en comparación con soluciones que dependen de streaming continuo o procesamiento en la nube para cada frame.
Uso en hubs domóticos
Los hubs domóticos actúan como orquestadores, recibiendo eventos de sensores o comandos y generando respuestas de voz sin intervención humana. La integración permite que dispositivos como termostatos o cerraduras notifiquen estados mediante audio sintetizado al instante.
La latencia típica de la API es de unos segundos para frases cortas, suficiente para notificaciones contextuales pero insuficiente para interacción conversacional en tiempo real. Se recomienda usar la API para avisos unidireccionales o confirmaciones de estado.
Comandos de voz
El hub captura la intención del usuario y envía el texto a la API para generar el audio de respuesta. Esto permite confirmar acciones, como 'La puerta principal ha sido cerrada', sin necesidad de pantallas en cada dispositivo.
- Envío de texto corto (<4096 caracteres) desde el hub a la API
- Uso de voces como 'nova' para confirmaciones rápidas o 'atlas' para estados neutros
- Formato mp3 o wav para máxima compatibilidad con reproductores de bajo costo
Respuestas automatizadas
Las notificaciones se generan al detectar eventos específicos, como apertura de puerta o cambio de temperatura. El sistema concatena los fragmentos de audio si el mensaje excede los 4096 caracteres, asegurando la integridad del mensaje.
- Activación por eventos de sensores (movimiento, temperatura, humedad)
- Generación de audio bajo demanda para evitar almacenamiento masivo
- Uso del campo 'language' para forzar el idioma en dispositivos multilingües
Integración con IFTTT
IFTTT puede disparar peticiones a la API cuando se cumple una condición específica, como un sensor de agua. El webhook envía el texto predefinido a la API, que devuelve el audio para reproducirlo en los altavoces conectados.
- Configuración de triggers en IFTTT para eventos del hogar
- Webhook que envía el payload JSON a la API
- Reproducción automática del audio generado en dispositivos compatibles
Ejemplos de código
La integración requiere enviar texto a la API mediante HTTP. El endpoint acepta JSON con el modelo, la voz y el formato deseado. La respuesta contiene el archivo de audio binario listo para reproducirse en el dispositivo IoT.
Los ejemplos siguientes muestran las tres formas más comunes de realizar la solicitud. Cada método maneja la autenticación y la recepción del audio de manera específica para su entorno de ejecución.
cURL básico
Utiliza este comando para verificar la integración directamente desde la terminal del dispositivo o gateway.
Reemplaza tts-tu-key con tu clave real y ajusta los parámetros según la voz y el idioma deseados.
- curl -X POST https://api.onebox63.info/v1/audio/speech
- -H "Authorization: Bearer tts-tu-key"
- -H "Content-Type: application/json"
- -d '{"model": "tts-1", "input": "Alerta de seguridad", "voice": "aria", "response_format": "mp3"}'
Python con SDK OpenAI
Aprovecha el SDK oficial de OpenAI cambiando la base URL para usar nuestra API sin modificar la lógica de llamada.
El código maneja la descarga del audio binario y lo guarda localmente para su reproducción inmediata.
- from openai import OpenAI
- client = OpenAI(base_url="https://api.onebox63.info/v1", api_key="tts-tu-key")
- audio = client.audio.speech.create(model="tts-1", voice="nova", input="Buenos días", response_format="mp3")
- audio.stream_to_file("output.mp3")
JavaScript fetch
Ideal para entornos basados en navegador o Node.js en gateways domóticos.
La promesa convierte la respuesta en un Blob para su reproducción nativa en el reproductor de audio del dispositivo.
- const response = await fetch("https://api.onebox63.info/v1/audio/speech", {
- method: "POST",
- headers: { "Authorization": "Bearer tts-tu-key", "Content-Type": "application/json" },
- body: JSON.stringify({ model: "tts-1", voice: "luna", input: "Luces encendidas" })
- });
- const blob = await response.blob();

Pruebas y validación
La validación técnica asegura que la síntesis cumpla con los tiempos esperados en entornos IoT reales. Cada solicitud procesa texto en tiempo real aproximado (25 caracteres por segundo), aunque las solicitudes largas pueden requerir división en fragmentos de 4096 caracteres.
La calidad del audio se verifica mediante la escucha de las 8 voces disponibles, que incluyen marcas de agua inaudibles para identificar el contenido sintético. El formato de respuesta debe coincidir con las capacidades del reproductor del dispositivo, ya sea MP3, WAV, OPUS, FLAC o PCM.
Prueba de latencia
Evalúa el tiempo total desde el envío del JSON hasta la recepción del archivo de audio. Para textos cortos, la generación toma unos segundos; para textos largos, el tiempo se acerca al tiempo real de reproducción.
Considera que las solicitudes se procesan en cola si hay carga. Verifica que el dispositivo IoT pueda manejar la espera sin desconectarse o reiniciar el bucle de comandos.
- Mide el tiempo de respuesta en ms para frases de menos de 100 caracteres.
- Verifica la estabilidad de la conexión Wi-Fi o Ethernet durante la descarga del audio.
- Prueba la recuperación tras un corte de red breve.
Calidad de audio
Comprueba la claridad de la voz y la pronunciación correcta en los 23 idiomas soportados. Si el texto está en latín pero no es inglés, asigna explícitamente el campo language para evitar la asignación automática incorrecta.
Confirma que el formato seleccionado (MP3, WAV, etc.) sea compatible con el hardware de altavoces del dispositivo.
- Verifica que no haya cortes abruptos en el audio generado.
- Confirma que la velocidad (0.25–4.0) se aplique correctamente.
- Escucha la marca de agua inaudible para confirmar que es contenido sintético.
Prueba en dispositivo
Despliega la lógica de integración en el hardware objetivo. Asegúrate de que el dispositivo pueda almacenar temporalmente el archivo de audio binario o reproducirlo (la API no ofrece streaming nativo).
Valida que la API Key se gestione correctamente y que los errores de síntesis no bloqueen el sistema domótico.
- Prueba la reproducción de audio en diferentes volúmenes.
- Verifica el consumo de memoria RAM durante la descarga.
- Comprueba la gestión de errores HTTP (ej. 429 por límites de tasa).
Escalabilidad
La API procesa las solicitudes secuencialmente, lo que significa que las peticiones se ejecutan una tras otra. En situaciones de alta demanda, es posible que una solicitud deba esperar en una cola antes de comenzar la síntesis, lo que afecta la latencia percibida en dispositivos IoT en tiempo real.
Límites de tasa
Cada clave de API está limitada a 60 solicitudes por minuto. Antes de realizar la primera recarga, este límite se reduce a 10 solicitudes por minuto. Es fundamental monitorear este límite para evitar rechazos en dispositivos que requieran respuestas inmediatas.
- 60 req/min tras la primera recarga
- 10 req/min antes del primer pago
- Un solo límite por clave activa
Gestión de cola
Debido al procesamiento secuencial, si múltiples dispositivos solicitan audio simultáneamente, las peticiones se ordenan y procesan una por una. Esto puede introducir un retraso variable dependiendo de la carga del servidor en ese momento.
Optimización de caracteres
Para mejorar la escalabilidad, divida textos largos en fragmentos de hasta 4096 caracteres. La concatenación de los archivos de audio resultantes es más eficiente que enviar textos extremadamente largos en una sola solicitud, reduciendo la probabilidad de errores o tiempos de espera excesivos.
Monitoreo de uso
El panel de control de <strong>onebox63.info</strong> muestra el saldo actual, el crédito de prueba restante y los caracteres consumidos. Esta información se actualiza en tiempo real tras cada solicitud exitosa, permitiendo verificar el estado de la cuenta sin salir de la interfaz.
Panel de control
La página de inicio muestra el saldo actual, el crédito de prueba restante y los caracteres consumidos. Esta información se actualiza tras cada solicitud exitosa, permitiendo verificar el estado de la cuenta sin salir de la interfaz.
Registro de solicitudes
Se conserva un registro de metadatos (hora, caracteres, estado) exclusivamente para facturación. Estos datos permiten auditar el consumo de caracteres por dispositivo IoT sin almacenar el audio generado ni el texto original.
Costos por dispositivo
El costo es de $0.01 por cada 1,000 caracteres. Al integrar sensores, es recomendable agrupar textos para optimizar la factura mensual y evitar límites de tasa, manteniendo un registro claro del gasto por nodo domótico.
Soporte técnico
El soporte técnico se limita al correo electrónico. No ofrecemos atención telefónica ni chat en vivo, lo que mantiene los costos bajos para tu integración IoT. Para resolver incidencias, envía tu solicitud a [email protected] con detalles de tu API Key y el código de error.
Documentación de errores
La API devuelve códigos de estado HTTP estándar para indicar el resultado de cada síntesis. Los errores comunes incluyen límites de tasa excedidos (429) o errores de entrada (400). Consulta la sección de errores en la documentación técnica para mapear cada código a su causa específica y solución inmediata.
Contacto por email
Envía tu consulta a [email protected]. Incluye siempre tu API Key activa y un ejemplo del JSON enviado. Nuestro equipo responde exclusivamente por este medio, sin canales adicionales como teléfono o chat en vivo.
Comunidad de IoT
No contamos con una comunidad propia ni foros dedicados. Los usuarios comparten experiencias en foros externos de domótica, pero no somos parte oficial de esas comunidades.
Casos de éxito IoT
La API de VozHoja permite transformar notificaciones críticas en audio claro sin necesidad de hardware especializado, integrándose directamente en los sistemas de seguridad del hogar mediante eventos simples.
Notificaciones de seguridad
Al detectar una apertura de puerta o un movimiento inusual, el sistema envía el texto al endpoint y reproduce una alerta auditiva inmediata en los altavoces IoT, garantizando atención rápida sin depender de la vista.
Asistentes de cocina
Los dispositivos en la cocina pueden leer cronómetros o instrucciones de recetas sin ocupar la pantalla del usuario. Esto permite mantener las manos libres mientras se cocina, utilizando voces claras como 'nova' o 'sage' para instrucciones concisas.
Control de iluminación
Al activar escenas de iluminación, el sistema puede confirmar verbalmente el estado de las luces o indicar cambios de temperatura de color, proporcionando retroalimentación auditiva inmediata que complementa la señal visual del dispositivo.
Escucha las 8 voces
Cada muestra a continuación fue generada por esta API a partir de la misma frase.
23 idiomas
Cualquier voz puede hablar cualquiera de estos idiomas.
