Documentación técnica para integrar voz en IoT

Por equipo editorial NodoVoz · Actualizado 2026-11-18

Esta guía técnica está diseñada para equipos de producto en domótica que necesitan integrar voz sintética en dispositivos IoT y aplicaciones sin complicaciones. Aquí encontrarás la documentación precisa para conectar tu backend a nuestra API de síntesis de voz, desde la obtención de la clave hasta la gestión de los límites de uso.

Descubre cómo enviar texto y recibir audio en formatos como MP3 o WAV, utilizando el endpoint estándar compatible con el SDK de OpenAI. Abordamos los parámetros de entrada, el manejo de errores y la forma de integrar las voces disponibles en tus flujos de trabajo de automatización del hogar.

Documentación técnica para integrar voz en IoT

Preguntas frecuentes

¿Qué es una clave API Bearer?

Es un token de autenticación que envías en el encabezado Authorization: Bearer tts-... para identificar tu cuenta. Cada cuenta tiene una clave activa que puedes revocar y emitir una nueva en cualquier momento. Esta clave es necesaria para realizar solicitudes a la API y se usa para facturación y control de acceso.

¿Cómo integro la API con Python?

Usa la librería requests o el SDK oficial de OpenAI modificando la base_url a https://api.play95y.com/v1. Envía una petición POST al endpoint /v1/audio/speech con tu clave Bearer. El cuerpo JSON debe incluir el modelo, texto, voz y formato deseado. Recibirás el archivo de audio directamente en la respuesta.

¿Cuál es el límite de caracteres por request?

Cada solicitud permite un máximo de 4096 caracteres en el campo input. Si tu texto es más largo, debes dividirlo en partes de este tamaño y unir los archivos de audio resultantes. Los espacios y la puntuación cuentan como caracteres. Este límite asegura una generación estable y predecible.

¿Qué formato de audio es mejor para IoT?

Para IoT, opus o mp3 son ideales por su equilibrio entre calidad y tamaño. wav y flac ofrecen mayor calidad pero usan más ancho de banda. pcm es sin comprimir. Elige según la capacidad de almacenamiento y procesamiento de tu dispositivo. Todos los formatos son válidos mediante el campo response_format.

¿Puedo usar la misma clave en varios dispositivos?

Sí, la clave API es válida para múltiples solicitudes simultáneas. Sin embargo, el límite de 60 peticiones por minuto se aplica por clave, no por dispositivo. Si muchos dispositivos usan la misma clave, compartirán ese cupo. Para mayor capacidad, emite una nueva clave o gestiona la cola localmente.

¿Qué ocurre si supero el límite de 60 rpm?

Las solicitudes adicionales pueden esperar en una cola si se supera el límite. No se pierden, solo se retrasan. El límite es de 60 peticiones por minuto por clave. Durante la prueba gratuita, el límite es de 10 rpm hasta el primer recargo.

¿Es compatible con la librería requests de Python?

Sí, la API responde a peticiones HTTP estándar. Puedes usar requests de Python para enviar el JSON con la clave Bearer. No necesitas un SDK propietario. Solo configura el encabezado Authorization y el cuerpo de la petición según la documentación del endpoint de speech. Es compatible con cualquier cliente HTTP.

¿Cómo obtengo la lista de voces disponibles?

Realiza una petición GET a /v1/voices. Este endpoint devuelve información sobre las 8 voces disponibles, los idiomas soportados y los formatos de audio. También puedes consultar /v1/models para detalles sobre los modelos tts-1 y tts-1-hd. La información incluye nombres como aria, nova y felix.

¿Qué significa el campo 'language' en la petición?

El campo language especifica el código ISO del idioma para la síntesis. Si no se proporciona, el sistema intenta adivinarlo desde el guión, asumiendo inglés para texto en latín. Para textos en otros idiomas con caracteres latinos, es recomendable establecerlo explícitamente para evitar errores de pronunciación.

¿Puedo generar audio en segundo plano?

La API es síncrona: envías la petición y esperas la respuesta con el audio. No hay streaming ni WebSockets para audio parcial. Puedes gestionar la generación en segundo plano desde tu aplicación cliente, haciendo la petición HTTP mientras tu interfaz muestra un indicador de carga. El servidor procesa las peticiones en cola.

¿Necesito un SDK propietario?

No. Puedes usar cualquier cliente HTTP o la SDK de OpenAI ajustando la URL base. No ofrecemos un SDK propio ni una aplicación móvil específica. La integración se realiza mediante peticiones REST estándar con autenticación Bearer. Esto facilita la integración en cualquier entorno de desarrollo de IoT.

¿Cómo se detecta el idioma automáticamente?

Si no envías el campo language, el sistema infiere el idioma basado en los caracteres del texto. El texto en latín se asume como inglés por defecto. Para otros idiomas, como japonés o chino, la detección suele ser precisa. Si el resultado no es el esperado, especifica el idioma ISO explícitamente.

¿Qué pasa si el servidor está lento?

Las solicitudes se procesan en orden. Si hay mucha carga, tu petición esperará en una cola. El tiempo de generación es aproximadamente el tiempo real del audio, más unos segundos para frases cortas. No hay garantía de tiempo de respuesta, pero las peticiones fallidas son gratuitas.

¿Hay versión beta de la API?

No se indica una versión beta específica. La API está disponible en la versión v1. Los modelos tts-1 y tts-1-hd están activos. No hay diferenciación de versiones. Si hay cambios, se notificarán en la documentación. La versión v1 es la estable para producción y pruebas.

Primera solicitud

curl

curl https://api.play95y.com/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.play95y.com/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.play95y.com/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 la clave API

Ilustración de onda de sonido para: Obtención de la clave API

Accede a /get-api-key/ para registrarte con Google o correo electrónico. Esta página centraliza tu clave, saldo y métricas de uso en tiempo real.

Registro en la plataforma

Registro en la plataforma

Crea tu cuenta en la plataforma para obtener acceso inmediato. Los usuarios con Google reciben $0.50 de crédito de prueba válido por 7 días.

Generación de clave Bearer

Generación de clave Bearer

La plataforma genera una clave única que debes enviar en el encabezado Authorization: Bearer. Esta credencial autenticará todas tus solicitudes de síntesis.

Gestión de claves activas

Mantén una sola clave activa por cuenta. Si la revocas o generas una nueva, la anterior deja de funcionar instantáneamente, asegurando el control de acceso.

Endpoint principal de síntesis

Ilustración de onda de sonido para: Endpoint principal de síntesis

El endpoint principal /v1/audio/speech acepta texto y devuelve un archivo de audio sintetizado. Funciona enviando una petición POST con un cuerpo JSON que incluye el modelo, el texto de entrada, la voz deseada y el formato de salida.

Es compatible con los SDKs oficiales de OpenAI si se ajusta la base_url a https://api.play95y.com/v1. Este diseño permite integrar la voz en dispositivos IoT y apps sin aprender una API nueva desde cero.

Método POST /v1/audio/speech

Envía texto al servidor y recibe un archivo de audio. El proceso es asíncrono; para textos largos, se deben dividir en fragmentos de hasta 4096 caracteres y unir los resultados.

Formato JSON requerido

La petición debe incluir los campos obligatorios: model ("tts-1" o "tts-1-hd"), input (texto), voice (uno de los 8 presets) y response_format.

  • model: "tts-1" o "tts-1-hd"
  • input: string (máx. 4096 caracteres)
  • voice: aria, nova, luna, sage, felix, milo, atlas, orion
  • response_format: mp3, wav, opus, flac, pcm
  • speed: número (0.25–4.0)
  • language: código ISO (opcional)

Parámetros de entrada

El parámetro input contiene el texto a sintetizar. Si no se especifica language, el sistema intenta adivinarlo, aunque se recomienda definirlo explícitamente para textos en latinos distintos al inglés.

Ejemplo con cURL

Ilustración de onda de sonido para: Ejemplo con cURL

Para probar la síntesis de voz desde tu terminal, utiliza el siguiente comando curl. Este ejemplo envía un texto corto en español y recibe el archivo de audio directamente en tu máquina.

Código de ejemplo listo

```bash curl -X POST "https://api.play95y.com/v1/audio/speech" \ -H "Authorization: Bearer tts-tu_clave_aqui" \ -H "Content-Type: application/json" \ -d '{"model": "tts-1", "input": "Bienvenido a casa", "voice": "nova", "response_format": "mp3"}' \ --output saludo.mp3 ```

Reemplazo de la clave API

Sustituye tts-tu_clave_aqui por tu clave Bearer real. Puedes obtenerla en la sección de tu panel tras registrarte. Asegúrate de que tu cuenta tenga saldo o crédito de prueba activo.

Descarga del audio

El archivo generado se guardará localmente como saludo.mp3. Si la solicitud falla, no se cobra. Verifica el código de estado HTTP para confirmar el éxito de la síntesis.

Integración con OpenAI SDK

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

La API de NodoVoz mantiene la misma estructura de cuerpo de solicitud que el endpoint de speech de OpenAI, lo que permite reutilizar el SDK oficial sin necesidad de modificar la lógica de serialización de tu aplicación IoT.

Esto simplifica la integración en dispositivos con recursos limitados, ya que puedes mantener tu código de cliente limpio y familiar, aprovechando las librerías que ya conoces para manejar las respuestas de audio.

Uso del SDK oficial

Simplemente importa el cliente de OpenAI en tu proyecto y configura la autenticación con tu clave Bearer (tts-...). El formato JSON de entrada (model, input, voice) es idéntico al estándar de OpenAI, por lo que no necesitas aprender una nueva sintaxis de parámetros.

  • Reutiliza el código existente de clientes OpenAI.
  • Formato JSON de entrada idéntico al estándar.

Cambio de base_url

La única configuración técnica necesaria es apuntar el cliente a nuestra infraestructura. Establece la propiedad base_url como https://api.play95y.com/v1 al inicializar la instancia del cliente. Esto redirige todas las solicitudes al endpoint correcto de síntesis de voz.

  • Configura base_url a https://api.play95y.com/v1.
  • Funciona con SDKs de Python, Node.js, Go y otros lenguajes compatibles con HTTP.

Compatibilidad de librerías

Al ser una API RESTful con formato OpenAI-compatible, las librerías oficiales de OpenAI para Python, JavaScript y otros lenguajes funcionan directamente. No requiere un SDK propietario ni dependencias adicionales específicas de NodoVoz.

  • Compatible con SDKs oficiales de OpenAI.
  • Sin librerías propietarias adicionales.

Formatos de audio soportados

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

El endpoint POST /v1/audio/speech acepta mp3, wav, opus y flac mediante el parámetro response_format. La elección depende del dispositivo IoT: MP3 es eficiente para redes móviles, mientras que WAV o FLAC preservan la fidelidad para altavoces domóticos.

Los formatos de pérdida como MP3 y Opus reducen el ancho de banda, ideal para respuestas rápidas en apps. WAV y FLAC son sin pérdida, útiles si el dispositivo procesa audio sin compresión adicional.

MP3 para streaming ligero

MP3 es un formato ligero y compatible universalmente. Ideal para dispositivos con ancho de banda limitado o respuestas en tiempo real en apps móviles.

  • Tamaño de archivo reducido
  • Decodificación rápida en hardware barato

WAV para alta calidad

WAV ofrece audio sin pérdida de calidad, perfecto para altavoces domóticos de alta fidelidad o pruebas de prototipos donde la claridad es crítica.

  • Sin compresión
  • Formato estándar en procesamiento de audio

FLAC y Opus disponibles

FLAC ofrece compresión sin pérdida, ideal para almacenamiento eficiente sin sacrificar calidad. Opus es eficiente para redes inestables, manteniendo claridad de voz.

  • FLAC: sin pérdida, eficiente
  • Opus: alta eficiencia en banda ancha limitada
Formatos de audio soportados

Límites y cuotas

Ilustración de onda de sonido para: Límites y cuotas

La API está diseñada para equilibrar capacidad y estabilidad. Cada clave activa permite 60 solicitudes por minuto, lo que facilita la integración en dispositivos IoT sin saturar el servicio.

Para textos largos, es necesario dividirlo en fragmentos de hasta 4096 caracteres. Cada fragmento se sintetiza por separado y debe unirse en el cliente para obtener el audio completo.

60 solicitudes por minuto

El límite estándar es de 60 solicitudes por minuto por clave. Antes de la primera recarga, el límite es de 10 solicitudes por minuto.

Este límite se aplica por clave API activa. Si generas una nueva clave, la anterior deja de funcionar inmediatamente.

4096 caracteres por petición

Cada solicitud puede contener un máximo de 4096 caracteres, incluyendo espacios y puntuación. Si tu texto excede este límite, debes dividirlo en partes más pequeñas.

La velocidad de generación es de aproximadamente 25 caracteres de texto por segundo de audio generado. Los textos largos tardan más, pero la generación es aproximadamente en tiempo real.

Cola de procesamiento

Las solicitudes se procesan una tras otra. Si hay muchas peticiones simultáneas, algunas pueden esperar en una cola.

Esto puede aumentar el tiempo de respuesta durante picos de carga, pero no afecta la calidad del audio generado.

Manejo de errores

Ilustración de onda de sonido para: Manejo de errores

La API devuelve códigos de estado HTTP estándar para indicar el resultado de cada solicitud. Un 200 confirma que el audio se generó correctamente, mientras que códigos 4xx o 5xx indican problemas de autenticación, límites superados o errores del servidor.

Códigos de estado HTTP

Utiliza los encabezados de respuesta para manejar flujos asíncronos en tus dispositivos IoT. Los errores de rate limit (429) son comunes si superas las 60 solicitudes por minuto.

Solicitudes fallidas sin costo

Si la síntesis falla por un error interno, el cargo se devuelve completamente. Esto asegura que no pagues por audio no entregado, manteniendo tu saldo intacto para las siguientes intentos.

Mensajes de depuración

Cada respuesta de error incluye información sobre el estado, facilitando la identificación de problemas.

Endpoint de voces y modelos

Ilustración de onda de sonido para: Endpoint de voces y modelos

GET /v1/voices para listar

Usa GET /v1/voices para obtener el catálogo completo. La respuesta incluye los 8 presets disponibles, sus idiomas soportados, formatos y precio. Puedes filtrar por language para asegurar la compatibilidad con tus dispositivos IoT.

Este endpoint te permite verificar qué voces están disponibles en tiempo real sin necesidad de adivinar los nombres o códigos.

  • Lista las 8 voces (Aria, Nova, Luna, Sage, Felix, Milo, Atlas, Orion).
  • Muestra los 23 idiomas soportados y sus códigos ISO.
  • Incluye los formatos de audio disponibles por voz.

GET /v1/models para detalles

El endpoint GET /v1/models devuelve la lista de modelos disponibles, actualmente tts-1 y tts-1-hd. Ambos usan el mismo motor de síntesis y tienen el mismo precio, pero tts-1-hd ofrece una calidad de audio superior.

Este endpoint es útil para verificar la disponibilidad del servicio antes de enviar solicitudes de síntesis en tu pipeline de IoT.

  • Modelo tts-1: estándar, ideal para latencia baja.
  • Modelo tts-1-hd: alta calidad, ideal para anuncios o narración.
  • Precio idéntico para ambos modelos.

Formatos y precios por voz

El precio es uniforme: $0.01 por cada 1.000 caracteres, sin importar la voz o el modelo elegido. Los formatos soportados son MP3, WAV, OPUS, FLAC y PCM. Elige el formato según las capacidades de tu dispositivo IoT.

Recuerda que el texto se cuenta incluyendo espacios y puntuación. No hay cargos adicionales por el formato de audio seleccionado.

  • Precio: $10 por 1 millón de caracteres.
  • Formatos: MP3, WAV, OPUS, FLAC, PCM.
  • Sin cargos por formato ni por voz específica.

Escucha las 8 voces

Cada muestra a continuación fue generada por esta API a partir de la misma frase. Necesitamos diseñar experiencias intuitivas que conecten dispositivos inteligentes sin fricción.

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. FFmpeg documentation
  3. openai-python on GitHub
  4. OpenAI API reference: create speech
  5. MDN: Web Speech API
  6. curl documentation
  7. LibriVox public-domain audiobooks
  8. LibriTTS-R paper (arXiv 2305.18802)
  9. LibriTTS-R corpus (OpenSLR 141)
  10. Creative Commons Attribution 4.0
  11. TRON developer hub: TRC-20
  12. Tether (USDT)

Más en este sitio