Guía de integración y endpoints de la API de texto a voz

Por Equipo editorial de Oído API · Actualizado 2026-11-18

Esta guía explica cómo integrar la API de texto a voz de Oído en tus aplicaciones. Aquí encontrarás los endpoints necesarios, ejemplos prácticos y la documentación técnica para generar audio a partir de texto. Está diseñada para desarrolladores independientes que buscan una solución clara y sin complicaciones para añadir accesibilidad o lectura asistida a sus proyectos.

Verás cómo obtener tu clave API, configurar el cliente y manejar los parámetros de voz, idioma y formato. También aprenderás a gestionar los límites de uso y los errores comunes. Todo está pensado para que puedas empezar a generar audio en minutos, con precios transparentes y una integración sencilla que respeta tu flujo de trabajo habitual.

Guía de integración y endpoints de la API de texto a voz

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.mp3

Python (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
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

Inicio rápido

Ilustración de onda de sonido para: 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

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

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

Ilustración de onda de sonido para: 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

Ilustración de onda de sonido para: 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

Ilustración de onda de sonido para: 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 language es opcional pero recomendado para textos en latín no ingleses.

Formatos de audio

Ilustración de onda de sonido para: 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.

Formatos de audio

Límites y rendimiento

Ilustración de onda de sonido para: 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

Ilustración de onda de sonido para: 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

Ilustración de onda de sonido para: 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.

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. Node.js documentation
  3. ISO 639 language codes
  4. TRON developer hub: TRC-20
  5. LibriTTS-R paper (arXiv 2305.18802)
  6. LibriTTS-R corpus (OpenSLR 141)
  7. W3C WAI: making audio and video accessible
  8. openai-node on GitHub
  9. FFmpeg documentation
  10. openai-python on GitHub
  11. MDN: Web Speech API
  12. OpenAI API reference: create speech

Más en este sitio