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.mp3Python (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 | |
|---|---|
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 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
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
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
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
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
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_urlahttps://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
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

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