¿Cómo integrar la API de texto a voz en tus dispositivos IoT?

Por equipo editorial VozHoja · Actualizado 2026-11-19

Esta guía explica cómo integrar la API de texto a voz de VozHoja en dispositivos IoT y sistemas de domótica sin necesidad de código complejo. Aprenderás a configurar el endpoint, enviar texto y recibir audio para crear asistentes de voz, notificaciones y controles de hogar inteligente.

El proceso utiliza solicitudes HTTP estándar con una API Key válida. Encontrarás ejemplos prácticos en cURL, Python y JavaScript, junto con detalles sobre latencia, límites de tasa y costos por dispositivo, ideales para implementar síntesis de voz en tus proyectos de IoT.

¿Cómo integrar la API de texto a voz en tus dispositivos IoT?

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

Ilustración de onda de sonido para: 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

Ilustración de onda de sonido para: 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

Ilustración de onda de sonido para: 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

Ilustración de onda de sonido para: 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

Ilustración de onda de sonido para: 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

Ilustración de onda de sonido para: 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

Ilustración de onda de sonido para: 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();
Ejemplos de código

Pruebas y validación

Ilustración de onda de sonido para: 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

Ilustración de onda de sonido para: 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

Ilustración de onda de sonido para: 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

Ilustración de onda de sonido para: 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

Ilustración de onda de sonido para: 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.

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. LibriTTS-R corpus (OpenSLR 141)
  3. openai-node on GitHub
  4. ISO 639 language codes
  5. curl documentation
  6. FFmpeg documentation
  7. W3C WAI: making audio and video accessible
  8. IETF RFC 7845: Ogg Opus
  9. openai-python on GitHub
  10. MDN: Web Speech API
  11. Creative Commons Attribution 4.0
  12. OpenAI API reference: create speech

Más en este sitio