Preguntas frecuentes
¿Qué es una API?
Es una interfaz que permite enviar texto y recibir un archivo de audio. Funciona como un servicio en la nube donde tu aplicación envía una solicitud JSON y obtiene el resultado de síntesis de voz, integrando audio en tus proyectos sin necesidad de gestionar servidores de audio complejos.
¿Cómo obtengo una clave API?
Regístrate en la página /get-api-key/ usando Google o correo electrónico. Una vez creado el cuenta, la página mostrará tu clave activa, el saldo y un ejemplo de uso. Si necesitas una nueva clave, puedes emitirla en cualquier momento; la anterior dejará de funcionar inmediatamente.
¿Qué es el base_url?
Es la dirección base para las solicitudes HTTP. Para esta API, debes usar https://api.playok59.com/v1. Si usas el SDK de OpenAI, solo necesitas cambiar este valor base para que las solicitudes se dirijan correctamente a nuestro servicio de síntesis de voz.
¿Puedo usar el SDK de OpenAI?
Sí, la forma de la solicitud es idéntica al endpoint de speech de OpenAI. Solo necesitas configurar el base_url a https://api.playok59.com/v1 y usar tu clave API. Esto permite reutilizar el código existente sin modificar la lógica principal de tu aplicación.
¿Qué formatos de audio soporta?
Soporta mp3, wav, opus, flac y pcm. Puedes especificar el formato deseado en el campo response_format de tu solicitud JSON. Esto te permite elegir el balance adecuado entre calidad de audio y tamaño del archivo según las necesidades de tu proyecto.
¿Cuál es el límite de caracteres?
Cada solicitud puede contener hasta 4096 caracteres. 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 dentro de este límite.
¿Qué pasa si excedo los límites?
Si excedes el límite de 4096 caracteres en una sola solicitud, esta será rechazada. Para textos largos, la estrategia recomendada es dividir el texto en fragmentos manejables y procesarlos secuencialmente, uniendo luego los archivos de audio generados para crear el archivo final.
¿Cómo se autentica la solicitud?
Incluye tu clave API en el encabezado Authorization como un token Bearer. El formato es: Authorization: Bearer tts-... . Cada cuenta tiene una clave activa; si emites una nueva, la anterior deja de funcionar inmediatamente, asegurando que solo uses la válida.
¿Qué es el modelo tts-1-hd?
Es uno de los dos modelos disponibles, junto con tts-1. Ambos utilizan el mismo motor de síntesis y tienen el mismo precio. La elección entre ellos no afecta el costo, ya que comparten el mismo motor y precio.
¿Es compatible con Python?
Sí, es totalmente compatible. Puedes usar el SDK oficial de OpenAI para Python configurando el base_url correctamente. También puedes realizar solicitudes HTTP estándar usando bibliotecas como requests. Esto facilita la integración rápida en proyectos de desarrollo backend o scripts de automatización.
¿Cómo manejo los errores?
Las solicitudes fallidas no tienen costo y el cargo se devuelve íntegramente. Si la síntesis falla, recibirás una respuesta de error con el código de estado. Verifica tu saldo y la validez de tu clave API si los errores persisten durante varias solicitudes.
¿Qué es la cola de procesamiento?
Las solicitudes se procesan una tras otra. Bajo carga, una solicitud puede esperar en una cola antes de comenzar la generación. Esto explica por qué textos largos tardan aproximadamente un tiempo real, mientras que las frases cortas pueden tardar unos segundos adicionales.
¿Puedo usar cURL?
Sí, cURL es una herramienta ideal para probar la API. La página /get-api-key/ proporciona un ejemplo de comando cURL listo para usar. Solo necesitas reemplazar la clave de ejemplo con tu clave API activa y ajustar el texto de entrada en el cuerpo JSON.
¿Dónde están las voces disponibles?
Puedes consultar la lista completa de voces, idiomas y formatos en el endpoint GET /v1/voices. Allí encontrarás los ocho presets disponibles, junto con los idiomas soportados por cada una.
Primera solicitud
curl
curl https://api.playok59.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.playok59.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.playok59.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 |
Inicio rápido
Comienza integrando la API de texto a voz en tu proyecto. Regístrate en nuestra plataforma para obtener una clave API única y empezar a generar audio inmediatamente. El proceso es simple y está diseñado para que los desarrolladores independientes configuren la accesibilidad sin fricción técnica.
Una vez tengas tu clave, puedes probar la integración con un simple comando cURL o utilizando las librerías oficiales de OpenAI. Nuestra API sigue un estándar familiar, lo que facilita la transición y la implementación rápida en tus aplicaciones web.
Obtén tu clave API
Accede a la página de registro con Google o correo electrónico para generar tu primera clave de API. Recibirás un crédito de prueba inicial para validar el servicio antes de realizar cualquier depósito.
La clave se genera instantáneamente y puede revocarse en cualquier momento si es necesario, garantizando que tu integración esté lista para producción desde el primer momento.
- Regístrate en /get-api-key/ con Google o email.
- La clave se emite al instante.
- Crédito de prueba disponible para validación.
Primer ejemplo en cURL
Envía tu primer texto a audio con este comando básico. Reemplaza tu_clave con tu token real y ajusta el texto de entrada según tus necesidades. El endpoint devuelve el archivo de audio directamente en la respuesta.
Este ejemplo utiliza el modelo estándar y el formato MP3, ideal para pruebas rápidas de integración en entornos de desarrollo.
- POST https://api.playok59.com/v1/audio/speech
- Body: JSON con input, voice y model.
- Response: archivo de audio binario.
Configuración básica
Asegúrate de que tu cliente HTTP maneje correctamente las respuestas binarias. La API devuelve el audio en el formato solicitado, sin necesidad de parsing complejo de JSON para el contenido final.
Para proyectos que requieren mayor control, puedes ajustar la velocidad y el idioma explícitamente, aunque el sistema detectará el idioma automáticamente si no se especifica.
- Usa Authorization: Bearer YOUR_KEY
- Soporte para múltiples lenguajes.
- Detección automática de idioma.
Endpoints principales
La API de Oído expone tres puntos de conexión RESTful que cubren desde la generación de audio hasta la consulta de metadatos. Cada endpoint sigue estándares claros para facilitar la integración en proyectos de accesibilidad y lectura asistida.
Los desarrolladores pueden generar archivos de audio y consultar la lista de voces y modelos disponibles. La estructura de las respuestas facilita la automatización de flujos de trabajo sin necesidad de adaptadores complejos.
POST /v1/audio/speech
Este es el endpoint principal para convertir texto en audio. Envías una solicitud JSON con el texto y las preferencias de síntesis, y recibes el archivo de audio generado directamente en la respuesta.
El cuerpo de la solicitud incluye el modelo (tts-1 o tts-1-hd), el texto de entrada (máximo 4096 caracteres), la voz deseada y el formato de salida. Si el texto excede el límite, debes dividirlo y unir los resultados.
- Endpoint: POST https://api.playok59.com/v1/audio/speech
- Formato de respuesta: Audio binario (mp3, wav, opus, flac, pcm)
- Límite: 4096 caracteres por solicitud
GET /v1/voices
Utiliza este endpoint para obtener la lista completa de voces disponibles, junto con sus idiomas y formatos soportados. La información es útil para construir interfaces de usuario dinámicas que permitan a los usuarios seleccionar su voz preferida.
El endpoint devuelve información sobre voces, idiomas, formatos y precios, permitiendo a los desarrolladores calcular costos antes de realizar la síntesis. Esto es especialmente útil en aplicaciones que ofrecen opciones como tts-1-hd.
- Endpoint: GET https://api.playok59.com/v1/voices
- Incluye: nombre de voz, idiomas, formatos y precio
- Voces: aria, nova, luna, sage, felix, milo, atlas, orion
GET /v1/models
Este endpoint devuelve la lista de modelos de síntesis disponibles. Actualmente, el API ofrece dos modelos: tts-1 y tts-1-hd, ambos con el mismo motor y el mismo precio.
Consultar este endpoint ayuda a verificar la disponibilidad de modelos en tiempo real y a asegurarse de que la integración esté utilizando las últimas versiones del servicio de texto a voz.
- Endpoint: GET https://api.playok59.com/v1/models
- Modelos: tts-1, tts-1-hd
- Uso: Verificar disponibilidad y versiones
Uso con SDK de OpenAI
La API de Oído reproduce la forma de solicitud del endpoint de speech de OpenAI, lo que permite usar los SDK oficiales con un cambio mínimo de configuración. Solo necesitas ajustar la URL base para que apunte a nuestro servicio.
Cambio de base_url
Para integrar Oído, simplemente reemplaza la URL base de tu cliente de OpenAI por https://api.playok59.com/v1. Esto redirige las solicitudes directamente a nuestro endpoint, manteniendo la misma estructura de datos que ya conoces.
- URL base: https://api.playok59.com/v1
- Mismo formato JSON que OpenAI
Compatibilidad total
Los SDK de OpenAI funcionan sin modificaciones adicionales. Solo necesitas proporcionar tu clave API de Oído en la cabecera de autorización y definir el modelo deseado en el cuerpo de la petición.
Ejemplo de código
Aquí tienes un ejemplo básico en Python usando la biblioteca oficial de OpenAI:
- import openai
- client = openai.OpenAI(base_url="https://api.playok59.com/v1", api_key="tts-TU_CLAVE")
- response = client.audio.speech.create(
- model="tts-1",
- voice="nova",
- input="Hola, esta es una prueba."
- )
Parámetros de solicitud
Los parámetros de solicitud definen cómo se procesa tu texto y se genera el audio. La estructura es idéntica a la de OpenAI, lo que facilita la integración inmediata en proyectos existentes sin necesidad de aprender una sintaxis nueva.
Cada campo determina el modelo de voz, el formato de salida y el idioma, asegurando que el resultado final se adapte exactamente a las necesidades de tu aplicación de accesibilidad o lectura asistida.
Modelo tts-1
El modelo estándar ofrece una buena relación calidad-precio para la mayoría de los casos de uso. Es suficiente para narraciones, lectores de pantalla y aplicaciones cotidianas donde el volumen de texto es alto.
- Precio estándar: $10 por 1 millón de caracteres.
Modelo tts-1-hd
Proporciona una calidad de audio superior con menos artefactos, ideal para proyectos donde la claridad del habla es crítica. Aunque el precio es el mismo, es más adecuado para contenido breve o destacado.
- Ideal para instrucciones precisas o contenido educativo.
Voces y idioma
Puedes elegir entre 8 voces predefinidas que cubren registros desde narrativo hasta conversacional. Si el texto está en un idioma distinto al inglés y usa alfabeto latino, debes especificar el parámetro language para evitar que el sistema adivine incorrectamente.
- 8 voces disponibles (ej. aria, nova, atlas).
- Soporte para 23 idiomas específicos.
- El campo
languagees opcional pero recomendado para textos en latín no ingleses.
Formatos de audio
Elige el formato que mejor se ajuste a tu aplicación. MP3 es ideal para la mayoría de casos por su equilibrio entre calidad y tamaño, mientras que WAV ofrece audio sin pérdida para grabaciones o edición posterior.
MP3
Formato comprimido con amplia compatibilidad nativa en todos los dispositivos y navegadores. Es la opción más eficiente para almacenar y transmitir audio en aplicaciones web o móviles.
WAV
Audio sin pérdida que conserva todos los detalles de la síntesis. Ideal si necesitas editar el archivo posteriormente o necesitas la máxima fidelidad sin compresión.
Opus y FLAC
Opus ofrece compresión eficiente para streaming o uso en redes móviles. FLAC proporciona audio sin pérdida con compresión, ideal para archivado sin pérdida de espacio significativo.

Límites y rendimiento
La API está diseñada para ser predecible y justa, con límites claros que evitan sorpresas en la integración. Conocer estos parámetros técnicos te permite ajustar tu lógica de envío y garantizar que tus usuarios reciban el audio sin interrupciones molestas.
Entender cómo se gestionan las colas y los caracteres te ayuda a optimizar el flujo de trabajo, especialmente si procesas textos largos o tienes picos de uso puntuales en tus aplicaciones de accesibilidad.
60 solicitudes por minuto
El límite estándar es de 60 solicitudes por minuto por clave. Antes de tu primera recarga, este límite se reduce a 10 por minuto para prevenir abusos en la cuenta gratuita. Si superas el límite, recibirás un error 429 hasta que el contador se reinicie.
4096 caracteres por petición
Cada solicitud puede contener hasta 4096 caracteres, incluyendo espacios y puntuación. Para textos más largos, tu aplicación debe dividir el contenido en fragmentos de este tamaño, generar el audio para cada parte y unirlos. Esto mantiene la latencia baja y evitamos tiempos de espera excesivos.
Cola de procesamiento
Las solicitudes se procesan en orden de llegada. En la mayoría de los casos, la generación es casi en tiempo real (aproximadamente 25 caracteres por segundo), pero bajo alta demanda, las peticiones pueden entrar en una cola temporal. Esto asegura que cada archivo se genere correctamente sin pérdida de calidad.
Códigos de error
La API devuelve códigos de estado HTTP claros para que depures tus integraciones sin ambigüedades. Conocer estos errores te ahorra tiempo de desarrollo y evita sorpresas en la facturación.
Error 400
Indica que la solicitud tiene un formato incorrecto. Revisa que el JSON tenga los campos requeridos y que el texto no supere los 4096 caracteres. Si el modelo o la voz no existen, también aparecerá este código.
Error 401
Significa que la clave API es inválida o ha sido revocada. Si emitiste una nueva clave, la anterior deja de funcionar al instante. Verifica que tu cabecera Authorization contenga el prefijo Bearer correcto.
Error 429
Avisa que has excedido el límite de 60 solicitudes por minuto. No se te cobrará si la síntesis falla. Espera unos segundos y reintenta la petición o revisa tu historial de uso.
Autenticación
La autenticación en Oído API es directa y sigue el estándar de seguridadBearer. Cada solicitud HTTP debe incluir una cabecera específica que verifica tu identidad y autoriza el uso de tu cuota de caracteres.
Solo necesitas una clave activa por cuenta. Si generas una nueva, la anterior deja de funcionar inmediatamente, lo que simplifica la gestión de seguridad sin complicaciones técnicas ni múltiples tokens pendientes.
Cabecera Authorization
Envía la cabecera Authorization en cada petición POST o GET. El formato es estrictamente Bearer seguido de un espacio y tu clave única. Si omites esta cabecera o es incorrecta, la API rechazará la solicitud con un error 401.
Asegúrate de que la clave se envíe exactamente como la generaste, sin espacios adicionales ni saltos de línea invisibles que puedan alterar la validación del servidor.
- - Cabecera:
Authorization: Bearer tts-tu_clave_aqui - - Obligatoria en todos los endpoints
- - Sensible a mayúsculas/minúsculas
Formato de la clave
Las claves de API comienzan siempre por el prefijo tts- seguido de una secuencia alfanumérica. Este formato permite a la API distinguir rápidamente tus credenciales de otros parámetros de la solicitud.
No necesitas codificar la clave en Base64 ni usar firmas complejas. El formato es texto plano listo para ser insertado directamente en tu código o herramientas como cURL.
- - Prefijo fijo:
tts- - - Caracteres alfanuméricos
- - Sin caracteres especiales
Gestión de claves
Tienes una sola clave activa por cuenta. Si sospechas que ha sido expuesta o simplemente quieres renovarla, puedes emitir una nueva desde tu panel de control. Al hacerlo, la clave anterior deja de funcionar al instante.
No hay período de transición. Si cambias de clave, actualiza todas tus integraciones inmediatamente para evitar interrupciones en el servicio de síntesis de voz.
- - Una clave activa por cuenta
- - La anterior se invalida al instante
- - Emisión ilimitada
Escucha las 8 voces
Cada muestra a continuación fue generada por esta API a partir de la misma frase. Haz que tu juego sea accesible para personas con dislexia desde el inicio.
23 idiomas
Cualquier voz puede hablar cualquiera de estos idiomas.
Fuentes y lecturas adicionales
- Wikipedia
- Node.js documentation
- ISO 639 language codes
- TRON developer hub: TRC-20
- LibriTTS-R paper (arXiv 2305.18802)
- LibriTTS-R corpus (OpenSLR 141)
- W3C WAI: making audio and video accessible
- openai-node on GitHub
- FFmpeg documentation
- openai-python on GitHub
- MDN: Web Speech API
- OpenAI API reference: create speech
