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

Por equipo editorial VozHoja · Actualizado 2026-11-19

Esta documentación técnica explica cómo integrar la API de síntesis de voz de VozHoja en dispositivos IoT y sistemas de domótica sin código. Aquí encontrarás los endpoints, parámetros de voz y formatos de audio necesarios para generar audio desde texto en tus ecosistemas inteligentes.

La guía cubre la obtención de la API Key, ejemplos de requests con cURL y la configuración con el SDK de OpenAI. También detalla los límites de 60 solicitudes por minuto, el manejo de textos largos y los errores comunes, proporcionando toda la información técnica necesaria para una integración eficiente.

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

Preguntas frecuentes

¿Cómo se obtiene la API Key?

Regístrate en /get-api-key/ con Google o correo electrónico. La clave se emite al instante y se usa con el encabezado Authorization: Bearer tts-... Puedes generar una nueva en cualquier momento; la anterior deja de funcionar inmediatamente.

¿Qué es el endpoint POST?

Es POST https://api.onebox63.info/v1/audio/speech. Envías texto en formato JSON y recibes un archivo de audio. Es el único punto de entrada para la síntesis de voz en la API.

¿Se puede usar el SDK de OpenAI?

Sí. Usa el SDK oficial de OpenAI cambiando el base_url a https://api.onebox63.info/v1. La forma de la solicitud es idéntica al endpoint de speech de OpenAI, facilitando la integración en tus proyectos IoT.

¿Qué formatos de audio están disponibles?

Puedes solicitar los formatos mp3, wav, opus, flac o pcm. Elige el que mejor se adapte a tu dispositivo IoT o sistema de notificaciones domóticas según tus necesidades de compresión y calidad.

¿Qué significa el error 401?

Indica un error de autenticación. Verifica que tu API Key sea válida y esté correctamente formada en el encabezado Authorization: Bearer tts-... Si la clave es incorrecta o ha sido revocada, la solicitud fallará.

¿Qué significa el error 429?

Significa que excediste el límite de velocidad de 60 solicitudes por minuto por clave. Reduce la frecuencia de tus peticiones o espera a que el contador se reinicie para reanudar la síntesis de voz.

¿Cuántos caracteres se pueden enviar?

Cada solicitud POST acepta un máximo de 4096 caracteres en el campo input. Si tu texto es más largo, debes dividirlo en partes y unir los archivos de audio resultantes para la reproducción final.

¿Se puede cambiar la velocidad de voz?

Sí, el parámetro speed permite ajustar la velocidad entre 0.25 y 4.0. Esto es útil para ajustar la duración de las notificaciones en tus dispositivos IoT sin alterar la claridad de la síntesis.

¿Qué pasa si se excede el límite de caracteres?

La solicitud será rechazada si el input supera los 4096 caracteres. Debes dividir tu texto en fragmentos más pequeños y enviar múltiples solicitudes para obtener el audio completo de la frase o instrucción deseada.

¿Cómo se manejan los textos largos?

Divide el texto en partes de hasta 4096 caracteres. Envía cada parte mediante una solicitud POST y une los archivos de audio resultantes. Esto permite generar audio para cualquier longitud de texto sin límites estrictos.

¿Se puede usar audio en tiempo real?

No existe streaming ni WebSocket para audio parcial. El audio se genera completo y se devuelve en la respuesta. Para textos largos, el proceso tarda aproximadamente el tiempo real de la locución, aunque bajo carga puede haber latencia.

¿Hay una SDK oficial propia?

No. No ofrecemos un SDK propietario. Utiliza el SDK de OpenAI o cualquier cliente HTTP estándar. Solo necesitas configurar la URL base correctamente para que las librerías funcionen con nuestra API de voz.

¿Qué es tts-1-hd?

Es un valor de modelo que usa el mismo motor y precio que tts-1. Ambas opciones tienen el mismo costo por carácter y generan audio con la misma calidad base de la API de síntesis.

¿Se puede especificar el idioma?

Sí, usa el campo language con un código ISO. Si no se especifica, se intenta adivinar por el guion, pero para texto en latín no inglés, es recomendable definirlo explícitamente para asegurar la pronunciación correcta.

Primera solicitud

curl

curl https://api.onebox63.info/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.onebox63.info/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.onebox63.info/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 API Key

Ilustración de onda de sonido para: Obtención de API Key

Accede a /get-api-key/ para registrar tu cuenta mediante Google o email y contraseña. La interfaz muestra la clave activa, el saldo disponible y el código cURL listo para usar.

Registro con Google o email

Registro con Google o email

El registro con Google incluye una prueba de $0.50 válida por 7 días. Las cuentas creadas con email y contraseña comienzan sin crédito de prueba.

Ubicación de la clave

Ubicación de la clave

Tu clave API se visualiza en el panel de /get-api-key/. Utilízala en el encabezado Authorization: Bearer tts-... para autenticar tus solicitudes.

Reemisión de clave

Puedes emitir una nueva clave en cualquier momento. La clave antigua se invalida de forma inmediata al generar la nueva.

Primer request con cURL

Ilustración de onda de sonido para: Primer request con cURL

La síntesis de voz se inicia enviando una solicitud HTTP POST al endpoint de la API. Este punto final es el responsable de recibir el texto plano y devolver el archivo de audio generado en el formato especificado.

Endpoint POST

La dirección base para las solicitudes es https://api.onebox63.info/v1/audio/speech. Este endpoint acepta únicamente el método POST y requiere autenticación mediante un token Bearer en los encabezados.

Body JSON

El cuerpo de la solicitud debe ser un objeto JSON que contenga el texto a convertir (input), el modelo de voz (tts-1 o tts-1-hd), el identificador de la voz (voice), el formato de salida deseado (response_format) y opcionalmente la velocidad (speed) y el idioma (language). El campo input admite hasta 4096 caracteres.

  • model: "tts-1" o "tts-1-hd"
  • input: texto plano (máx. 4096 caracteres)
  • voice: preset de voz (ej. aria, felix)
  • response_format: mp3, wav, opus, flac o pcm
  • speed: multiplicador de 0.25 a 4.0

Ejemplo de código

El siguiente comando cURL envía una notificación de estado del hogar inteligente. Reemplaza YOUR_API_KEY con tu clave activa. El archivo de audio resultante se guarda localmente como alert.mp3.

  • curl -X POST https://api.onebox63.info/v1/audio/speech \
  • -H "Authorization: Bearer YOUR_API_KEY" \
  • -H "Content-Type: application/json" \
  • -d '{"model":"tts-1","input":"La puerta principal está cerrada.","voice":"atlas","response_format":"mp3"}' \
  • --output alert.mp3

Uso con SDK de OpenAI

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

La API es compatible con los SDKs oficiales de OpenAI mediante un ajuste mínimo en la configuración. Solo es necesario modificar la URL base para apuntar al endpoint de VozHoja, manteniendo la misma estructura de cuerpo JSON.

Esto permite utilizar las bibliotecas estándar en Python, JavaScript o Go sin reimplementar la lógica de serialización. La integración es directa y no requiere adaptadores adicionales para la mayoría de los casos de uso en domótica.

Cambio de base_url ['Configura la variable de entorno o el parámetro base_url del cliente SDK para apuntar a https://api.onebox63.info/v1. Este cambio redirige todas las llamadas al servicio de síntesis de voz de VozHoja.'] ['https://api.onebox63.info/v1']

Compatibilidad de SDK ['Los SDKs oficiales de OpenAI funcionan sin modificaciones en la lógica de la aplicación. La estructura de la petición es idéntica a la del endpoint de speech de OpenAI, lo que facilita la migración o el uso de clientes existentes en entornos IoT.', 'No se requiere una biblioteca propietaria adicional. El formato de respuesta y los campos de entrada (model, input, voice) son compatibles con los estándares esperados por estas bibliotecas.']

Configuración de headers ['El SDK gestiona automáticamente la serialización JSON. Debes proporcionar la clave API válida en el encabezado de autorización. Esto asegura que cada solicitud de síntesis sea autenticada correctamente ante el servidor de VozHoja.', 'La clave se envía como Bearer <tu_api_key>. Asegúrate de que la clave esté activa y tenga saldo suficiente para evitar errores de facturación durante la generación de audio.']

Formatos de audio

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

La API devuelve audio en los formatos MP3, WAV, OPUS, FLAC o PCM. Estos formatos permiten integrar la síntesis en distintos ecosistemas IoT, desde reproductores de audio hasta sistemas de notificación por voz en dispositivos sin pantalla.

MP3, WAV, OPUS, FLAC, PCM

Selecciona el formato que mejor se adapte al hardware del dispositivo IoT. MP3 y OPUS son eficientes en ancho de banda, mientras que WAV y FLAC ofrecen calidad sin pérdida. PCM es útil para dispositivos que requieren audio sin comprimir.

  • MP3: compresión eficiente, amplio soporte.
  • WAV: calidad original, mayor tamaño.
  • OPUS: alta eficiencia, ideal para IoT.
  • FLAC: sin pérdida, compresión ligera.
  • PCM: audio crudo sin compresión.

Elección por dispositivo IoT

Para dispositivos con recursos limitados, como sensores o altavoces básicos, MP3 u OPUS reducen el uso de memoria y ancho de banda. Si el dispositivo soporta decodificación en tiempo real, WAV o FLAC pueden ser opciones válidas para garantizar la claridad del audio.

Tamaño de archivo

El tamaño del archivo depende del formato y la duración. En general, OPUS y MP3 generan archivos más pequeños, ideales para transmisión en redes IoT con ancho de banda reducido. WAV y FLAC ocupan más espacio pero mantienen una mayor calidad de audio.

Considera la capacidad de almacenamiento del dispositivo al elegir el formato. Para notificaciones rápidas, formatos comprimidos son más eficientes.

Errores comunes

Ilustración de onda de sonido para: Errores comunes

La API devuelve códigos de estado HTTP claros para identificar fallos específicos durante la síntesis. La mayoría de los problemas se resuelven verificando la configuración de autenticación, los límites de tasa o la longitud del texto de entrada.

Los errores 401, 429 y 400 son los más frecuentes en entornos IoT donde las conexiones pueden ser intermitentes o los dispositivos envían comandos automáticos sin validación previa.

Error 401 (API Key)

Indica que la clave proporcionada es inválida, está mal escrita o ha sido revocada. Recuerda que emitir una nueva clave invalida inmediatamente a la anterior.

Asegúrate de incluir el encabezado Authorization: Bearer tts-... en cada solicitud. Si usas el SDK de OpenAI, verifica que base_url apunte a https://api.onebox63.info/v1.

  • Verifica que la clave comience con tts-
  • Revisa si has generado una nueva clave recientemente
  • Confirma que el encabezado de autorización se envía correctamente

Error 429 (Límite)

Se produce al exceder los 60 requests por minuto por clave (10 rpm antes del primer recargo). Las solicitudes se procesan en orden secuencial y pueden esperar en una cola bajo carga.

En dispositivos IoT, implementa un mecanismo de retroceso exponencial o buffer local para evitar saturar la API durante picos de notificaciones simultáneas.

  • Monitorea el encabezado X-RateLimit-Remaining
  • Implementa reintentos con backoff
  • Considera escalar el saldo para aumentar el límite base

Error 400 (Input)

Ocurre cuando el texto supera los 4096 caracteres o el formato JSON es inválido. El cuerpo debe contener los campos model, input y voice correctamente tipados.

Si el texto excede el límite, divídelo en partes menores y une los archivos de audio resultantes, ya que la API no almacena ni une automáticamente fragmentos.

  • Valida la longitud del string antes de enviar
  • Verifica la sintaxis JSON del cuerpo de la solicitud
  • Asegúrate de que voice sea una de las 8 presets válidas
Errores comunes

Límites de la API

Ilustración de onda de sonido para: Límites de la API

La API de VozHoja para domótica opera con límites técnicos definidos. No ofrecemos acuerdos de nivel de servicio (SLA) ni garantía de disponibilidad. Estos límites afectan directamente la capacidad de tus dispositivos IoT para generar notificaciones de voz en tiempo real.

60 solicitudes por minuto

Cada clave API permite un máximo de 60 solicitudes por minuto. Antes de la primera recarga, el límite es de 10 solicitudes por minuto. Este control evita la saturación del servidor durante picos de actividad en tu hogar inteligente.

4096 caracteres por request

Cada llamada POST puede contener hasta 4096 caracteres de texto. Los espacios y la puntuación cuentan como caracteres. Si tu mensaje de notificación excede este límite, debes dividirlo en varias solicitudes o la API devolverá un error.

Cola de procesamiento

Las solicitudes se procesan en orden secuencial. Bajo carga, las peticiones pueden esperar en una cola antes de iniciarse la síntesis. Esto puede añadir latencia a las respuestas de audio, especialmente en dispositivos con conexión intermitente.

Parámetros de voz

Ilustración de onda de sonido para: Parámetros de voz

La API ofrece dos identificadores de modelo, tts-1 y tts-1-hd, que funcionan de manera idéntica. Ambos utilizan el mismo motor de síntesis y ofrecen la misma calidad de audio y precio, lo que simplifica la integración en sistemas IoT sin necesidad de gestionar diferencias técnicas entre versiones.

El campo model en el cuerpo JSON acepta cualquiera de estos dos valores. Dado que no existe diferencia de precio ni de procesamiento, la selección depende únicamente de la convención de código o de la compatibilidad con SDKs específicos que requieran un identificador concreto.

Modelo tts-1

Es el identificador estándar para la generación de audio. Al enviar este modelo, la API procesa la solicitud utilizando el motor principal disponible. Es adecuado para la mayoría de los casos de uso en domótica, desde notificaciones de sensores hasta respuestas de asistentes de voz.

El costo es de $0.01 por cada 1.000 caracteres, independientemente del modelo seleccionado. No se aplican recargos por usar este identificador específico en lugar de tts-1-hd.

  • Identificador: "tts-1"
  • Motor de síntesis: Principal
  • Precio: Estándar ($10/1M caracteres)
  • Uso recomendado: General, domótica, alertas

Modelo tts-1-hd

Utiliza el mismo motor de síntesis que tts-1. Ambos modelos tienen el mismo precio y calidad de audio. No ofrece mayor fidelidad vocal ni requiere más recursos de procesamiento, por lo que no justifica su uso en escenarios de bajo coste por una supuesta mejora técnica.

Su existencia responde principalmente a la compatibilidad con el formato de solicitud de la API de referencia. Puede usarse si el sistema cliente está hardcodeado para solicitar este modelo, pero no aporta ventajas audibles o de rendimiento.

  • Identificador: "tts-1-hd"
  • Calidad: Idéntica a tts-1
  • Precio: Idéntico a tts-1
  • Motor: Mismo que tts-1

Velocidad 0.25–4.0

El parámetro speed permite ajustar la tasa de habla entre 0.25 y 4.0. El valor predeterminado es 1.0. Ajustar la velocidad es útil para adaptar el audio a dispositivos con limitaciones de ancho de banda o para mejorar la comprensión en entornos ruidosos.

Velocidades menores a 1.0 aumentan la duración del archivo generado, mientras que velocidades mayores la reducen. Esto afecta directamente el tiempo de transmisión en redes IoT y el consumo de memoria en el dispositivo receptor.

  • Rango: 0.25 a 4.0
  • Default: 1.0
  • Efecto: Ajusta duración y tamaño
  • Uso: Optimización de red o comprensión

Manejo de texto largo

Ilustración de onda de sonido para: Manejo de texto largo

Para textos extensos, la API requiere dividir el contenido en fragmentos de máximo 4096 caracteres por solicitud. Cada fragmento genera un archivo de audio independiente que debe gestionarse durante la integración.

Los archivos generados se unen para reproducir el texto completo. Esta estrategia evita límites de longitud en la entrada y garantiza que la síntesis se complete correctamente incluso para instrucciones largas de domótica.

División en partes

Envía texto de hasta 4096 caracteres por llamada POST. Si tu mensaje supera este límite, divídelo manualmente en la lógica de tu script antes de realizar las solicitudes consecutivas.

Unión de archivos de audio

La API devuelve un archivo de audio por cada solicitud exitosa. Para obtener el audio final, une los archivos binarios en el orden en que se generaron, respetando el formato seleccionado (mp3, wav, etc.).

Límite de caracteres

Cada solicitud individual acepta un máximo de 4096 caracteres. El conteo incluye espacios y puntuación. Exceder este valor en un solo cuerpo JSON provocará un error de validación.

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 paper (arXiv 2305.18802)
  3. Python documentation
  4. W3C WAI: making audio and video accessible
  5. MDN: Web Speech API
  6. openai-node on GitHub
  7. curl documentation
  8. LibriTTS-R corpus (OpenSLR 141)
  9. Creative Commons Attribution 4.0
  10. IETF RFC 7845: Ogg Opus
  11. FFmpeg documentation
  12. Tether (USDT)

Más en este sitio