Documentación técnica para narrador de voz online

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

Esta documentación técnica explica cómo integrar la API de NarraLab para generar narraciones profesionales destinadas a vídeos de recursos humanos y formación interna. Aquí encontrarás la referencia completa del endpoint principal, los parámetros configurables y ejemplos prácticos para desarrolladores y equipos de capacitación que necesitan audio sintetizado sin depender de locutores externos.

La guía cubre desde la obtención de tu clave API hasta la gestión de textos largos y errores comunes. Utiliza la estructura compatible con el SDK de OpenAI o comandos cURL directos. Los ejemplos incluyen parámetros como el modelo de voz, el formato de salida y los límites de velocidad, asegurando una integración rápida y predecible para tus flujos de trabajo de capacitación corporativa.

Documentación técnica para narrador de voz online

Preguntas frecuentes

¿Cuál es la estructura del JSON de entrada?

El cuerpo de la solicitud debe ser un objeto JSON con los campos model ("tts-1" o "tts-1-hd"), input (texto, máximo 4096 caracteres), voice (uno de los 8 presets), response_format (mp3, wav, opus, flac, pcm), speed (0.25–4.0) y language (opcional, código ISO).

¿Qué voz elegir para vídeos corporativos?

Para narraciones corporativas, recomendamos atlas (neutral, estilo noticiero) o sage (calma, instruccional). milo es adecuado para un tono conversacional y aria para una narradora clara. Todas las voces soportan los 23 idiomas disponibles, permitiendo adaptar el tono a la audiencia de RRHH.

¿Puedo usar la misma clave en producción y pruebas?

Sí, cada cuenta tiene una única clave activa que funciona tanto para pruebas como para producción. Si emites una nueva clave, la anterior deja de funcionar inmediatamente. Puedes emitir una nueva clave en cualquier momento desde tu panel de usuario sin costo adicional.

¿Qué significa el código 429?

El código 429 indica que has excedido los límites de velocidad (rate limits). El límite es de 60 solicitudes por minuto por clave (10 por minuto antes del primer recargo). Debes esperar a que el contador se restablezca o dividir textos largos en partes más pequeñas.

¿Es compatible con Python y Node.js?

Sí, la API sigue la misma estructura de solicitud que el endpoint de speech de OpenAI. Puedes usar los SDKs oficiales de OpenAI para Python y Node.js simplemente cambiando la base_url a https://api.nn22.info/v1 y utilizando tu clave de API en la cabecera de autenticación.

¿Cuánto tarda en generarse un audio?

La generación es aproximadamente en tiempo real para textos largos (unos 25 caracteres por segundo). Las frases cortas pueden tardar unos segundos. Las solicitudes se procesan en secuencia, por lo que bajo carga una solicitud podría esperar en una cola antes de comenzar la síntesis.

¿Puedo cambiar la velocidad en la API?

Sí, puedes ajustar la velocidad mediante el campo speed en la solicitud JSON. El valor debe estar entre 0.25 y 4.0. Esto permite acelerar o ralentizar la voz sin afectar la calidad del audio generado, adaptando el ritmo a las necesidades del vídeo de formación.

¿Qué formato es mejor para editar vídeo?

Para edición de vídeo, wav o flac son ideales por ser sin pérdida. mp3 es ligero y compatible. opus ofrece alta compresión. pcm es sin comprimir. La elección depende de tu flujo de trabajo, pero todos se entregan como archivos de audio estándar en la respuesta.

¿Cómo manejo errores de red?

Si la síntesis falla, la carga se devuelve íntegramente. Para errores de red, implementa una lógica de reintento estándar. Asegúrate de manejar códigos de estado HTTP adecuados. Los metadatos de la solicitud (tiempo, caracteres, estado) se conservan para facturación, lo que facilita la auditoría de fallos.

¿Hay un límite de caracteres totales?

El límite es de 4096 caracteres por solicitud. Para textos más largos, debes dividirlos en partes de hasta 4096 caracteres y unir los archivos de audio resultantes. Los espacios y la puntuación cuentan como caracteres, por lo que debes considerar esto al calcular la longitud del texto.

¿Qué es tts-1-hd?

tts-1-hd es el modelo de alta definición de la API. Utiliza el mismo motor de síntesis que tts-1 y tiene el mismo precio ($10 por 1 millón de caracteres). La diferencia es solo el nombre del modelo; usan el mismo motor y tienen el mismo precio.

¿Puedo usar la API desde un navegador?

Sí, puedes hacer solicitudes HTTP directas desde un navegador usando JavaScript (fetch). Sin embargo, tu clave API quedará expuesta en el código del cliente. Para producción, es mejor usar un servidor backend que maneje la autenticación. No hay un SDK oficial de NarraLab para navegadores.

¿Cómo detecto el idioma automáticamente?

Si no especificas el campo language, el sistema intenta adivinarlo basándose en el guion. El texto en latino por defecto es inglés. Para textos en otros idiomas con caracteres latinos, debes establecer explícitamente el campo language con el código ISO para evitar errores de pronunciación.

¿Qué pasa si el servidor está caído?

Si la síntesis falla por cualquier motivo, la carga se devuelve íntegramente. No se cobra por las solicitudes fallidas. Los metadatos de la solicitud se mantienen para facturación. No hay garantía de disponibilidad (SLA), por lo que los tiempos de inactividad pueden ocurrir sin aviso previo.

Primera solicitud

curl

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

La obtención de la clave API es el primer paso para integrar la narración de voz en tus flujos de formación. El registro se realiza directamente en la página de obtención de clave, donde se asignan las credenciales de acceso necesarias para la facturación y la autenticación de las solicitudes.

Registro en /get-api-key/

Registro en /get-api-key/

Accede a la página de registro para crear tu cuenta utilizando Google o correo electrónico. Una vez registrado, la interfaz muestra tu clave API activa, el saldo disponible y un ejemplo de comando curl listo para usar, facilitando la integración inmediata sin necesidad de desarrolladores especializados.

  • Registro vía Google o email + contraseña
  • Visualización inmediata de la clave y el saldo
  • Ejemplo de curl incluido para pruebas rápidas

Una clave activa por cuenta

Una clave activa por cuenta

Cada cuenta de usuario mantiene una única clave API activa que autoriza todas las solicitudes de síntesis. Esta clave se envía en la cabecera Authorization como token Bearer y es el único identificador necesario para procesar los textos y cargar el consumo en tu cuenta.

Revocación inmediata al emitir nueva

Al generar una nueva clave desde tu panel, la clave anterior deja de funcionar de forma instantánea. Este mecanismo garantiza que cualquier uso no autorizado o pérdida de credenciales se resuelve inmediatamente sin necesidad de esperar a la expiración de sesiones o tokens.

Endpoint principal de síntesis

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

El endpoint principal para generar audio es POST https://api.nn22.info/v1/audio/speech. Envías el texto en formato JSON y recibes el archivo de audio generado directamente.

La respuesta es un archivo binario cuyo formato depende del campo response_format especificado en la solicitud (mp3, wav, opus, flac o pcm).

Método POST a /v1/audio/speech

Utiliza el método HTTP POST para enviar la solicitud de síntesis. La dirección base es https://api.nn22.info/v1 y el path específico es /audio/speech.

Este endpoint es compatible con las librerías oficiales de OpenAI si ajustas la variable base_url, facilitando la integración sin cambiar la lógica de tu código.

Cuerpo JSON con input y voice

El cuerpo de la solicitud debe incluir el campo input con el texto a narrar (máximo 4096 caracteres) y el campo voice seleccionando una de las 8 voces disponibles.

Opcionalmente, puedes especificar el idioma ISO, la velocidad (0.25–4.0) y el formato de respuesta. El modelo tts-1 o tts-1-hd usa el mismo motor.

  • input: texto plano (hasta 4096 caracteres)
  • voice: nombre de la voz (ej. aria, nova)
  • response_format: mp3, wav, opus, flac, pcm
  • speed: valor numérico entre 0.25 y 4.0

Respuesta con archivo de audio binario

La respuesta exitosa contiene el archivo de audio binario listo para descargar o reproducir. Si la síntesis falla, el cargo se devuelve íntegramente.

El archivo generado incluye una marca de agua inaudible que identifica el contenido como speech sintético.

Parámetros de solicitud

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

La solicitud POST a /v1/audio/speech requiere especificar el modelo y la voz. Solo se permiten los modelos tts-1 y tts-1-hd, que utilizan el mismo motor y tienen el mismo precio. El texto de entrada debe tener como máximo 4096 caracteres.

Modelo tts-1 o tts-1-hd

Ambos modelos usan el mismo motor y tienen el mismo precio. La elección no afecta el precio ni el rendimiento, sino que se mantiene por compatibilidad con la estructura de la API.

Voz de 8 opciones disponibles

Seleccione una de las ocho voces predefinidas. Cada voz tiene un tono específico, desde narradora clara hasta documental profundo. El idioma se infiere automáticamente, pero puede forzarlo con el campo language.

  • Aria: Narradora cálida y clara
  • Nova: Brillante y enérgica
  • Luna: Suave para historias
  • Sage: Calma instruccional
  • Felix: Promocional y dinámico
  • Milo: Conversacional y amigable
  • Atlas: Neutral para noticias
  • Orion: Profundo para documentales

Formatos mp3, wav, opus, flac, pcm

Elija el formato de salida según sus necesidades de integración. MP3 es un formato estándar; WAV y FLAC ofrecen calidad sin pérdida; OPUS es eficiente para ancho de banda; PCM es audio crudo sin comprimir.

  • mp3: Estándar para web
  • wav: Alta calidad sin pérdida
  • opus: Compresión eficiente
  • flac: Audio lossless
  • pcm: Datos crudos

Ejemplo rápido con Curl

Ilustración de onda de sonido para: Ejemplo rápido con Curl

El endpoint principal acepta solicitudes JSON para sintetizar texto en audio. La estructura es idéntica a la de OpenAI, lo que facilita la integración inmediata sin adaptaciones complejas.

Este flujo es ideal para automatizar la generación de narraciones en flujos de capacitación interna, donde el texto se procesa y se almacena como archivo de audio listo para usar.

Comando POST estándar

Envía una solicitud POST a https://api.nn22.info/v1/audio/speech. El cuerpo debe incluir el texto en 'input', la 'voice' deseada y el 'model'.

Ejemplo de estructura JSON: {"model": "tts-1", "input": "Bienvenidos al módulo de seguridad laboral", "voice": "sage", "response_format": "mp3"}.

  • Método: POST
  • URL: /v1/audio/speech
  • Formato: application/json

Inclusión de cabecera Authorization

Autentica cada solicitud con tu clave API en la cabecera 'Authorization'. El formato es 'Bearer tts-tu_clave_aqui'.

Sin esta cabecera, el servidor rechazará la síntesis con un error 401. Obtén tu clave en /get-api-key/.

Descarga del archivo generado

La respuesta contiene el archivo de audio binario directamente en el cuerpo. Guárdalo con la extensión correspondiente (ej. .mp3).

El tiempo de generación es cercano al tiempo real. Para textos largos, divide en fragmentos de 4096 caracteres y concatena los resultados.

Uso con OpenAI SDK

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

La API de NarraLab sigue el formato de la API de OpenAI, lo que permite reutilizar las librerías oficiales sin adaptaciones complejas. Solo es necesario apuntar el cliente a la base URL de la plataforma.

Este enfoque simplifica la integración para equipos de RRHH que ya usan herramientas basadas en Python o Node.js, evitando la necesidad de aprender una sintaxis nueva desde cero.

Cambiar base_url a api.nn22.info

Inicializa tu cliente de OpenAI estableciendo base_url en https://api.nn22.info/v1. Esto redirige todas las solicitudes al endpoint de síntesis de NarraLab sin modificar el resto de la lógica de tu aplicación.

La autenticación sigue siendo un token Bearer (tts-...) pasado en la cabecera Authorization. Este token se obtiene en /get-api-key/.

  • Base URL: https://api.nn22.info/v1
  • Formato de clave: tts-...

Mantener estructura de parámetros

El cuerpo JSON utiliza los mismos campos que el endpoint de speech de OpenAI: model, input, voice, response_format y speed. No hay diferencias estructurales que requieran mapeo adicional.

Los valores válidos para model son "tts-1" o "tts-1-hd", ambos con el mismo motor de síntesis y precio.

Mismas librerías de cliente

Puedes usar la librería oficial openai para Python o Node.js directamente. No se requiere un SDK específico de NarraLab; se usan las librerías oficiales de OpenAI.

Esto facilita la integración en flujos de formación interna donde el audio se genera dinámicamente dentro de aplicaciones web o scripts de automatización.

Uso con OpenAI SDK

Límites y rendimiento

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

La API está diseñada para integrar narraciones en flujos de trabajo de formación interna sin complicaciones de infraestructura. Conocer sus límites de velocidad y capacidad de procesamiento garantiza que la generación de audio para vídeos de RRHH sea predecible y estable.

El sistema procesa las solicitudes en un orden estricto, lo que significa que el rendimiento depende de la cola actual. Esta arquitectura simple evita la complejidad de la gestión de múltiples hilos, ofreciendo una solución robusta para equipos sin conocimientos de programación.

60 solicitudes por minuto

Cada clave API permite un máximo de 60 solicitudes por minuto. Este límite es suficiente para la mayoría de los equipos de capacitación que generan narraciones para vídeos corporativos de forma escalonada.

Antes de realizar la primera recarga de saldo, el límite se reduce a 10 solicitudes por minuto. Esto permite probar la integración sin riesgos antes de comprometerse con un volumen mayor de producción.

  • Máximo 60 peticiones/min tras la primera recarga.
  • 10 peticiones/min en la fase inicial gratuita.

Cola de procesamiento bajo carga

Las solicitudes se procesan en orden de llegada. Si hay múltiples peticiones simultáneas, algunas pueden esperar en una cola hasta que se libere capacidad de procesamiento.

Esto es normal en momentos de alta demanda y no indica un fallo del sistema. La latencia puede aumentar ligeramente durante estos picos, pero la integridad del audio generado se mantiene.

Texto máximo 4096 caracteres

Cada solicitud está limitada a 4096 caracteres de texto, incluyendo espacios y puntuación. Para guiones más largos, es necesario dividir el texto en fragmentos manejables.

Al generar múltiples fragmentos, asegúrate de usar la misma voz para mantener la coherencia narrativa en el vídeo final. La concatenación de los archivos de audio resultantes es responsabilidad del cliente.

Códigos de error comunes

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

La API devuelve códigos HTTP estándar para indicar el estado de cada solicitud de síntesis. Conocer estos errores permite ajustar la lógica de tu integración sin depender de soporte inmediato.

401 Clave incorrecta o inválida

Este error indica que la cabecera Authorization no coincide con una clave activa en tu cuenta. Verifica que no haya espacios extra o que hayas renovado la clave en /get-api-key/ si la emitiste recientemente.

  • Verificar la cabecera Authorization: Bearer tts-...

429 Límite de velocidad excedido

Se alcanza el límite de 60 solicitudes por minuto por clave. Si usas la cuenta nueva, el límite inicial es de 10 solicitudes/min. Espera a que se libere la cola o revisa tu código de reintentos.

  • 60 req/min por clave activa

500 Fallo interno del servidor

Indica un error durante la generación. Si ocurre, la carga se devuelve íntegramente. Reintenta la solicitud o verifica que el texto no exceda los 4096 caracteres.

  • Reintento gratuito en caso de fallo

Manejo de textos largos

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

La API limita cada solicitud a 4096 caracteres. Para narraciones corporativas extensas, es necesario segmentar el guion manualmente o mediante script antes de enviarlo.

Al dividir el texto, cada fragmento genera un archivo de audio independiente. El flujo de trabajo requiere gestionar estos archivos para mantener la continuidad del audio final.

Dividir en fragmentos de 4096 chars

Cada petición POST a /v1/audio/speech acepta un máximo de 4096 caracteres en el campo input. Si tu guion de formación supera este límite, debes dividirlo en bloques lógicos (oraciones o párrafos) antes de realizar las llamadas API.

El límite incluye espacios y puntuación. Asegúrate de que el último fragmento no corte palabras importantes para facilitar la edición posterior.

  • Máximo 4096 caracteres por solicitud.
  • Incluye espacios y signos de puntuación.
  • Divide en bloques lógicos de significado.

Concatenar archivos de audio

La API devuelve el audio binario en la respuesta. Al procesar múltiples fragmentos, recibirás varios archivos separados. Debes unirlos secuencialmente usando un script o herramienta de edición para obtener el audio final de la capacitación.

No hay un endpoint de concatenación nativo; la unión es responsabilidad del cliente que consume la API.

  • Cada fragmento genera un archivo independiente.
  • Une los archivos en el orden de las solicitudes.
  • Formatos soportados: mp3, wav, opus, flac, pcm.

Mantener coherencia de voz en partes

Para evitar saltos bruscos, utiliza siempre el mismo valor de voice en todas las solicitudes del mismo guion. La API no guarda contexto entre llamadas, por lo que cada fragmento se genera de forma aislada.

La transición entre fragmentos puede tener pequeños silencios naturales. Ajusta la velocidad (speed) de manera consistente para mantener un ritmo uniforme en toda la narración.

  • Usa el mismo voice en todas las peticiones.
  • La API no guarda contexto entre llamadas.
  • Ajusta speed consistentemente.

Escucha las 8 voces

Cada muestra a continuación fue generada por esta API a partir de la misma frase. Su tono cálido mantiene la atención del empleado sin resultar monótono, facilitando la retención de información clave en vídeos de onboarding.

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. W3C WAI: making audio and video accessible
  3. ISO 639 language codes
  4. FFmpeg documentation
  5. Python documentation
  6. Creative Commons Attribution 4.0
  7. MDN: Web Speech API
  8. Node.js documentation
  9. TRON developer hub: TRC-20
  10. LibriTTS-R paper (arXiv 2305.18802)
  11. IETF RFC 7845: Ogg Opus
  12. openai-python on GitHub

Más en este sitio