Preguntas frecuentes
¿Qué es la accesibilidad en apps?
Es la práctica de diseñar aplicaciones para que personas con discapacidades visuales o cognitivas puedan usarlas. La API de Oído permite convertir texto en audio, facilitando la lectura asistida y mejorando la experiencia de usuario para personas con dislexia o dificultades de lectura, sin requerir componentes visuales complejos.
¿Cómo elijo la voz correcta?
Elige entre 8 presets según el tono: Aria (narradora), Nova (alegre), Luna (historias), Sage (instruccional), Felix (promocional), Milo (conversacional), Atlas (noticias) o Orion (documental). Todas hablan los 23 idiomas soportados. Si el texto no es inglés en latín, especifica el campo language para evitar errores de pronunciación.
¿Cuánto tarda en generarse el audio?
Típicamente, la generación es casi en tiempo real: unos 25 caracteres por segundo para textos largos. Las frases cortas pueden tardar unos segundos adicionales. Las solicitudes se procesan en cola, por lo que bajo carga alta podría haber una pequeña espera antes de comenzar la síntesis.
¿Puedo guardar el audio generado?
La API devuelve el audio en la respuesta, pero no lo almacena en sus servidores. Tú eres responsable de guardar los archivos en tu propia infraestructura. Puedes solicitar formatos como mp3, wav, opus, flac o pcm según tus necesidades de almacenamiento y reproducción.
¿Qué es el caché de audio?
No es una función nativa de la API. El caché depende de cómo tu aplicación gestione las respuestas HTTP. Si tu app guarda los archivos de audio generados localmente o en un CDN, evitarás solicitar el mismo texto repetidamente, optimizando costos y latencia en tu integración.
¿Cómo manejo textos largos?
Debes dividir el texto en partes de máximo 4096 caracteres por solicitud. Luego, envía cada fragmento a la API y une los archivos de audio resultantes en tu aplicación. Esto asegura que cada solicitud cumpla con los límites de longitud establecidos por el endpoint de speech.
¿Es necesario usar HTTPS?
Sí, es recomendable para la seguridad de tus claves API y datos. La API está disponible en https://api.playok59.com/v1. Aunque no es estrictamente obligatorio por la API, el uso de HTTPS es el estándar para proteger la transmisión de tus credenciales y payloads JSON.
¿Qué lenguajes de programación soporta?
Cualquiera que pueda enviar solicitudes HTTP POST con un cuerpo JSON. Funciona con el SDK oficial de OpenAI cambiando la base_url, o con cualquier librería HTTP estándar. No tenemos un SDK propio, pero la compatibilidad es universal para cualquier entorno que soporte JSON.
¿Cómo pruebo la API antes de pagar?
Regístrate con Google para obtener una prueba gratuita de $0.50 (aprox. 50 000 caracteres) válida por 7 días. Si usas email y contraseña, no hay crédito inicial. Puedes usar este saldo para probar la integración y verificar que el audio generado cumple con tus requisitos antes de recargar.
¿Qué es la tasa de bits?
Se refiere a la calidad de audio en bits por segundo, determinada por el formato elegido (mp3, wav, opus, flac, pcm). El formato mp3 es eficiente en tamaño, mientras que wav o flac ofrecen mayor calidad sin pérdida. Elige el formato que mejor equilibre la calidad de audio y el ancho de banda de tu app.
¿Puedo usar la API en segundo plano?
Sí, la API es asíncrona. Envías una solicitud POST y recibes el archivo de audio. Puedes procesar múltiples solicitudes en paralelo o en cola desde tu servidor. Las solicitudes se procesan en secuencia, por lo que la velocidad depende de la cola de procesamiento.
¿Cómo mido el éxito de la integración?
Mide la latencia de respuesta, la tasa de éxito de las solicitudes y el ahorro en tiempo de lectura para tus usuarios. Monitorea el uso de caracteres frente a tu saldo. La API proporciona metadatos de tiempo y estado para que puedas auditar el rendimiento de tus integraciones.
¿Qué hacer si falla una solicitud?
Si la síntesis falla, no se cobra el carácter. Verifica que el texto esté dentro de los 4096 caracteres y que el formato sea válido. Revisa tu clave API y los límites de tasa (60 req/min). Si el error persiste, revisa la documentación o contacta por email.
¿Es escalable la API?
La API soporta el volumen necesario para proyectos independientes. Tienes un límite de 60 solicitudes por minuto por clave. Si necesitas más capacidad, puedes emitir una nueva clave (la anterior deja de funcionar al instante) o distribuir la carga. No hay planes de suscripción ni límites de ancho de banda fijos más allá de la tasa.
Preparación del proyecto
Antes de escribir la primera línea de código, es clave definir qué necesitas: ¿texto para accesibilidad web, audiolibros o notificaciones? Conocer el volumen de caracteres y los idiomas requeridos te ayuda a elegir la velocidad y el formato de audio adecuados desde el inicio.
Seleccionar API Oído API está diseñada para integrarse fácilmente usando SDKs compatibles con OpenAI. Oído API es compatible con el SDK oficial de OpenAI (cambiando la base_url) o con cualquier librería HTTP estándar, lo que simplifica la conexión técnica para desarrolladores independientes.
Definir necesidades
Identifica si tu proyecto requiere formatos como MP3 para web o WAV para alta fidelidad. Ten en cuenta que cada solicitud tiene un límite de 4096 caracteres, por lo que deberás gestionar textos más largos dividiéndolos en partes.
La claridad de las voces y la velocidad ajustable son factores clave para la experiencia del usuario final, especialmente en proyectos de accesibilidad y dislexia.
Seleccionar API
Oído API es compatible con el SDK oficial de OpenAI (cambiando la base_url) o con cualquier librería HTTP estándar. Esta compatidad evita aprender sintaxis nuevas y permite usar herramientas que ya conoces.
No necesitas SDKs propietarios ni plugins específicos; una simple petición POST es suficiente para obtener audio sintético de alta calidad.
Crear cuenta
Visita la página /get-api-key/ y regístrate con Google o correo electrónico. Esto te dará acceso inmediato a la consola donde verás tu clave API, saldo y uso.
Si usas Google, recibirás un crédito de prueba de $0.50 válido por 7 días para realizar tus primeras pruebas sin costo adicional.
Obtención de la clave API
Para empezar, accede a la página de registro en playok59.com. Puedes crear tu cuenta usando Google o proporcionando un correo electrónico y contraseña. Esta cuenta es específica para este sitio y te permitirá acceder a tu panel de control personal.
Registro en el sitio
El proceso es directo y no requiere validación bancaria inmediata. Una vez registrado, tendrás acceso al panel donde se gestionan tus credenciales y el saldo inicial.
Generación de clave
Desde tu panel, genera una clave API que comienza con 'tts-'. Esta única clave activa se usa para todas las solicitudes. Si la revocas, la anterior deja de funcionar al instante.
- Una clave activa por cuenta
- Uso en cabecera Authorization: Bearer
- Revocación inmediata al generar nueva
Almacenamiento seguro
Guarda tu clave en variables de entorno, no en el código fuente visible. Esto previene exposiciones accidentales en repositorios públicos o en la versión cliente de tus aplicaciones.
Primera solicitud
Una vez que tienes tu clave y conoces los extremos, el siguiente paso es enviar tu primera solicitud. La API espera una petición POST a https://api.playok59.com/v1/audio/speech con un cuerpo JSON bien formado. Es fundamental que el texto no supere los 4096 caracteres por petición.
La estructura es simple: especificas el modelo, el texto a convertir y la voz deseada. La API procesa la solicitud y devuelve el archivo de audio generado directamente en la respuesta, listo para ser reproducido o almacenado en tu aplicación.
Estructura JSON
El cuerpo de la solicitud debe ser un objeto JSON que contenga los parámetros esenciales. Utiliza el campo input para el texto, voice para la voz seleccionada y model para elegir entre 'tts-1' o 'tts-1-hd'.
Asegúrate de incluir el encabezado Authorization: Bearer tts-... con tu clave única. Si no especificas un idioma, el sistema asume inglés para texto en latín; es recomendable definirlo explícitamente para otros idiomas.
model: "tts-1" o "tts-1-hd".input: tu texto (máx. 4096 caracteres).voice: una de las 8 voces disponibles.response_format: mp3, wav, opus, flac o pcm.
Parámetros básicos
Los parámetros mínimos son el modelo, la entrada de texto y la voz. Puedes ajustar la velocidad con el parámetro speed, que acepta valores entre 0.25 y 4.0. Esto es útil para adaptar la lectura a necesidades de accesibilidad, como en casos de dislexia.
El campo language es opcional pero recomendado. Si no se establece, el sistema asume inglés para texto en latín. Definirlo explícitamente evita errores de pronunciación en otros idiomas soportados.
- Velocidad: 0.25 a 4.0.
- Idioma: código ISO opcional.
- Formato: mp3, wav, opus, flac, pcm.
Respuesta exitosa
Si la solicitud es válida, la API devuelve el archivo de audio binario directamente en el cuerpo de la respuesta HTTP. No se almacena nada en nuestros servidores; solo conservamos metadatos para facturación.
El código de estado será 200 OK. El archivo generado puede ser reproducido inmediatamente o guardado. Si la síntesis falla, no se cobra y recibirás un código de error describiendo el problema.
- Código 200 con audio binario.
- Sin almacenamiento del audio generado.
- Cobro solo en éxito.
Manejo de errores
La API devuelve códigos de estado HTTP claros para indicar el resultado de cada síntesis. Un 200 significa que el audio está listo, mientras que un 4xx indica problemas con la clave o los parámetros enviados.
Manejar estos códigos permite que tu aplicación reaccione de forma adecuada sin bloquearse, asegurando una experiencia fluida para los usuarios finales.
Códigos de estado
Los errores comunes incluyen 401 (clave inválida) y 429 (límite de velocidad alcanzado, 60 req/min).
- 400: Parámetros incorrectos (ej. texto vacío).
- 401: Clave de API ausente o incorrecta.
- 429: Excedido el límite de 60 solicitudes por minuto.
- 500: Error interno del servicio.
Reintento automático
Implementa una lógica de reintento con backoff exponencial para errores 429 o 500. Espera breves intervalos entre intentos para evitar saturar la cola de procesamiento.
- Reintenta solo en errores transitorios.
- Usa retardos crecientes (exponencial).
- Límite máximo de reintentos recomendado: 3.
Registros (logs)
Registra el código de estado, el mensaje de error y la solicitud enviada. Esto facilita la depuración cuando un usuario reporta que no se escucha el audio.
Optimización de costes
Reducir el tamaño del texto antes de enviarlo a la API es la forma más directa de ahorrar. Como cada carácter cuenta para el precio ($0.01 por mil caracteres), eliminar espacios innecesarios reduce la factura sin afectar la calidad del audio generado.
Implementar un sistema de caché para frases frecuentes evita regenerar el mismo audio una y otra vez. Si tu aplicación repite instrucciones o salidas comunes, guardar los archivos MP3 o WAV resultantes elimina el costo de repetición y acelera la experiencia del usuario.
Compresión de texto
Antes de realizar la solicitud, procesa la entrada para eliminar espacios dobles, saltos de línea excesivos y puntuación redundante. Dado que los espacios y signos de puntuación se cuentan como caracteres, esta limpieza simple puede reducir significativamente el volumen facturable en textos largos.
Aprovecha la capacidad de hasta 4096 caracteres por solicitud. Si tu contenido es extenso, divídelo eficientemente para evitar límites, pero evita fragmentos demasiado pequeños que añadan sobrecarga sin necesidad, manteniendo el equilibrio entre eficiencia y claridad.
- Elimina espacios dobles y saltos de línea no esenciales.
- Simplifica signos de puntuación complejos que no aporten valor.
- Verifica la longitud antes de enviar para evitar reintentos.
Caché de audio
Guarda localmente los archivos de audio para texto idéntico. Esto es crucial para elementos estáticos como menús de navegación, instrucciones de accesibilidad fijas o respuestas de bot comunes. Al recuperar el archivo en caché, no consumes créditos ni tiempo de CPU.
Define una estrategia de invalidación clara. Si el texto cambia aunque sea en un carácter, la caché debe considerarse obsoleta para garantizar que el usuario siempre escuche la versión correcta y precisa.
- Almacena hashes de texto para identificar coincidencias exactas.
- Usa formatos eficientes como MP3 para archivos pequeños.
- Limpia la caché periódicamente para liberar espacio.
Uso eficiente
Monitorea el uso de caracteres en tu panel para entender patrones de consumo. Al tener visibilidad clara de cuántos caracteres se generan por función, puedes priorizar las integraciones más críticas y ajustar la velocidad o el modelo según la urgencia.
Aprovecha las solicitudes fallidas gratuitas. Si la API devuelve un error, no se cobra el crédito. Diseña tu lógica para reintentar solo si el error es transitorio, evitando ciclos innecesarios que no generan audio pero sí consumen tiempo de desarrollo.
- Revisa el saldo y uso en /get-api-key/ regularmente.
- Implementa reintentos inteligentes con backoff exponencial.
- Elige el modelo adecuado según la necesidad de calidad.
Accesibilidad avanzada
La accesibilidad no es un lujo, es una necesidad para lectores con dislexia o dificultades visuales. Nuestra API te permite ajustar la velocidad de reproducción entre 0.25x y 4.0x, adaptando la experiencia a la capacidad de procesamiento individual de cada usuario sin perder naturalidad.
Velocidad ajustable
El parámetro speed permite desde una lectura pausada para personas que necesitan más tiempo de procesamiento, hasta una velocidad acelerada para usuarios avanzados. Esto garantiza que el contenido sea consumible por todos, respetando el ritmo cognitivo de cada lector.
- Rango de 0.25 a 4.0
- Adaptación al ritmo de lectura individual
- Sin pérdida de claridad en velocidades altas
Idiomas múltiples
Ofrecemos soporte para 23 idiomas, incluyendo español, inglés, francés y alemán, entre otros. Si no se especifica el language, el sistema infiere el idioma del script, pero para textos en latinos con otros idiomas, se recomienda establecerlo explícitamente para evitar errores de pronunciación.
- 23 idiomas soportados
- Incluso variantes menos comunes como suajili o turco
- Detección automática del script por defecto
Voces claras
Las 8 voces (Aria, Nova, Luna, Sage, Felix, Milo, Atlas, Orion) están basadas en grabaciones licenciadas y son claras. Aria y Sage ofrecen tonos ideales para narración y contenido instruccional, mientras que Nova y Luna aportan calidez para historias. Todas son sintéticas y llevan una marca de agua invisible.
- 8 voces predefinidas de alta claridad
- Ideales para lectura asistida y accesibilidad
- Basadas en grabaciones licenciadas de dominio público
Pruebas y calidad
Verificar la calidad auditiva es crucial antes de lanzar tu aplicación. Dado que la síntesis tarda unos segundos por frase corta, prueba la latencia en tu entorno real para asegurar que la experiencia no sea frustrante para lectores con dislexia o usuarios con baja visión.
Compara diferentes voces y velocidades con texto real de tu proyecto. Esto ayuda a confirmar que la claridad es suficiente para la comprensión lectora sin depender de suposiciones.
Pruebas unitarias
Automatiza la validación de las respuestas de la API. Verifica que el formato de audio (mp3, wav, etc.) sea correcto y que los metadatos coincidan con la solicitud. Usa los límites de 4096 caracteres para probar la división de textos largos y asegurar que la concatenación de audio funcione sin cortes abruptos.
- Validar código de estado 200
- Verificar duración del audio
- Comprobar formato de salida
Audición de muestras
Escucha activamente las muestras en diferentes idiomas y velocidades. La API no ofrece SSML ni etiquetas de emoción, por lo que debes confiar en las voces preset como 'sage' para texto instructivo o 'aria' para narración. Ajusta la velocidad entre 0.25 y 4.0 para encontrar el ritmo óptimo para tu audiencia.
- Probar voces masculinas y femeninas
- Ajustar velocidad de lectura
- Verificar claridad en idiomas minoritarios
Feedback de usuarios
Recoge opiniones directas sobre la utilidad de la función en tu contexto específico. Pregunta a tus usuarios si la voz natural facilita la lectura o si prefieren una velocidad más lenta. Esta retroalimentación es clave para ajustar las configuraciones por defecto de tu aplicación.

Despliegue
El despliegue en producción requiere considerar la latencia de la cola de procesamiento. Dado que las solicitudes se procesan en secuencia, los textos largos pueden tardar varios segundos en generarse, lo que difiere de una respuesta instantánea.
Es fundamental ajustar los tiempos de espera en tu infraestructura para evitar errores de timeout durante picos de carga, asegurando que la experiencia de usuario se mantenga fluida.
Entorno de producción
Configura tu entorno para manejar la naturaleza asíncrona de la API. Si tu aplicación espera una respuesta inmediata, considera implementar un sistema de colas que gestione las solicitudes de texto a voz en segundo plano.
- Ajusta los timeouts según la longitud del texto.
- Verifica la disponibilidad de la clave API antes de iniciar.
Monitoreo
Mantén un registro de los metadatos de las solicitudes, como el tiempo de respuesta y el estado de la síntesis. Esto te permitirá identificar cuellos de botella en la cola y optimizar el flujo de trabajo.
Actualizaciones
La API no requiere actualizaciones frecuentes de versión. Sin embargo, revisa periódicamente la página de documentación para verificar cambios en los límites de velocidad o la disponibilidad de nuevas voces y formatos de audio.
Ejemplo completo
La integración práctica demuestra cómo la API de Oído encaja en flujos de trabajo estándar. Utilizamos las bibliotecas oficiales o solicitudes HTTP directas para convertir texto en audio de forma fiable.
A continuación, presentamos ejemplos concretos en Python y JavaScript que ilustran la estructura de la petición y el manejo de la respuesta binaria.
Código en Python
Usamos la librería requests para enviar el texto y recibir el archivo de audio. El código configura la cabecera de autorización con la clave tts-... y especifica el modelo tts-1.
Es crucial guardar la respuesta binaria directamente en un archivo local o servirla sin deserializarla a texto, ya que el formato puede ser MP3, WAV u OPUS.
- Instalar
requests:pip install requests - Definir la URL base:
https://api.playok59.com/v1 - Enviar cabecera
Authorization: Bearer YOUR_KEY
Código en JavaScript
Con fetch, enviamos una petición POST con el cuerpo JSON. La respuesta se convierte en un Blob para su reproducción inmediata o descarga.
Este enfoque es ideal para aplicaciones web donde el audio debe generarse bajo demanda del usuario sin recargar la página.
- Usar
fetch()con métodoPOST - Convertir respuesta con
response.blob() - Crear URL de objeto con
URL.createObjectURL()
Estructura final
El flujo completo consta de tres pasos: preparar el texto (máximo 4096 caracteres), enviar la solicitud y guardar el audio resultante.
Esta estructura simple permite escalar fácilmente añadiendo lógica de caché o gestión de errores sin complicar la integración base.
Recursos adicionales
Esta guía cubre los aspectos técnicos esenciales para integrar la API. Para profundizar en la sintaxis exacta de los endpoints, consulta la documentación oficial.
Si necesitas ayuda específica con tu implementación, el soporte técnico está disponible por correo electrónico. Estamos aquí para resolver dudas técnicas sin perder tiempo en procesos burocráticos.
Documentación oficial
La referencia técnica completa incluye ejemplos de curl, especificaciones de los modelos tts-1 y tts-1-hd, y la lista detallada de voces y formatos soportados.
Usa la documentación para verificar los límites de caracteres y la estructura correcta del JSON para evitar errores de validación.
Comunidad
Los desarrolladores independientes comparten fragmentos de código, trucos de optimización y experiencias de integración en foros públicos y repositorios abiertos.
- Repositorios con snippets en Python y JavaScript
- Discusiones sobre integración de accesibilidad
Soporte
Envía tus dudas técnicas directamente por correo electrónico. Nuestro equipo responde a consultas sobre facturación, errores de sintaxis o limitaciones de velocidad.
Preguntas frecuentes
Aquí respondemos las dudas más frecuentes sobre el uso de nuestra API de texto a voz. Si tienes preguntas específicas, revisa la documentación completa o contáctanos por email.
Esta sección cubre errores típicos, límites de velocidad y cómo obtener ayuda técnica para tu integración.
Errores comunes
Si la síntesis falla, el cargo se devuelve íntegramente. Asegúrate de que el texto no supere los 4096 caracteres por solicitud. Si el texto es más largo, divídelo en partes y une los archivos de audio resultantes.
- Textos largos: dividir en fragmentos de 4096 caracteres.
- Formatos no válidos: verificar que se acepten mp3, wav, opus, flac o pcm.
- Clave expirada: emitir una nueva si la anterior deja de funcionar.
Límites de velocidad
El límite es de 60 solicitudes por minuto por clave API. Antes de la primera recarga, este límite se reduce a 10 solicitudes por minuto. Si hay mucha demanda, las peticiones se procesan en cola.
- 60 req/min tras la primera recarga.
- 10 req/min antes del primer depósito.
- Procesamiento secuencial bajo carga.
Soporte técnico
El soporte se realiza exclusivamente por correo electrónico. No contamos con chat en vivo ni número de teléfono. Para incidencias graves, envía un email con los detalles de tu cuenta y la solicitud fallida.
- Email: único canal de soporte.
- Sin chat en vivo ni teléfono.
- Respuesta en función de la cola de tickets.
Conclusión
Integrar la API de texto a voz de Oído permite a tu proyecto ofrecer accesibilidad real sin complejidad técnica. Con precios transparentes, soporte por email y voces naturales en 23 idiomas, la solución se adapta a desarrolladores independientes que priorizan la claridad y la eficiencia.
El flujo es directo: obtén tu clave, envía el texto y recibe el audio. Sin sorpresas, sin contratos largos ni infraestructura oculta. Es la herramienta que necesitas para mejorar la experiencia de tus usuarios de forma inmediata.
Ventajas claras
Oído API elimina la fricción entre el texto y el audio. Ofreces voces naturales, múltiples idiomas y un costo predecible ($0.01 por 1.000 caracteres) sin depender de suscripciones mensuales complejas. La simplicidad es tu mayor ventaja competitiva.
Siguiente paso
Crea tu cuenta en /get-api-key/ y obtén tu clave API en segundos. Si aún no tienes saldo, recuerda que puedes recargar con USDT (TRC-20) de forma automática o comenzar con el crédito de prueba de $0.50 si usas Google para registrarte.
Recursos finales
Consulta la documentación completa en /docs/ para ver ejemplos de código y parámetros avanzados. Si tienes dudas específicas sobre la integración o los límites de uso, nuestro equipo está disponible por email para ayudarte a resolverlas rápidamente.
- Documentación técnica completa
- Ejemplos de código listos para copiar
- Soporte por email para integraciones
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.
