Documentación técnica para integrar texto a voz

Por Equipo editorial LectorVoz · Actualizado 2026-11-19

Esta documentación explica cómo integrar nuestra API de texto a voz en tus aplicaciones. Obtén claves, usa cURL o el SDK de OpenAI, y aprende a gestionar voces, formatos y límites técnicos con ejemplos concretos.

Ideal para equipos de producto que buscan accesibilidad y soporte para usuarios con dislexia. Encuentra guías rápidas para la obtención de claves, primeros pasos con código, manejo de errores y detección de idioma precisa.

Documentación técnica para integrar texto a voz

Preguntas frecuentes

¿Cómo obtengo una clave API?

Regístrate en /get-api-key/ con Google o correo electrónico. La página muestra tu clave única, saldo y ejemplos listos para copiar. Si usas Google, recibes $0.50 de prueba por 7 días. Las cuentas con email y contraseña comienzan sin crédito inicial. Puedes emitir una nueva clave en cualquier momento, lo que invalida la anterior inmediatamente.

¿Qué SDK debo usar para la API?

Usa el SDK oficial de OpenAI o HTTP plano. Solo cambia el base_url a https://api.g781b.info/v1 y utiliza tu clave de LectorVoz. La forma del cuerpo de la solicitud es idéntica al endpoint de voz de OpenAI, lo que facilita la integración rápida sin necesidad de aprender una nueva estructura de parámetros.

¿Cuál es el límite de caracteres por petición?

Cada solicitud puede contener hasta 4096 caracteres de texto. 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. Este enfoque permite gestionar textos extensos manteniendo la integridad de la síntesis.

¿Cuántas solicitudes puedo hacer por minuto?

El límite es de 60 solicitudes por minuto por clave. Antes de tu primera recarga, este límite es de 10 solicitudes por minuto. Si superas el límite, recibirás un error 429. Este control asegura que el servicio permanezca estable para todos los usuarios, especialmente durante picos de demanda en la generación de audio.

¿Qué formato de audio es mejor para web?

Puedes elegir entre mp3, wav, opus, flac o pcm. Para la web, mp3 u opus son ideales por su equilibrio entre calidad y tamaño de archivo. Estos formatos son ampliamente compatibles con los reproductores de navegador modernos. El formato seleccionado se especifica en el campo response_format de tu solicitud JSON.

¿Cómo cambio la velocidad de la voz?

Ajusta el parámetro speed en tu solicitud, aceptando valores entre 0.25 y 4.0. El valor predeterminado es 1.0. Esto permite acelerar o ralentizar la voz sintética según las necesidades de tu aplicación, ideal para ajustar la claridad en contenido educativo o para usuarios con dislexia que requieren un ritmo más pausado.

¿Debo especificar el idioma siempre?

No es obligatorio, pero se recomienda. Si no se especifica, el sistema intenta adivinarlo basándose en el script; el texto en latín por defecto es inglés. Para textos en otros idiomas con script latino, debes establecer el campo language explícitamente para garantizar una pronunciación correcta y evitar errores de síntesis.

¿Qué significa el error 429?

Significa que has excedido el límite de velocidad de 60 solicitudes por minuto (o 10 antes de recargar). Debes esperar a que el contador se reinicie o reducir la frecuencia de tus llamadas. Las solicitudes fallidas no cobran caracteres ni afectan tu saldo. Revisa la documentación para implementar una lógica de reintentos con retroceso exponencial.

¿Las claves API caducan?

Las claves API no caducan por tiempo. Sin embargo, puedes emitir una nueva clave en cualquier momento desde tu panel, lo que invalida la anterior inmediatamente. Esto permite una gestión segura de tus credenciales sin interrupciones en el servicio. Mantén tu clave activa y secreta para garantizar el acceso continuo a la API.

¿Se puede usar la API con JavaScript?

Sí, es totalmente compatible con JavaScript. Puedes usar el SDK de OpenAI configurando la URL base o realizar solicitudes fetch HTTP estándar. La integración es directa y funciona en cualquier entorno que soporte peticiones HTTP modernas, incluyendo navegadores y servidores Node.js, facilitando la implementación en aplicaciones web dinámicas.

¿Cuánto tarda en generarse el audio?

La velocidad es aproximadamente tiempo real: 25 caracteres por segundo de audio generado. Las frases cortas tardan unos segundos adicionales en procesarse. Las solicitudes se procesan en cola, por lo que bajo carga puede haber una espera adicional. Esto asegura una calidad consistente sin sacrificar la precisión de la síntesis de voz.

¿Puedo concatenar varios audios?

Sí, debes dividir textos largos en fragmentos de 4096 caracteres, generar cada audio por separado y luego unirlos. La API devuelve cada fragmento individualmente. Esta estrategia permite manejar textos extensos manteniendo la integridad de la voz y la sincronización, ideal para narraciones largas o contenido educativo continuo.

¿Qué ocurre si el servidor está ocupado?

Las solicitudes se procesan en orden de llegada. Si hay alta demanda, tu petición puede esperar en una cola antes de generarse. Esto puede aumentar ligeramente el tiempo total de respuesta, pero no afecta la calidad del audio ni el cobro. Cada solicitud se procesa individualmente para garantizar la precisión.

¿Es compatible con React o Vue?

Sí, es compatible con React, Vue y cualquier framework que use JavaScript. Al ser una API REST estándar, puedes integrarla mediante llamadas fetch o usando el SDK de OpenAI. La integración es agnóstica al framework, permitiendo añadir componentes de audio o texto a voz fácilmente en tus aplicaciones modernas.

Primera solicitud

curl

curl https://api.g781b.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.g781b.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.g781b.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 clave API

Ilustración de onda de sonido para: Obtención de clave API

Para comenzar a usar LectorVoz, accede a /get-api-key/ y registra tu cuenta mediante Google o correo electrónico. La elección del método determina si recibes un crédito de prueba inicial de $0.50 válido por 7 días, disponible solo con autenticación Google.

Una vez registrado, el panel muestra tu clave API única y el saldo actual. Esta clave es el único requisito para autenticar tus solicitudes a la API.

Registro con Google o email

Registro con Google o email

El registro es inmediato y crea una cuenta independiente para este sitio. Si usas correo y contraseña, no obtienes el crédito de prueba, pero puedes cargar saldo más adelante mediante USDT en la red TRON.

  • Soporte para autenticación con Google
  • Opción de registro por email y contraseña

Ubicación de la clave en el panel

Ubicación de la clave en el panel

Tu clave API (formato tts-...) se visualiza directamente en la página de configuración de la cuenta. También encontrarás allí tu balance, el estado del crédito de prueba y el ejemplo de comando cURL listo para copiar.

Emisión de nueva clave

Puedes generar una nueva clave en cualquier momento desde tu panel. Al hacerlo, la clave anterior deja de funcionar instantáneamente, lo que permite una rotación segura sin interrupciones en el servicio.

Primera solicitud con cURL

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

Para probar la API sin dependencias externas, envía una solicitud POST a /v1/audio/speech con tu clave Bearer. Este método básico permite verificar la integración rápidamente antes de implementar la lógica de tu aplicación.

La respuesta contiene el archivo de audio binario directo, listo para reproducirse o guardarse. No necesitas parsear JSON para obtener el audio en este formato básico.

Ejemplo de código completo

Usa este comando cURL para generar audio con la voz nova en formato MP3. Reemplaza tts-CLAVE_AQUI con tu clave real.

```bash curl https://api.g781b.info/v1/audio/speech \ -H "Authorization: Bearer tts-CLAVE_AQUI" \ -H "Content-Type: application/json" \ -d '{"model": "tts-1", "input": "Hola mundo", "voice": "nova", "response_format": "mp3"}' \ --output audio.mp3 ```

Parámetros requeridos

El cuerpo JSON debe incluir obligatoriamente model ("tts-1" o "tts-1-hd"), input con el texto a sintetizar y voice seleccionada de las 8 opciones.

El campo response_format es necesario para definir la salida. Opcionalmente, puedes especificar speed entre 0.25 y 4.0 para ajustar la velocidad de lectura.

  • model: "tts-1" o "tts-1-hd"
  • input: texto máximo 4096 caracteres
  • voice: nombre de la voz preset
  • response_format: mp3, wav, opus, flac, pcm

Respuesta de audio binario

La API devuelve el archivo de audio directamente en el cuerpo de la respuesta con el encabezado Content-Type correspondiente al formato solicitado.

Si la síntesis falla, recibirás un código de error JSON y la carga se devolverá. En caso de éxito, guarda el archivo para reproducirlo en tu aplicación de accesibilidad.

Uso con SDK de OpenAI

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

Al cambiar la variable base_url del SDK de OpenAI a https://api.g781b.info/v1, las librerías oficiales funcionan sin modificaciones adicionales. Esto permite aprovechar la misma estructura de peticiones que ya conoces, manteniendo la compatibilidad con tus flujos de trabajo actuales.

El SDK gestiona la autenticación y la serialización JSON automáticamente, lo que reduce la fricción técnica. Solo necesitas ajustar la URL base y proporcionar tu clave API para que la integración sea inmediata y funcional.

Modificación de base_url

Configura la variable de entorno o el parámetro de inicialización para apuntar a https://api.g781b.info/v1. Esto redirige las llamadas a nuestro endpoint de síntesis sin alterar la forma del cuerpo de la solicitud.

Esta configuración es reversible y segura, permitiendo alternar entre proveedores si es necesario sin cambiar la lógica de tu aplicación.

  • URL base: https://api.g781b.info/v1
  • Endpoint de síntesis: /v1/audio/speech
  • Formato de cuerpo: JSON idéntico al estándar

Compatibilidad de librerías

Las librerías oficiales de OpenAI para Python, Node.js y otros lenguajes son completamente compatibles. Solo requieren la configuración de la URL base y la clave de autorización.

No necesitas instalar paquetes adicionales ni adaptar la estructura de datos. Las llamadas se procesan siguiendo el mismo esquema que los clientes nativos de OpenAI.

  • Python SDK
  • Node.js SDK
  • HTTP clientes estándar (requests, axios)

Ejemplo en Python

Instala la librería oficial con pip install openai. Luego, inicializa el cliente especificando la base URL y la clave API. El código sigue la sintaxis estándar de Audio.speech.

Este enfoque permite integrar la lectura en voz alta en tus aplicaciones de accesibilidad con muy pocas líneas de código, facilitando la escalabilidad para equipos de producto.

  • pip install openai
  • base_url='https://api.g781b.info/v1'
  • API_KEY='tts-tu-clave-aqui'

Parámetros de entrada

Ilustración de onda de sonido para: Parámetros de entrada

La API acepta dos modelos idénticos en motor y precio: tts-1 y tts-1-hd. Ambos generan audio de alta calidad, por lo que la elección depende exclusivamente de la necesidad de latencia versus fidelidad sonora en tu aplicación de accesibilidad.

Modelo tts-1 y tts-1-hd

Ambos modelos utilizan el mismo motor de síntesis y tienen el mismo costo por carácter. No hay diferencia técnica en la calidad base, solo en la optimización interna del proceso de generación.

Voces disponibles

Puedes elegir entre 8 presets que cubren registros femeninos y masculinos. Cada voz está diseñada para tonos específicos, desde narradores claros hasta locutores documentales, permitiendo adaptar la experiencia de usuario para lectores con dislexia o dificultades cognitivas.

  • Aria: Narradora cálida y clara.
  • Nova: Tono brillante y enérgico.
  • Luna: Suave, ideal para historias.
  • Sage: Calma, instruccional.
  • Felix: Energético, promocional.
  • Milo: Conversacional y amigable.
  • Atlas: Neutral, estilo noticias.
  • Orion: Profundo, documental.

Velocidad ajustable

Puedes modificar la velocidad de lectura entre 0.25x y 4.0x. Esto permite a los usuarios ajustar la velocidad de procesamiento auditivo según su comodidad, facilitando la comprensión de textos complejos sin perder la naturalidad del habla sintetizada.

Formatos de salida soportados

Ilustración de onda de sonido para: Formatos de salida soportados

LSelecciona el formato de salida según tu caso de uso. MP3 es ideal para la web por su equilibrio entre calidad y peso, mientras que WAV ofrece alta fidelidad para procesamiento local o aplicaciones que requieren datos sin comprimir.

MP3 para web

El formato MP3 es la opción predeterminada y más eficiente para la mayoría de las aplicaciones web. Proporciona una buena relación calidad-tamaño, facilitando la carga rápida en navegadores y dispositivos móviles sin consumir ancho de banda excesivo.

WAV para alta calidad

Utiliza WAV cuando necesites la máxima fidelidad de audio sin pérdida. Este formato es ideal para integraciones que requieren procesamiento de señal posterior o para aplicaciones de accesibilidad donde la claridad del espectro de frecuencia es crítica.

Opus y FLAC comprimidos

Opus ofrece una compresión eficiente con excelente calidad a bitrates bajos. FLAC proporciona compresión sin pérdida, manteniendo la calidad original del audio.

  • FLAC: sin pérdida
Formatos de salida soportados

Límites y rendimiento

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

La API está diseñada para ser robusta bajo carga moderada. Conocer sus límites técnicos permite a los equipos de producto predecir el comportamiento de la aplicación y evitar interrupciones en la experiencia de lectura para usuarios con dislexia.

60 solicitudes por minuto

Cada clave API permite un máximo de 60 solicitudes por minuto. Antes de la primera recarga, el límite es de 10 solicitudes por minuto.

Este límite es por clave, no por cuenta. Si tu aplicación genera audio en tiempo real para varios usuarios, considera gestionar las solicitudes para no saturar el límite.

  • 60 req/min tras top-up
  • 10 req/min antes del primer top-up
  • Límite por clave API activa

Límite de 4096 caracteres

Cada solicitud acepta un máximo de 4096 caracteres. Si tu texto es más largo, debes dividirlo en partes y unir los archivos de audio resultantes.

Los espacios y la puntuación cuentan como caracteres. Planifica la segmentación de tu contenido para mantener la fluidez de la narración.

  • Máximo 4096 caracteres por petición
  • Espacios y puntuación cuentan
  • División manual requerida para textos largos

Cola de procesamiento

Las solicitudes se procesan en orden secuencial. Bajo alta demanda, una petición puede esperar en una cola antes de comenzar.

El tiempo de generación es aproximadamente en tiempo real (25 caracteres por segundo). Las frases cortas pueden tardar unos segundos adicionales.

  • Procesamiento secuencial
  • Posible espera en cola bajo carga
  • Tiempo de generación ~tiempo real

Manejo de errores comunes

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

La API de LectorVoz responde con códigos HTTP estandarizados para indicar el estado de cada solicitud. Estos códigos te permiten detectar rápidamente si el problema es de autenticación, límites de uso o validación de datos, facilitando la integración en tus flujos de trabajo.

Es importante verificar la estructura de la respuesta JSON cuando ocurre un error para obtener el mensaje descriptivo correspondiente y ajustar tu lógica de reintentos o manejo de excepciones en consecuencia.

Código 401 clave inválida

Este error indica que el token Bearer en el encabezado de autenticación es incorrecto o ha expirado. Asegúrate de copiar la clave exacta desde tu panel en /get-api-key/.

Si has emitido una nueva clave, la anterior deja de funcionar inmediatamente. Reemplázala en tu código para restablecer la conexión.

  • Verifica que el encabezado sea Authorization: Bearer tts-...
  • Una nueva clave invalida a la antigua al instante

Código 429 límites excedidos

Recibes este código si superas los 60 requests por minuto por clave (o 10 antes del primer recargo). La API procesa las peticiones en cola, por lo que un pico momentáneo puede desencadenar esta limitación.

Implementa una lógica de reintentos con retroceso exponencial para gestionar estas pausas sin interrumpir la experiencia del usuario.

  • Límite base: 60 solicitudes/minuto por clave
  • Procesamiento secuencial bajo carga

Código 422 texto vacío

Se produce si el campo input está vacío o contiene solo espacios. Recuerda que los espacios y puntuación cuentan como caracteres para tu saldo.

Valida que el texto tenga contenido antes de enviar la solicitud, especialmente si generas audio desde bases de datos donde pueden haber valores nulos.

  • El campo input no puede estar vacío
  • Los espacios cuentan como caracteres

Detección de idioma

Ilustración de onda de sonido para: Detección de idioma

La detección automática de idioma funciona bien para textos en inglés con caracteres latinos, pero puede fallar con otros idiomas. Por eso, el parámetro language es la herramienta principal para garantizar la pronunciación correcta.

Uso del parámetro language

Incluye el código ISO (ej. 'es', 'fr', 'de') en la solicitud para forzar el idioma de síntesis. Esto asegura que las voces interpreten correctamente acentos y reglas fonéticas específicas, evitando lecturas extrañas.

Detección por script latino

Si omites el parámetro language, el sistema asume inglés para cualquier texto en caracteres latinos. Esto significa que el español o el francés se leerán con acento inglés si no se especifica lo contrario.

Recomendaciones para precisión

Para equipos de accesibilidad, siempre define language explícitamente, incluso si el texto parece obvio. Esto evita errores de pronunciación en palabras prestadas o nombres propios, mejorando la experiencia para usuarios con dislexia.

  • Usa códigos ISO de dos letras (ej. 'en', 'pt', 'ja').
  • Define language incluso si la voz elegida es multilingüe.
  • Verifica la lista completa de 23 idiomas soportados en /docs/voices.

Escucha las 8 voces

Cada muestra a continuación fue generada por esta API a partir de la misma frase. Aquí encontrarás el desglose transparente de los costos para tu proyecto de accesibilidad.

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. LibriTTS-R paper (arXiv 2305.18802)
  3. curl documentation
  4. Node.js documentation
  5. LibriVox public-domain audiobooks
  6. W3C WAI: making audio and video accessible
  7. FFmpeg documentation
  8. MDN: Web Speech API
  9. ISO 639 language codes
  10. Tether (USDT)
  11. LibriTTS-R corpus (OpenSLR 141)
  12. openai-python on GitHub

Más en este sitio