Documentación técnica para integrar voz sintética

Por Equipo editorial de LocutorWeb · Actualizado 2026-11-19

Esta documentación técnica está diseñada para desarrolladores que integran nuestra API de texto a voz en sus aplicaciones. Aquí encontrarás la referencia completa para generar audio sintético de alta calidad mediante llamadas HTTP simples, sin necesidad de gestionar infraestructura compleja ni dependencias propietarias.

El contenido incluye ejemplos prácticos con cURL y el SDK de OpenAI, explicación de parámetros como formato y velocidad, así como detalles sobre autenticación y límites de uso. Ideal para equipos que necesitan audios para anuncios y contenido sin complicaciones de infraestructura, con un enfoque en la integración rápida y funcional.

Documentación técnica para integrar voz sintética

Preguntas frecuentes

¿Qué es la base_url de la API?

La base_url es https://api.luckypub.cc/v1. Es el punto de conexión principal donde se envían las solicitudes POST para generar audio. Todas las rutas de la API, como /audio/speech, se añaden a esta URL base para realizar las llamadas necesarias a nuestro servicio de texto a voz.

¿Puedo usar la librería de OpenAI?

Sí, las librerías oficiales de OpenAI funcionan perfectamente. Solo necesitas cambiar el base_url a https://api.luckypub.cc/v1 y utilizar tu clave API. Esto permite reutilizar tu código existente sin modificaciones mayores, aprovechando la compatibilidad con el formato de solicitud estándar de la industria.

¿Qué códigos de error devuelve la API?

La API devuelve códigos HTTP estándar para indicar el estado de la solicitud. Si la síntesis falla, el cargo se devuelve íntegramente. No se especifican códigos numéricos detallados en la documentación, pero el estado de la respuesta indica si el audio se generó correctamente.

¿Cómo cambio la velocidad del audio?

Ajusta el parámetro speed en el cuerpo de la solicitud JSON. Los valores válidos van de 0.25 a 4.0. Un valor de 1.0 es la velocidad normal. Puedes acelerar o ralentizar la locución según las necesidades de tu anuncio o contenido sin cambiar el modelo ni el costo.

¿Qué formato es mejor para web?

MP3 es la opción más compatible y eficiente para la web. También puedes elegir WAV, OPUS, FLAC o PCM según tus necesidades de calidad o compresión. MP3 ofrece un buen equilibrio entre tamaño de archivo y calidad de audio para la reproducción en navegadores modernos.

¿Debo codificar el texto en base64?

No, no es necesario. Envía el texto directamente en el campo input del cuerpo JSON de la solicitud. La API acepta el texto plano y lo procesa para generar el audio. No necesitas realizar codificaciones adicionales antes de enviar la solicitud POST al endpoint.

¿Cuántas claves API puedo tener?

Solo puedes tener una clave activa por cuenta. Si necesitas revocar la clave actual, puedes emitir una nueva en cualquier momento. La clave antigua dejará de funcionar inmediatamente al generar la nueva, asegurando que solo tengas un punto de acceso activo a la API.

¿El audio tiene marca de agua visible?

El audio generado lleva una marca de agua inaudible que lo identifica como voz sintética. No es visible ni audible para el oyente promedio. Esta marca distingue el audio generado por la API de las grabaciones humanas o de otras fuentes sin necesidad de alterar la experiencia de escucha.

¿Qué pasa si excedo el límite de caracteres?

Cada solicitud puede contener hasta 4096 caracteres. Si tu texto es más largo, debes dividirlo en partes de ese tamaño y unir los archivos de audio resultantes. Las solicitudes se procesan secuencialmente, por lo que el límite se aplica por llamada individual a la API.

¿Es compatible con React o Vue?

Sí, es totalmente compatible. Puedes realizar llamadas HTTP desde cualquier framework frontend o backend usando la clave API. La API es independiente del entorno de ejecución, por lo que funciona perfectamente en aplicaciones React, Vue, Angular o cualquier otro entorno que soporte solicitudes HTTP.

¿Puedo usar SSML con esta API?

No, la API no soporta SSML. Solo acepta texto plano en el campo input. Si necesitas control preciso sobre la entonación o la pausa, deberás gestionarlo mediante la estructura del texto enviado o ajustando la velocidad y el tono mediante los parámetros de voz disponibles.

¿Cómo manejo textos muy largos?

Divide el texto en fragmentos de máximo 4096 caracteres. Envía cada fragmento en una solicitud separada y luego une los archivos de audio generados. Este proceso asegura que cada parte se sintetice correctamente.

¿La velocidad afecta el precio?

No, la velocidad no afecta el precio. El costo es de $10 por cada millón de caracteres procesados, independientemente de la velocidad configurada. Cambiar entre 0.25x y 4.0x no altera la facturación, que se basa únicamente en la longitud del texto de entrada.

¿Debo esperar a que termine el stream?

No hay streaming; la API devuelve el archivo de audio completo al finalizar la solicitud. Debes esperar a que la respuesta contenga el audio antes de continuar. No se envían fragmentos parciales, por lo que el tiempo de espera depende de la longitud del texto y la cola de procesamiento.

Primera solicitud

curl

curl https://api.luckypub.cc/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.luckypub.cc/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.luckypub.cc/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

Autenticación y clave API

Ilustración de onda de sonido para: Autenticación y clave API

Para acceder a la API, debes crear una cuenta en la página de registro e iniciar sesión con Google o correo electrónico. Cada cuenta recibe una única clave API activa que identifica tus solicitudes y gestiona tu saldo.

Generación de clave única por cuenta

Generación de clave única por cuenta

La clave se genera automáticamente al completar el registro. Es el identificador principal para todas las operaciones de facturación y uso de la API.

Uso del encabezado Authorization Bearer

Uso del encabezado Authorization Bearer

Incluye la cabecera Authorization: Bearer <tu-clave> en cada solicitud HTTP. Sin este encabezado, la API rechazará la petición con un error de autenticación.

Invalidación inmediata al emitir nueva clave

Puedes generar una nueva clave en cualquier momento desde tu panel. La clave anterior dejará de funcionar inmediatamente al emitir la nueva, asegurando que solo tengas una activa.

Endpoint principal de síntesis

Ilustración de onda de sonido para: Endpoint principal de síntesis

El endpoint principal de síntesis se accede mediante una solicitud POST a la ruta /v1/audio/speech. Este punto final actúa como el núcleo de la API, recibiendo las instrucciones para convertir el texto plano en audio.

La integración es directa: se envía la configuración en formato JSON y se recibe el resultado auditivo sin intermediarios. Es el componente esencial para generar locuciones en segundos.

Método POST /v1/audio/speech

Utiliza el método HTTP POST para enviar la carga útil de datos. La URL base completa es https://api.luckypub.cc/v1/audio/speech.

Formato JSON para la solicitud

Cuerpo de la solicitud que especifica el modelo, el texto y la voz. Debe incluir los campos obligatorios como input y voice en formato JSON.

Retorno del archivo de audio binario

La API responde con el archivo de audio generado directamente en la respuesta. No se devuelve un enlace, sino el archivo de audio generado en el formato solicitado.

Modelos de voz disponibles

Ilustración de onda de sonido para: Modelos de voz disponibles

El endpoint acepta dos identificadores de modelo en el campo model: tts-1 y tts-1-hd. Ambos utilizan el mismo motor de síntesis subyacente y tienen el mismo precio, diferenciándose principalmente en la calidad del audio generado.

La selección entre uno u otro depende de la necesidad de calidad versus tamaño de archivo, pero no implica una diferencia en el precio.

tts-1: Motor estándar

Este modelo genera audio en formato optimizado para una carga rápida y un tamaño de archivo reducido. Es la opción predeterminada para la mayoría de los casos de uso, como anuncios de radio o contenido de marketing donde la eficiencia es prioritaria.

tts-1-hd: Alta definición

Proporciona una mayor fidelidad de audio, resultando en archivos de mayor tamaño pero con mejor calidad sonora. Es recomendable cuando se requiere máxima claridad para piezas de audio profesional o donde la compresión agresiva podría afectar la experiencia del oyente.

Mismo precio para ambos modelos

A diferencia de otros servicios, la tarifa es idéntica para ambos modelos: $0.01 por cada 1.000 caracteres. El costo se basa únicamente en la longitud del texto procesado, no en la complejidad del motor seleccionado, lo que simplifica la previsión de gastos.

Parámetros de entrada de texto

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

La integración requiere enviar el texto a sintetizar dentro del cuerpo JSON de la solicitud. El sistema procesa el contenido como texto plano estándar, sin necesidad de marcado complejo ni etiquetas especiales.

Campo input con texto plano

Incluye tu texto en el campo input. El API acepta caracteres UTF-8 normales. No se requiere marcado SSML ni diccionarios de pronunciación personalizados.

  • Texto plano estándar
  • Soporte UTF-8
  • Sin necesidad de marcado

Límite de 4096 caracteres

Cada solicitud está limitada a 4096 caracteres, incluyendo espacios y puntuación. Si tu guion es más largo, debes dividirlo en segmentos dentro de este límite y unir los archivos de audio resultantes posteriormente.

Campo voice con nombre de preset

Selecciona una de las 8 voces predefinidas (ej. aria, nova, milo). La voz elegida determina el timbre y el estilo de la locución, adaptable a cualquier idioma soportado.

  • aria
  • nova
  • luna
  • sage
  • felix
  • milo

Configuración de formato y velocidad

Ilustración de onda de sonido para: Configuración de formato y velocidad

La API permite seleccionar el formato de audio de salida y ajustar la velocidad de reproducción para adaptarse a tus requisitos de producción.

El idioma se detecta automáticamente, pero puedes forzarlo explícitamente si el texto usa caracteres latinos para evitar confusiones.

response_format: mp3, wav, opus, flac, pcm

El campo response_format acepta cinco valores: mp3, wav, opus, flac y pcm. Esto te permite elegir entre compresión con pérdida o audio sin perder calidad, según el uso final del archivo.

  • mp3: tamaño reducido, ideal para web.
  • wav: sin compresión, estándar para edición.
  • opus: alta compresión, buena calidad.
  • flac: lossless, para archivar.
  • pcm: raw audio sin cabecera.

speed: rango de 0.25 a 4.0

El parámetro speed acepta valores decimales entre 0.25 y 4.0. Un valor de 1.0 mantiene la velocidad natural. Reduce el tiempo de generación para anuncios rápidos o extiéndelo para narraciones pausadas.

language: código ISO opcional

El campo language recibe un código ISO opcional. Si no se envía, el sistema adivina el idioma basándose en los caracteres; el texto en latino por defecto se interpreta como inglés. Para otros idiomas latinos, establece este campo explícitamente.

Configuración de formato y velocidad

Ejemplo de solicitud con cURL

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

Este ejemplo demuestra cómo generar audio directamente desde la terminal. Utiliza el endpoint estándar de síntesis con los parámetros mínimos necesarios para obtener un archivo de audio listo para usar en tus campañas.

Comando completo para terminal

Envía una solicitud POST a la API con tu texto y voz seleccionada. El ejemplo usa el modelo tts-1 con formato mp3 y la voz nova.

  • curl -X POST https://api.luckypub.cc/v1/audio/speech \ -H "Authorization: Bearer $TTS_KEY" \ -H "Content-Type: application/json" \ -d '{"model": "tts-1", "input": "Hola mundo", "voice": "nova", "response_format": "mp3"}' \ -o output.mp3

Uso de variable de entorno para clave

Almacena tu clave API en una variable de entorno (ej. $TTS_KEY) para evitar exponerla en scripts públicos o historiales de comandos. Esto asegura que la autenticación sea segura y fácil de rotar.

Verificación de código de estado 200

Un código 200 indica que la síntesis fue exitosa y el archivo se guardó correctamente. Si la solicitud falla, la carga se devuelve completamente, por lo que no se te cobra por intentos inválidos.

Uso con SDK oficial de OpenAI

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

Utiliza los SDK oficiales de OpenAI cambiando la variable base_url a https://api.luckypub.cc/v1. Esto permite mantener la misma estructura de clases sin reescribir la lógica de integración.

Cambio de base_url a nuestra API

Inicializa el cliente apuntando a la ruta base de LocutorWeb. La estructura de la solicitud permanece idéntica a la de OpenAI, facilitando la migración inmediata.

Mantener estructura de clases de OpenAI

Las clases y métodos del SDK conservan su comportamiento estándar. Solo necesitas ajustar la URL base y proporcionar tu clave API en el encabezado de autorización.

Compatibilidad con Python y Node.js

El SDK oficial funciona nativamente en Python y Node.js. No se requiere un SDK personalizado ni bibliotecas adicionales para gestionar la síntesis de voz.

Límites y manejo de errores

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

La API está diseñada para un flujo de trabajo eficiente, pero requiere respetar los límites de tasa para evitar interrupciones en la generación de locuciones. Cada clave de API permite un máximo de 60 solicitudes por minuto (10 por minuto antes del primer recargo), lo que es suficiente para la mayoría de los volúmenes de producción diaria sin necesidad de infraestructura adicional.

Los errores se manejan mediante códigos HTTP estándar y notificaciones claras en la respuesta. Si excedes el límite, recibirás un código 429, indicando que debes esperar antes de enviar más texto. Esta estructura permite una integración robusta con scripts de automatización y pipelines de producción de audio.

60 solicitudes por minuto por clave

Cada clave API tiene un límite estricto de 60 solicitudes por minuto. Este límite se aplica por cuenta y clave, independientemente del número de desarrolladores que utilicen la misma credencial. Para volúmenes superiores, puedes emitir una nueva clave desde tu panel de usuario; la anterior dejará de funcionar inmediatamente, permitiendo escalar sin complicaciones.

  • Límite fijo de 60 req/min por clave activa.
  • La invalidación de una clave es instantánea al generar una nueva.

Código 429 para exceso de límite

Cuando superas las 60 solicitudes en un minuto, la API devuelve un estado HTTP 429 Too Many Requests. Este código indica que has alcanzado la capacidad máxima de procesamiento para tu clave actual. Es importante implementar lógica de reintento con backoff exponencial en tus scripts para manejar este caso sin perder datos ni generar errores críticos.

  • Respuesta HTTP 429 al exceder el límite.
  • No se cobran las solicitudes que fallan.
  • Recomendado implementar reintentos automáticos con retraso progresivo.

Retraso en cola bajo alta demanda

Las solicitudes se procesan en orden secuencial. Bajo alta demanda, una solicitud puede esperar en una cola antes de comenzar la síntesis. Esto puede añadir algunos segundos de latencia adicional, especialmente para textos largos que requieren fragmentación. La velocidad típica es de aproximadamente 25 caracteres por segundo de audio generado, por lo que la cola se gestiona de forma transparente para la mayoría de los casos de uso.

  • Procesamiento secuencial de solicitudes.
  • Latencia variable según la carga del servidor.
  • Velocidad de generación: ~25 caracteres/segundo de audio.

Escucha las 8 voces

Cada muestra a continuación fue generada por esta API a partir de la misma frase. Estos identificadores deben enviarse en el campo voice de la solicitud POST.

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. curl documentation
  3. W3C WAI: making audio and video accessible
  4. TRON developer hub: TRC-20
  5. IETF RFC 7845: Ogg Opus
  6. Creative Commons Attribution 4.0
  7. Tether (USDT)
  8. openai-python on GitHub
  9. OpenAI API reference: create speech
  10. openai-node on GitHub
  11. Python documentation
  12. LibriVox public-domain audiobooks

Más en este sitio