Documentación técnica de la API de generación de voz

Por Equipo editorial Narras · Actualizado 2026-11-19

Esta documentación técnica explica cómo integrar la API de Narras en tus flujos de trabajo para generar narraciones de audio a partir de texto. Si eres desarrollador que integra voz sintetizada en aplicaciones, esta guía detalla los endpoints, parámetros y autenticación necesarios para empezar a usar el servicio de inmediato.

El contenido cubre desde la obtención de tu clave API hasta la implementación con las librerías de OpenAI. Encontrarás ejemplos prácticos en cURL, una descripción de los modelos disponibles y las limitaciones técnicas como los límites de caracteres o la velocidad de procesamiento,

Documentación técnica de la API de generación de voz

Preguntas frecuentes

¿Qué formato de respuesta devuelve la API?

La API devuelve el archivo de audio directamente en el cuerpo de la respuesta. Puedes elegir entre los formatos mp3, wav, opus, flac o pcm especificando el campo response_format en tu solicitud JSON. No se devuelve metadatos adicionales junto al audio, solo el binario del archivo generado listo para su reproducción o descarga inmediata.

¿Puedo usar la librería de Python de OpenAI?

Sí, la forma de solicitud es idéntica a la de OpenAI. Solo necesitas cambiar la base_url a https://api.winslots777.info/v1 y utilizar tu clave de API en su lugar. Esto permite usar las librerías de OpenAI ajustando la URL base.

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

Cada solicitud individual acepta un máximo de 4096 caracteres en el campo input. Si tu texto supera este límite, debes dividirlo en partes más pequeñas y enviar múltiples solicitudes. Cada parte generará un archivo de audio independiente que luego deberás unir para obtener la narración completa.

¿Cómo manejo textos largos en la API?

Debes dividir tu texto en fragmentos de hasta 4096 caracteres y enviar una solicitud POST por cada fragmento. Luego, une los archivos de audio resultantes en el orden correcto. Las solicitudes se procesan secuencialmente, por lo que textos muy largos pueden tardar más debido a la cola de procesamiento.

¿Qué hace el modelo tts-1-hd?

El modelo tts-1-hd utiliza el mismo motor de síntesis y tiene el mismo precio que tts-1. La única diferencia es la etiqueta de calidad del modelo seleccionado en la solicitud. Ambos modelos generan audio con la misma velocidad y características técnicas, ofreciendo la misma experiencia de narración.

¿La API soporta streaming?

No, la API no ofrece streaming ni WebSockets para audio parcial. Devuelve el archivo completo una vez finalizada la síntesis. Las solicitudes se procesan una tras otra, por lo que bajo carga una petición puede esperar en cola antes de generar y devolver el audio completo.

¿Puedo cambiar la velocidad en tiempo real?

La velocidad se define en cada solicitud mediante el parámetro speed, con un rango de 0.25 a 4.0. No es posible ajustar la velocidad dinámicamente mientras se reproduce el audio. Debes especificar la velocidad deseada en cada llamada a la API antes de que se genere el archivo.

¿Cómo se mide el uso de caracteres?

Se facturan 10 dólares por cada millón de caracteres, donde los espacios y la puntuación cuentan como caracteres. El límite es de 4096 caracteres por petición. Los caracteres se cuentan en el campo input de tu solicitud JSON antes de enviarla a la API para la síntesis.

Primera solicitud

curl

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

Autenticación

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

La autenticación se realiza mediante una clave API enviada en el encabezado Authorization como token Bearer. Cada cuenta mantiene una sola clave activa válida para todas las peticiones.

Esta clave debe obtenerse desde la página /get-api-key/ y se utiliza en cada llamada a la API para identificar tu cuenta y facturar los caracteres generados.

Uso de clave Bearer

Uso de clave Bearer

Incluye el encabezado Authorization: Bearer tts-tu-clave-aqui en cada solicitud HTTP. La API verifica la validez de la clave antes de procesar el texto o asignar costo.

Obtención desde /get-api-key/

Obtención desde /get-api-key/

Navega a la ruta /get-api-key/ tras registrarte con Google o correo electrónico. Allí verás tu clave activa, el saldo disponible y el historial de uso.

Invalidación inmediata al cambiar clave

Al generar una nueva clave desde tu panel, la anterior deja de funcionar instantáneamente. Asegúrate de actualizar la variable de entorno en tus scripts para evitar errores 401.

Endpoint principal

Ilustración de onda de sonido para: Endpoint principal

El endpoint principal de la API es POST https://api.winslots777.info/v1/audio/speech. Este punto de entrada procesa la solicitud de síntesis y devuelve el archivo de audio generado directamente en la respuesta.

Es el único punto necesario para convertir texto en audio. Solo requiere enviar el cuerpo JSON con el texto y la voz deseada, sin necesidad de gestión de sesiones o estados previos.

Método POST /v1/audio/speech

Envía una petición POST a la ruta /v1/audio/speech de la API base. La solicitud debe incluir la cabecera Authorization con la clave Bearer y el cuerpo JSON con los parámetros de generación.

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

Cuerpo JSON con input y voice

El cuerpo de la petición debe contener el campo input con el texto a narrar (máximo 4096 caracteres) y voice con uno de los 8 presets disponibles (ej. aria, nova, felix). También puedes incluir model, response_format y speed.

Si omites language, el sistema intenta adivinarlo por el script, pero para textos en latín distintos al inglés es recomendable especificarlo explícitamente para asegurar la pronunciación correcta.

  • input: Texto (≤4096 caracteres)
  • voice: ID de voz (ej. 'nova')
  • model: 'tts-1' o 'tts-1-hd'
  • speed: 0.25 a 4.0

Retorno de archivo de audio

La respuesta contiene el archivo de audio en el formato solicitado (response_format: mp3, wav, opus, flac, pcm). Si la síntesis falla, se devuelve un error JSON sin cargo. En caso de éxito, recibe el binario directamente.

Ejemplo de integración

Puedes usar el SDK oficial de OpenAI cambiando base_url a https://api.winslots777.info/v1. Esto permite usar client.audio.speech() ajustando la URL base, aprovechando la compatibilidad con el esquema de solicitud de OpenAI.

Comando cURL de ejemplo

Ilustración de onda de sonido para: Comando cURL de ejemplo

La forma más directa de validar la integración es mediante una solicitud HTTP básica. Este enfoque permite generar audio sin depender de librerías externas ni configurar entornos complejos, ideal para pruebas rápidas en terminales o scripts simples.

El comando utiliza el método POST sobre el endpoint principal, enviando los parámetros esenciales en formato JSON. La respuesta devuelve el archivo de audio generado directamente, listo para ser guardado o reproducido en tu flujo de trabajo.

Código de petición básico

Envía una petición POST al endpoint /v1/audio/speech. El cuerpo debe contener el model (tts-1 o tts-1-hd), el input con el texto a narrar y el voice deseado.

  • Método: POST
  • Endpoint: https://api.winslots777.info/v1/audio/speech
  • Content-Type: application/json

Inclusión de clave API

La autenticación se realiza mediante un encabezado Bearer. Usa la clave generada en /get-api-key/ para autorizar la solicitud y evitar errores 401.

Recepción de respuesta binaria

La respuesta contiene el archivo de audio binario en el formato solicitado. Guarda la salida estándar directamente en un archivo local para su uso posterior.

Integración con SDK OpenAI

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

La API de Narras mantiene la misma estructura de peticiones que el endpoint de OpenAI, lo que permite reutilizar librerías oficiales sin reescribir la lógica de conexión. Solo es necesario ajustar la URL base para dirigir las llamadas a nuestro servicio.

Cambio de base_url

Configura la URL base de tu cliente SDK a https://api.winslots777.info/v1. Esto redirige todas las peticiones hacia nuestra infraestructura manteniendo la compatibilidad con las claves de API existentes.

Compatibilidad con librerías oficiales

Las librerías de OpenAI funcionan correctamente al modificar este parámetro. No se requiere un SDK propietario ni adaptadores adicionales, lo que simplifica la integración en proyectos Python o Node.js.

Uso de client.audio.speech

Invoca el método client.audio.speech enviando el texto y la voz deseada. El SDK gestionará la serialización JSON y la recepción del archivo de audio generado.

Parámetros de la petición

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

La configuración de la síntesis se controla mediante tres campos clave en el cuerpo JSON. El modelo determina la calidad base, mientras que la voz asigna el timbre vocal y la velocidad ajusta la duración del audio generado.

Estos parámetros permiten adaptar rápidamente la salida a diferentes estilos de narración, desde locuciones rápidas para videos dinámicos hasta lecturas pausadas para contenido educativo, sin necesidad de post-procesamiento complejo.

Modelo tts-1 o tts-1-hd

El campo model acepta dos valores: tts-1 o tts-1-hd. Ambos utilizan exactamente el mismo motor de síntesis y tienen el mismo precio por carácter, por lo que la selección depende exclusivamente de la preferencia de calidad de audio percibida, no de un diferencial de costo o capacidad técnica entre ellos.

Voz seleccionada entre 8 presets

Debes especificar una de las ocho voces predefinidas mediante el campo voice. Cada voz tiene un perfil distinto: desde aria (narradora clara) hasta atlas (neutral, ideal para noticias) o orion (profundo, para documentales). La voz elegida determina el timbre, pero puede hablar en cualquiera de los 23 idiomas soportados.

  • aria: narradora cálida y clara
  • nova: brillante y enérgica
  • luna: suave, para historias
  • sage: calmada e instructiva
  • felix: dinámica, para promos
  • milo: amigable y conversacional
  • atlas: neutral, estilo noticioso
  • orion: profunda, estilo documental

Velocidad de 0.25 a 4.0

El parámetro speed permite ajustar la velocidad de habla entre 0.25 (muy lento) y 4.0 (muy rápido). El valor predeterminado es 1.0. Ajustar esta velocidad es útil para sincronizar la narración con el ritmo visual del video o para hacer que textos largos suenen más concisos.

Parámetros de la petición

Formatos de salida

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

La API permite generar audio en cinco formatos diferentes: mp3, wav, opus, flac y pcm. Esta variedad garantiza que puedas integrar la voz generada en cualquier flujo de producción, ya sea para edición de video o distribución web.

El formato elegido se especifica en el campo response_format del cuerpo de la petición. Cada formato tiene características técnicas distintas que afectan el tamaño del archivo y la compatibilidad con tus herramientas de postproducción.

Mp3, wav, opus, flac, pcm

Estos cinco formatos cubren las necesidades más comunes. MP3 ofrece compresión con pérdida. WAV y FLAC son sin pérdida, preservando la máxima fidelidad del audio generado. PCM es la forma bruta sin comprimir, y OPUS ofrece una compresión eficiente para web.

  • MP3: Compresión con pérdida, tamaño reducido.
  • WAV: Audio sin pérdida.
  • FLAC: Compresión sin pérdida, archivos ligeros.
  • OPUS: Alta eficiencia para transmisión web.
  • PCM: Formato de audio sin comprimir.

Selección en campo response_format

Para seleccionar el formato, añade la clave response_format a tu JSON de solicitud. El valor debe ser una de las cinco extensiones admitidas.

Calidad variable según formato

La calidad percibida y el tamaño del archivo varían según la elección. Los formatos sin pérdida como WAV y FLAC mantienen todos los detalles de la síntesis, mientras que MP3 y OPUS reducen el peso del archivo a costa de una pequeña pérdida de datos auditivos.

Límites y rendimiento

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

La API maneja hasta 60 peticiones por minuto por clave activa (10 antes del primer recargo). Si excedes este límite, recibirás un error 429.

Cada petición acepta un máximo de 4096 caracteres. Para textos más largos, debes dividirlos y unir los archivos de audio resultantes.

60 peticiones por minuto

El límite de velocidad es de 60 solicitudes por minuto por clave API. Antes de tu primer recargo, este límite se reduce a 10 peticiones por minuto para evitar abusos en la prueba gratuita.

4096 caracteres máximo por input

Cada campo input está limitado a 4096 caracteres, incluyendo espacios y puntuación. Si tu guion supera esta longitud, divide el texto en partes más pequeñas y concatena los archivos de audio generados.

Procesamiento secuencial en cola

Las solicitudes se procesan de forma secuencial. En momentos de alta demanda, las peticiones pueden esperar en una cola, lo que aumenta ligeramente el tiempo de generación comparado con el tiempo real de audio.

Códigos de error comunes

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

La API devuelve códigos de estado HTTP estándar para indicar el resultado de cada solicitud. Es fundamental verificar estos códigos en la respuesta para gestionar correctamente los errores de autenticación, límites de uso o formatos inválidos.

A continuación se detallan los errores más frecuentes que puedes encontrar al integrar el servicio en tu flujo de trabajo.

Error 401 por clave inválida

Este error indica que la clave Bearer proporcionada no es válida o ha caducado. Si emites una nueva clave en el panel, la anterior deja de funcionar inmediatamente.

  • Verifica que la cabecera Authorization incluya el prefijo Bearer seguido de tu clave actual.
  • Si has renovado tu clave recientemente, asegúrate de actualizarla en tu código.

Error 429 por límite excedido

Se produce al superar los 60 solicitudes por minuto. Si tu aplicación envía peticiones en ráfaga, implementa una lógica de reintentos con retroceso exponencial para evitar bloqueos temporales.

  • El límite se aplica por clave API.
  • Cuenta caracteres y no solo peticiones para optimizar tu uso.

Errores de formato JSON

La API espera un cuerpo JSON válido con los campos requeridos. Si falta input o voice, o si los tipos de datos no coinciden, la solicitud se rechazará.

  • Asegúrate de que input sea una cadena de texto.
  • Verifica que voice sea uno de los 8 presets válidos.

Escucha las 8 voces

Cada muestra a continuación fue generada por esta API a partir de la misma frase. Su energía la convierte en una herramienta efectiva para anuncios, introducciones rápidas o contenido que necesita ritmo.

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. Python documentation
  3. OpenAI API reference: create speech
  4. IETF RFC 7845: Ogg Opus
  5. openai-python on GitHub
  6. Creative Commons Attribution 4.0
  7. MDN: Web Speech API
  8. TRON developer hub: TRC-20
  9. ISO 639 language codes
  10. Node.js documentation
  11. LibriVox public-domain audiobooks
  12. LibriTTS-R paper (arXiv 2305.18802)

Más en este sitio