Documentación técnica API de síntesis de voz

Por equipo editorial de LocutorEngine · Actualizado 2026-11-19

Esta documentación técnica detalla la integración de la API de síntesis de voz de LocutorEngine, diseñada para desarrolladores que necesitan generar spots de radio y anuncios publicitarios con precisión. El enfoque es directo: explica la estructura de las solicitudes, los parámetros necesarios y los formatos de audio soportados para una implementación eficiente en campañas digitales.

El contenido cubre desde la obtención de la clave API hasta el manejo de errores y límites de tasa, incluyendo ejemplos prácticos con curl y la adaptación del SDK de OpenAI. Se describe el flujo completo de datos, desde el texto de entrada hasta la recepción del archivo de audio, asegurando que los equipos de ingeniería comprendan las restricciones y capacidades del servicio sin ambigüedades.

Documentación técnica API de síntesis de voz

Preguntas frecuentes

¿Cómo se obtiene la clave API?

Regístrate en /get-api-key/ con Google o correo electrónico. La página muestra tu clave única (formato tts-...) y un ejemplo curl listo para usar. Si usas Google, recibes $0.50 de crédito válido por 7 días. Las cuentas con email no incluyen esta prueba inicial.

¿Qué formato de audio es mejor para web?

Para web, usa mp3 o opus por su equilibrio entre calidad y tamaño. El endpoint acepta mp3, wav, opus, flac y pcm. El formato mp3 es ampliamente compatible con reproductores modernos, mientras que opus ofrece compresión eficiente.

¿Se puede usar con Python?

Sí. Usa el SDK oficial de OpenAI cambiando el base_url a https://api.tm66.info/v1 y proporcionando tu clave. También puedes hacer solicitudes HTTP POST directas. El cuerpo de la solicitud sigue la misma estructura que el endpoint de speech de OpenAI.

¿Cuántas solicitudes puedo hacer por minuto?

El límite es de 60 solicitudes por minuto por clave. Antes de la primera recarga, el límite es de 10 por minuto. Si excedes el límite, las solicitudes adicionales se procesarán en cola o recibirán un error de límite de tasa.

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

Cada solicitud acepta 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. Los espacios y puntuación cuentan como caracteres. No hay penalización por dividir el texto manualmente.

¿Cómo se manejan los errores de red?

El API devuelve códigos de estado HTTP estándar. Si la síntesis falla, la carga se devuelve íntegramente. Implementa reintentos exponenciales para errores temporales. Los metadatos de la solicitud (tiempo, estado) se conservan para facturación y depuración de problemas de conectividad.

¿Se puede usar en producción?

Sí, es una API REST estándar diseñada para integración programática. No hay garantía de uptime ni SLA oficial. Las solicitudes se procesan en orden; bajo carga, puede haber retrasos. Asegúrate de manejar los límites de tasa y errores de red adecuadamente.

¿Qué es la cola de procesamiento?

Las solicitudes se procesan secuencialmente. Si hay alta demanda, tu solicitud puede esperar en una cola antes de comenzar la síntesis. Esto explica por qué textos largos tardan aproximadamente el tiempo real de generación, mientras que frases cortas pueden tener latencia adicional.

¿Cómo se reinicia la clave API?

Puedes emitir una nueva clave en cualquier momento desde tu panel de cuenta. La clave anterior deja de funcionar inmediatamente al generar la nueva. Solo se permite una clave activa por cuenta. Esto es útil si crees que la clave fue comprometida.

¿Es compatible con JavaScript?

Sí, funciona con cualquier cliente HTTP. Puedes usar fetch o axios para enviar solicitudes POST al endpoint. Solo necesitas configurar la cabecera Authorization con tu clave Bearer y el cuerpo JSON con los parámetros de modelo, voz, entrada y formato.

¿Se puede usar en iOS?

Sí, es compatible con iOS mediante llamadas HTTP estándar. Puedes integrar la API en tus aplicaciones Swift usando bibliotecas HTTP nativas. El audio devuelto se puede reproducir directamente en el dispositivo sin necesidad de un SDK específico de la plataforma.

¿Qué sucede con las solicitudes fallidas?

Las solicitudes fallidas son gratuitas. Si la síntesis falla, el cargo se devuelve íntegramente a tu saldo. Esto aplica tanto a errores de red como a fallos en el motor de generación. No se consume crédito por intentos que no generan audio.

¿Cómo se especifica el idioma?

Pasa el código ISO del idioma en el campo language. Si no se especifica, el sistema adivina el idioma basándose en el script (texto latino se asume inglés). Para textos en latín no ingleses, siempre establece el campo language explícitamente para evitar errores.

¿Se puede cambiar la velocidad en tiempo real?

No hay streaming ni control de velocidad durante la reproducción. La velocidad (0.25–4.0) se fija al generar el audio. Debes ajustar el parámetro speed en la solicitud para obtener la velocidad deseada antes de recibir el archivo de audio final.

Primera solicitud

curl

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

Accede a la página /get-api-key/ para crear tu cuenta. Puedes registrarte con Google o con email y contraseña. El registro es el primer paso para obtener acceso a la API de síntesis de voz de LocutorEngine.

Una vez dentro, tu panel muestra la clave API, el saldo disponible y el uso. Esta clave es el identificador único que usarás en tus solicitudes HTTP para generar audio.

Registro con Google o email

Registro con Google o email

Inicia sesión con Google para recibir $0.50 de crédito de prueba válido por 7 días. Si eliges email y contraseña, la cuenta comienza sin crédito de prueba. El registro es inmediato y no requiere verificación de tarjeta.

Generación de clave única

Generación de clave única

Cada cuenta recibe una única clave activa con el prefijo 'tts-'. Esta clave es el único token necesario para autenticar tus solicitudes a la API. No necesitas generar múltiples claves para diferentes entornos; una sola gestiona todo.

  • Prefijo: tts-...
  • Formato: Bearer token en cabecera

Gestión de claves activas

Puedes emitir una nueva clave en cualquier momento desde el panel. Al generar una nueva, la anterior deja de funcionar instantáneamente. Esto es útil si tu clave se expone en logs o repositorios públicos durante el desarrollo.

  • Reemplazo instantáneo
  • Una sola clave activa

Primera solicitud con curl

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

La API de LocutorEngine utiliza el método POST para generar archivos de audio a partir de texto. La solicitud se envía a https://api.tm66.info/v1/audio/speech con un cuerpo JSON que especifica el modelo, la voz y el texto a sintetizar. Esta estructura es compatible con los SDKs oficiales de OpenAI al ajustar la base URL.

Cada solicitud debe incluir los parámetros esenciales para garantizar la generación correcta del audio. El sistema procesa las peticiones en cola, por lo que tiempos de respuesta pueden variar según la carga. Los formatos soportados incluyen MP3, WAV, OPUS, FLAC y PCM.

Estructura del cuerpo JSON

El cuerpo de la solicitud debe ser un objeto JSON válido. Los campos obligatorios son model, input y voice. El campo input contiene el texto a convertir, con un límite estricto de 4096 caracteres por solicitud. Los espacios y puntuación cuentan como caracteres.

Campos opcionales incluyen response_format (por defecto mp3), speed (rango 0.25–4.0) y language (código ISO). Si no se especifica language, el sistema intenta deducirla del script, pero para texto en latín no inglés se recomienda establecerlo explícitamente.

  • model: "tts-1" o "tts-1-hd"
  • input: texto plano (máx. 4096 caracteres)
  • voice: nombre de la voz preset
  • response_format: mp3, wav, opus, flac, pcm
  • speed: número entre 0.25 y 4.0
  • language: código ISO opcional

Parámetros requeridos

La autenticación se realiza mediante la cabecera Authorization: Bearer <tu_clave_api>. La clave debe ser válida y activa. Cada cuenta tiene una única clave activa; si se emite una nueva, la anterior deja de funcionar inmediatamente.

El parámetro model determina la calidad y el motor de síntesis. Ambos modelos, tts-1 y tts-1-hd, utilizan el mismo motor y tienen el mismo precio: $0.01 por cada 1000 caracteres procesados.

  • Authorization: Bearer tts-...
  • Content-Type: application/json
  • model: tts-1 o tts-1-hd
  • input: string de texto
  • voice: string de voz

Ejemplo de comando curl

Aquí tienes un ejemplo funcional para generar un audio con la voz nova en formato MP3. Reemplaza <TU_API_KEY> con tu clave real y ajusta el texto según tu campaña de radio.

Este comando devuelve el archivo de audio directamente en la salida estándar. Para guardarlo en un archivo, redirige la salida con -o audio.mp3.

  • curl -X POST https://api.tm66.info/v1/audio/speech \
  • -H "Authorization: Bearer <TU_API_KEY>" \
  • -H "Content-Type: application/json" \
  • -d '{"model": "tts-1", "input": "Hola, esta es una prueba de LocutorEngine.", "voice": "nova"}'

Uso con SDK de OpenAI

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

La API es compatible con los SDKs oficiales de OpenAI mediante la simple modificación de la URL base. Esto permite reutilizar la lógica de cliente ya implementada en tus aplicaciones sin necesidad de escribir un integrador personalizado.

Configuración de base_url

Configura el parámetro base_url del SDK para apuntar a https://api.tm66.info/v1. Esto redirige todas las solicitudes al endpoint de síntesis de voz de LocutorEngine manteniendo la compatibilidad con la estructura de peticiones de OpenAI.

  • base_url: https://api.tm66.info/v1
  • Mantener la versión v1

Uso de clientes oficiales

Utiliza las librerías oficiales de OpenAI con tu clave de API (tts-...). El flujo de autenticación y la gestión de errores son idénticos a los estándares de la industria, facilitando la integración rápida en entornos de producción.

  • Requiere clave Bearer válida
  • Compatible con bibliotecas estándar

Adaptación de endpoints

No se requieren adaptadores complejos. El endpoint POST /v1/audio/speech acepta el mismo formato JSON que el servicio de referencia. Solo necesitas asegurarte de que tu cliente envíe las cabeceras de autorización correctamente.

Formatos de salida soportados

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

La API permite especificar el formato de audio mediante el parámetro response_format. El sistema genera el archivo en el formato solicitado, devolviendo el flujo binario directamente en la respuesta de la solicitud POST.

Los formatos disponibles cubren desde la compresión ligera para redes hasta la pérdida cero para masters de radio. La elección depende del flujo de trabajo de producción y de los reproductores destino.

MP3 para distribución web

El formato MP3 es el estándar para campañas digitales y emisoras online. Ofrece una relación calidad-peso óptima para la descarga rápida en aplicaciones móviles y navegadores sin overhead de procesamiento.

Recomendado para spots de radio digitales y anuncios en redes sociales donde el ancho de banda puede ser limitado.

  • Compatible con todos los reproductores web modernos
  • Tamaño de archivo reducido para tiempos de carga rápidos

WAV para alta fidelidad

WAV proporciona audio sin compresión, preservando la fidelidad original de la síntesis. Es ideal para etapas de postproducción donde se requiere editar el audio sin generar artefactos de compresión adicionales.

Utilice este formato si planea aplicar efectos de sonido o mezclar la voz en un estudio de grabación profesional.

  • Audio sin pérdida de calidad
  • Ideal para edición y mezcla posterior

OPUS, FLAC y PCM

OPUS ofrece una compresión eficiente con buena calidad a bitrates bajos, útil para transmisión en tiempo real o almacenamiento eficiente. FLAC asegura compresión sin pérdida, reduciendo el tamaño del archivo sin sacrificar datos.

PCM entrega el flujo de audio crudo sin codificar, máximo control para sistemas de hardware específico o análisis de señal.

  • OPUS: eficiencia para streaming y bajo ancho de banda
  • FLAC: compresión sin pérdida para archivado
  • PCM: audio crudo para procesamiento de hardware

Códigos de error comunes

Ilustración de onda de sonido para: Códigos de error comunes

Los errores API devuelven códigos HTTP estándar que indican el estado del procesamiento. Comprender cada código permite ajustar la lógica de integración sin interrupciones innecesarias en la generación de audio para tus campañas.

Error 401: Clave inválida

Se devuelve cuando la cabecera Authorization: Bearer contiene una clave incorrecta o expirada. Verifica que la clave generada en /get-api-key/ sea la activa, ya que la emisión de una nueva invalida instantáneamente a la anterior.

Error 429: Límite de velocidad

Indica que has excedido los 60 requests por minuto por clave (10/min antes del primer depósito). Implementa retroceso exponencial o divide los lotes grandes en partes de 4096 caracteres para respetar la cola de procesamiento.

  • Límite base: 10 req/min.
  • Límite estándar: 60 req/min.
  • Implementa backoff exponencial.

Error 500: Fallo en síntesis

Ocurre si el motor no puede generar el audio. A diferencia de otros fallos, este error devuelve el cargo en su totalidad, aunque no se entregue el archivo. Verifica la longitud del texto y el formato soportado.

Códigos de error comunes

Límites de la API

Ilustración de onda de sonido para: Límites de la API

La API aplica un límite estricto de 60 solicitudes por minuto por clave. Antes de la primera recarga, este límite se reduce a 10 solicitudes por minuto. El exceso de solicitudes retorna un error 429 hasta que el intervalo de tiempo se restablece.

60 solicitudes por minuto

Cada clave de API permite un máximo de 60 peticiones en un ventana de un minuto. Este límite es constante una vez que la cuenta tiene saldo. Si superas este umbral, las solicitudes adicionales recibirán un código 429.

Límite de 4096 caracteres

Cada cuerpo de solicitud JSON puede contener hasta 4096 caracteres en el campo input. Si tu texto excede este límite, debes dividirlo manualmente o mediante tu lógica de cliente antes de enviar la petición.

Cola de procesamiento

Las solicitudes se procesan en orden secuencial. Bajo alta carga, una petición puede esperar en la cola antes de comenzar la síntesis. Esto puede extender el tiempo de respuesta total para textos largos, aunque el precio se mantiene fijo.

Manejo de textos largos

Ilustración de onda de sonido para: Manejo de textos largos

La API acepta textos de hasta 4096 caracteres por solicitud. Para anuncios o spots de radio más extensos, es necesario dividir el texto manualmente en segmentos que respeten este límite antes de enviar las peticiones.

División en partes

Divida el guion en fragmentos de máximo 4096 caracteres. Cada segmento se envía como una solicitud POST independiente con el campo input correspondiente. Esto evita truncamientos y asegura que cada parte se procese correctamente.

Unión de archivos de audio

Cada solicitud devuelve un archivo de audio independiente. Para obtener el spot final, debe concatenar los archivos binarios en el orden original. No se ofrece una unión automática en el servidor; la responsabilidad de ensamblar el audio completo recae en el cliente.

Gestión de memoria

Al procesar múltiples segmentos, almacene los archivos temporales o buffers en memoria hasta completar la concatenación. Dado que las solicitudes se procesan secuencialmente bajo carga, considere implementar un retardo mínimo entre peticiones para evitar saturación y asegurar la integridad del flujo de audio final.

Autenticación y seguridad

Ilustración de onda de sonido para: Autenticación y seguridad

La autenticación se realiza mediante la cabecera Authorization: Bearer <tts-...> en cada solicitud. La clave debe enviarse exactamente como se muestra en el panel de control.

Cabecera Authorization Bearer

Incluya la cabecera Authorization: Bearer tts-... en el encabezado HTTP de cada petición POST. El sistema valida la clave antes de procesar la síntesis.

  • Cabecera: Authorization: Bearer tts-...
  • Formato de clave: prefijo tts- seguido de caracteres alfanuméricos

Un solo key por cuenta

Cada cuenta mantiene una única clave activa. No se soportan múltiples claves simultáneas para un mismo usuario.

Reemplazo instantáneo de clave

Al generar una nueva clave, la anterior deja de funcionar inmediatamente. Revoca el acceso antiguo sin demora para mantener la seguridad.

Escucha las 8 voces

Cada muestra a continuación fue generada por esta API a partir de la misma frase. Su tono es ideal para videos explicativos de SaaS o guías de producto donde la comprensión es prioritaria.

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. TRON developer hub: TRC-20
  3. FFmpeg documentation
  4. LibriTTS-R corpus (OpenSLR 141)
  5. LibriVox public-domain audiobooks
  6. OpenAI API reference: create speech
  7. Python documentation
  8. openai-python on GitHub
  9. LibriTTS-R paper (arXiv 2305.18802)
  10. MDN: Web Speech API
  11. ISO 639 language codes
  12. curl documentation

Más en este sitio