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.mp3Python (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 | |
|---|---|
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 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
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
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
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
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
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
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
voicesea una de las 8 presets válidas

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