Documentación de la API de texto a audio para desarrolladores

Por equipo editorial de LectorFácil · Actualizado 2026-11-19

Esta documentación explica cómo convertir texto en audio mediante la API de LectorFácil, diseñada específicamente para usuarios sin conocimientos técnicos que buscan facilitar el acceso a la información. Aquí encontrarás instrucciones claras para generar archivos de audio a partir de artículos o libros, utilizando una interfaz sencilla y parámetros directos.

La guía cubre desde la obtención de tu clave API hasta la ejecución de las primeras solicitudes con herramientas comunes como curl o el SDK de OpenAI. También detalla los límites de caracteres, los formatos de audio disponibles y cómo gestionar errores, asegurando que puedas integrar la síntesis de voz en tus flujos de trabajo sin complicaciones técnicas.

Documentación de la API de texto a audio para desarrolladores

Preguntas frecuentes

¿Qué es la clave API?

Es un token de autenticación único que inicia cada solicitud. Se envía en el encabezado Authorization: Bearer tts-... Cada cuenta tiene una clave activa; si emites una nueva, la anterior deja de funcionar inmediatamente.

¿Cómo obtengo mi clave API?

Regístrate en /get-api-key/ con Google o correo electrónico. La página muestra tu clave, saldo y ejemplos listos para usar. Las cuentas con Google reciben $0.50 de prueba por 7 días.

¿Qué es base_url en la API?

Es la dirección base para las llamadas HTTP. Debes configurarla en https://api.999com.info/v1. Esto permite usar SDKs estándar como el de OpenAI simplemente cambiando esta URL base en tu configuración.

¿Puedo usar la API con Python?

Sí, puedes usar el SDK oficial de OpenAI modificando su base_url a https://api.999com.info/v1. También puedes realizar llamadas HTTP directas. No ofrecemos un SDK propio específico para Python.

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

Cada solicitud puede contener hasta 4096 caracteres en el campo input. Para textos más largos, debes dividirlos en partes de este tamaño y unir los archivos de audio resultantes manualmente.

¿Qué ocurre si excedo el límite de solicitudes?

El límite es de 60 solicitudes por minuto por clave. Si excedes este límite, recibirás un error 429. Antes de tu primera recarga, el límite es de 10 solicitudes por minuto.

¿Qué formatos de audio puedo recibir?

Puedes solicitar audio en los formatos mp3, wav, opus, flac o pcm. Estos se especifican en el campo response_format de tu solicitud JSON.

¿La API devuelve el audio en streaming?

No, la API no soporta streaming ni WebSockets. Devuelve el archivo de audio completo en la respuesta. Los archivos contienen una marca de agua invisible que indica que son síntesis de voz.

¿Cómo sé si mi solicitud fue exitosa?

Una respuesta HTTP 200 indica éxito y contiene el archivo de audio. Si la síntesis falla, la solicitud no se cobra y recibes un código de error correspondiente con detalles del problema.

¿Qué significa el código de error 429?

Significa que has excedido el límite de velocidad de 60 solicitudes por minuto. Debes esperar a que el contador se reinicie o revisar tu límite si eres un usuario nuevo sin recarga.

¿Puedo usar la API desde un navegador?

Sí, mediante llamadas HTTP directas o SDKs compatibles. Para mayor seguridad en producción, usa un servidor intermediario.

¿Necesito instalar algún software adicional?

No es necesario instalar software específico de nuestra marca. Solo necesitas una herramienta para hacer llamadas HTTP, como curl, Postman o cualquier biblioteca de red en tu lenguaje de programación preferido.

¿La API soporta SSML?

No, la API no soporta etiquetas SSML. Solo acepta texto plano en el campo input. No hay soporte para diccionarios de fonemas o pronunciación personalizada mediante marcas de lenguaje.

¿Cómo se manejan los errores de audio?

Si la síntesis falla, no se realiza ningún cargo y el saldo se devuelve íntegramente. La respuesta HTTP indicará el error. Puedes reintentar la solicitud o revisar los parámetros como el modelo o la voz.

Primera solicitud

curl

curl https://api.999com.info/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.999com.info/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.999com.info/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

Para usar la API de LectorFácil, primero debes registrar una cuenta en la plataforma. El registro se realiza en la página /get-api-key/, donde puedes elegir autenticarte con Google o con correo electrónico y contraseña. Una vez creado el perfil, tendrás acceso a tu espacio de gestión.

La clave API es el elemento principal para identificar tus solicitudes. Se genera automáticamente tras el registro y puedes revisarla o regenerarla cuando lo necesites desde tu panel de control personal.

Registro en la plataforma

Registro en la plataforma

Accede a /get-api-key/ para iniciar el proceso. Puedes registrarte usando tu cuenta de Google para una configuración rápida, o proporcionar un correo electrónico y una contraseña para crear una cuenta estándar. Este paso es necesario para obtener tu identificador único.

  • Registro disponible en /get-api-key/
  • Opciones: Google o correo electrónico
  • Cuentas independientes por sitio

Ubicación de la clave en el panel

Ubicación de la clave en el panel

Una vez registrado, tu clave API (formato tts-...) se muestra en el panel de control. Aquí también puedes ver tu saldo, la cantidad de caracteres restantes y el historial de uso. Si es necesario, puedes emitir una nueva clave en cualquier momento; la anterior dejará de funcionar inmediatamente.

  • Clave visible en el panel
  • Emitir nueva clave invalida la anterior
  • Visualización de saldo y uso

Diferencias entre registro en Google y email

El método de registro afecta directamente a tu saldo inicial. Las cuentas creadas con Google reciben automáticamente $0.50 de crédito de prueba (aproximadamente 50 000 caracteres) con una validez de 7 días. Por el contrario, las cuentas registradas con correo electrónico y contraseña comienzan sin este crédito de prueba, requiriendo una recarga inicial para empezar a generar audio.

  • Google: incluye $0.50 de prueba
  • Email: sin crédito inicial
  • Prueba válida por 7 días

Primera solicitud con curl

Ilustración de onda de sonido para: Primera solicitud con curl

Para generar tu primer archivo de audio, utiliza la herramienta curl en tu terminal. La API acepta texto en formato JSON y devuelve el audio directamente. Solo necesitas configurar la clave de autorización y especificar los parámetros básicos como el modelo y la voz deseada.

Comando curl básico

Envía una solicitud POST a https://api.999com.info/v1/audio/speech. Incluye tu clave API en el encabezado Authorization: Bearer tts-tu_clave. Reemplaza el texto de ejemplo con tu contenido y selecciona una voz de las disponibles.

  • Método: POST
  • URL: /v1/audio/speech
  • Encabezado: Authorization: Bearer <tu_clave>

Estructura del cuerpo JSON

El cuerpo de la solicitud debe ser un objeto JSON con las claves model, input, voice y response_format. Por ejemplo, usa tts-1 con la voz nova y formato mp3. El texto puede tener hasta 4096 caracteres.

  • model: "tts-1" o "tts-1-hd"
  • input: texto a convertir
  • voice: nombre de la voz
  • response_format: mp3, wav, opus, flac, pcm

Verificación de la respuesta

Si la solicitud es exitosa, recibirás el archivo de audio binario en la respuesta. Si hay un error, la API devuelve un código de estado HTTP y un mensaje descriptivo en formato JSON. Los fallos de síntesis no cobran crédito.

Uso con el SDK de OpenAI

Ilustración de onda de sonido para: Uso con el SDK de OpenAI

La API de LectorFácil mantiene la misma estructura de solicitud que el endpoint de speech de OpenAI, lo que permite reutilizar las librerías oficiales sin necesidad de desarrollar un cliente desde cero. Esta compatibilidad facilita la integración para equipos que ya utilizan el ecosistema de OpenAI.

La única modificación necesaria consiste en apuntar la URL base del SDK al dominio de LectorFácil, asegurando que las peticiones se procesen en nuestro servidor en lugar del de OpenAI.

Modificación de base_url

Configura la variable base_url del SDK para que apunte a https://api.999com.info/v1. Esto redirige todas las llamadas al endpoint correcto, manteniendo la compatibilidad con la forma de cuerpo JSON estándar.

El SDK de OpenAI detectará automáticamente esta nueva URL y enviará las solicitudes al servicio de texto a audio de LectorFácil en lugar del servicio original.

Configuración de la clave

Incluye tu clave API de LectorFácil en el encabezado de autorización (Authorization: Bearer tts-...). Asegúrate de que la clave tenga los permisos necesarios y esté activa.

Recuerda que la clave es única por cuenta y se invalida inmediatamente al emitir una nueva en el panel de control.

Ejemplo de código en Python

A continuación se muestra un ejemplo básico utilizando la librería oficial de OpenAI en Python, ajustada para usar la API de LectorFácil.

El código genera un archivo de audio a partir de un texto simple, especificando el formato MP3 y la voz "aria".

Este enfoque permite integrar la generación de audio en aplicaciones existentes sin modificar la lógica de manejo de errores o la estructura de las respuestas.

  • import openai
  • client = openai.OpenAI(base_url="https://api.999com.info/v1", api_key="tts-tu-clave-aqui")
  • speech_file_path = "audio.mp3"
  • with client.audio.speech.audio.speech.create(
  • model="tts-1",
  • voice="aria",
  • input="Texto para accesibilidad",
  • response_format="mp3"
  • ) as response:
  • with open(speech_file_path, 'wb') as f: f.write(response.content)

Parámetros de la solicitud

Ilustración de onda de sonido para: Parámetros de la solicitud

La API permite generar audio mediante dos modelos: tts-1 y tts-1-hd. Ambos utilizan el mismo motor de síntesis y tienen idéntico precio, por lo que la elección depende exclusivamente de la preferencia de calidad de audio sin impacto en la facturación.

Modelo tts-1 y tts-1-hd

Los parámetros model, voice, response_format y speed son los elementos centrales de la solicitud. Aunque existen dos modelos, el motor subyacente es idéntico, diferenciándose solo en la codificación del archivo final.

Selección de voz y idioma

Se pueden elegir entre ocho voces predefinidas, con opciones femeninas y masculinas, cada una con un tono específico (narrador, informativo, documental, etc.). El idioma puede especificarse mediante un código ISO; si no se indica, el sistema intenta deducirlo del texto, asumiendo inglés para el script latino.

  • Voces: aria, nova, luna, sage, felix, milo, atlas, orion.
  • Idiomas: 23 disponibles (ej. español, inglés, alemán, japonés).
  • No soportados: vietnamita, tailandés, ucraniano, rumano, checo, bengalí.

Formatos de respuesta soportados

El formato de salida se define con response_format. MP3 es ideal para la mayoría de los reproductores web. WAV ofrece calidad sin compresión. OPUS es un formato eficiente para reducir el tamaño de archivo. FLAC ofrece compresión sin pérdida.

  • Formatos: mp3, wav, opus, flac, pcm.

Límites y cuotas

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

Para textos largos, es necesario dividir el contenido en fragmentos de máximo 4096 caracteres y unir los archivos de audio resultantes. Esto garantiza que cada solicitud se procese correctamente sin exceder el límite técnico del endpoint.

La cuota permite hasta 60 solicitudes por minuto por clave activa. Antes del primer recargo, el límite es de 10 solicitudes por minuto. Esto asegura un uso ordenado del servicio.

Límite de 4096 caracteres por solicitud

Cada llamada a la API acepta un máximo de 4096 caracteres en el campo input. Esto incluye espacios y puntuación. Para libros o artículos extensos, debe dividir el texto y concatenar los audios generados.

Límite de 60 solicitudes por minuto

Se permiten 60 solicitudes por minuto por clave API. Si la cuenta es nueva y no ha realizado recargas, el límite se reduce a 10 solicitudes por minuto. Este control evita saturación del servicio.

Cola de procesamiento bajo carga

Las solicitudes se procesan en orden secuencial. Bajo alta demanda, es posible que una solicitud espere en una cola antes de comenzar la síntesis. Los textos largos tardan aproximadamente un segundo por cada 25 caracteres.

Límites y cuotas

Manejo de errores

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

Cuando la API detecta un problema, devuelve un código de estado HTTP y un mensaje descriptivo en el cuerpo de la respuesta. Esto permite que tu aplicación identifique si el fallo es temporal o permanente.

Códigos de error comunes

Los errores más frecuentes son 400 (texto inválido o formato incorrecto), 401 (clave API ausente o incorrecta) y 429 (límite de 60 solicitudes por minuto excedido). Cada respuesta incluye un campo error con detalles específicos.

Comportamiento ante fallos

Si la síntesis falla por un error interno del servidor, la solicitud no se descuenta de tu saldo. Es importante verificar el código de estado antes de considerar la operación como completada con éxito.

Reembolso automático

Si la generación de audio falla, el cargo se devuelve íntegramente. No necesitas solicitarlo manualmente; el sistema ajusta tu balance automáticamente al detectar el error en la transacción.

Formatos de audio disponibles

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

La API de LectorFácil devuelve el audio generado en varios formatos según tus necesidades de uso. Cada formato tiene ventajas específicas en cuanto a calidad, tamaño de archivo y compatibilidad con reproductores o editores de audio.

MP3 para compatibilidad general

El formato MP3 es la opción más universal, ideal para integración rápida en plataformas web, apps móviles o lectores de pantalla. Su compresión con pérdida permite archivos ligeros que se cargan rápidamente, manteniendo una claridad de voz suficiente para la comprensión de texto en personas con dislexia.

WAV para alta calidad

El formato WAV ofrece audio sin compresión, preservando todos los detalles de la voz sintética. Es la elección recomendada si planeas editar el audio posteriormente o necesitas la máxima fidelidad posible para procesos de postproducción.

OPUS y FLAC para eficiencia

OPUS y FLAC ofrecen alternativas avanzadas. FLAC proporciona compresión sin pérdida con archivos más pequeños que WAV, ideal para archivar. OPUS es eficiente en ancho de banda, manteniendo buena calidad con un tamaño de archivo reducido.

  • OPUS: alta eficiencia para transmisión.
  • FLAC: calidad sin pérdida, menor tamaño que WAV.

Ejemplos de uso para no code

Ilustración de onda de sonido para: Ejemplos de uso para no code

La API de LectorFácil permite convertir textos en audio sin escribir código, ideal para quienes necesitan accesibilidad sin complicaciones técnicas. Puedes integrar la generación de voz en flujos de trabajo diarios utilizando herramientas de automatización populares.

Estas soluciones permiten procesar documentos completos o artículos de blog de forma sencilla, asegurando que el contenido sea audible para personas con dislexia o trastornos de aprendizaje.

Integración con herramientas de automatización ['Conectores como Make o Zapier permiten enviar texto a la API y recibir el archivo de audio directamente. Esto automatiza la creación de audios para newsletters o actualizaciones de contenido sin intervención manual.', 'El flujo funciona detectando nuevos textos y enviándolos automáticamente al endpoint de síntesis, guardando el resultado en la nube para su reproducción posterior.'] ['Automatización de newsletters a audio', 'Conversión automática de artículos de blog', 'Procesamiento de notificaciones por correo']

Uso de conectores API simples ['Las herramientas no-code utilizan peticiones HTTP básicas que imitan la estructura JSON de la API. Solo necesitas configurar la URL base, la clave de autorización y el texto a convertir.', 'Es posible usar formularios simples donde el usuario introduce el texto y recibe el enlace de audio generado, sin necesidad de entender la estructura técnica subyacente.', 'La simplicidad de la solicitud permite que cualquier usuario con conocimientos básicos de internet pueda configurar su propio generador de audio.']

Generación masiva de audio ['Para textos largos, la API permite dividir el contenido en partes de hasta 4096 caracteres. Las herramientas de automatización pueden dividir el texto automáticamente y unir los archivos de audio resultantes.', 'Este enfoque permite convertir libros o documentos extensos en audio de forma continua, manteniendo la coherencia del idioma y la voz seleccionada.', 'El límite de 60 solicitudes por minuto permite un procesamiento eficiente, aunque textos muy largos pueden requerir tiempo adicional para completarse.']

Escucha las 8 voces

Cada muestra a continuación fue generada por esta API a partir de la misma frase. No hay configuración técnica compleja ni necesidad de conocimientos previos de programació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. ISO 639 language codes
  3. OpenAI API reference: create speech
  4. Creative Commons Attribution 4.0
  5. Node.js documentation
  6. Python documentation
  7. Tether (USDT)
  8. W3C WAI: making audio and video accessible
  9. LibriTTS-R corpus (OpenSLR 141)
  10. openai-node on GitHub
  11. LibriVox public-domain audiobooks
  12. curl documentation

Más en este sitio