Integración de la API de narración para museos

Por Equipo editorial AudioMuseo · Actualizado 2026-11-18

Esta guía detalla la integración de la API de texto a voz de AudioMuseo para generar narraciones profesionales en audioguías y contenido digital de museos. Aunque el producto es una API REST que requiere enviar solicitudes HTTP o usar el SDK de OpenAI, su estructura estandarizada facilita la conexión sin necesidad de programadores avanzados. El proceso permite obtener archivos de audio claros y fiables, ideales para entornos turísticos que exigen precisión en la reproducción de texto.

La documentación incluye ejemplos concretos con curl y la configuración de parámetros como voces, velocidad y formatos. Cubre desde la obtención de la clave API hasta el manejo de errores y el límite de 4096 caracteres por solicitud, asegurando que la integración funcione correctamente. Cada archivo generado lleva una marca de agua sintética y se entrega mediante endpoints estándar, garantizando un flujo de trabajo técnico preciso y verificable para proyectos de museos.

Integración de la API de narración para museos

Preguntas frecuentes

¿Cómo se obtiene la clave API inicial?

Regístrate en /get-api-key/ con Google o correo electrónico. La página muestra tu clave única, saldo, crédito de prueba, caracteres restantes, uso y un ejemplo de curl listo para usar. La clave se envía en el encabezado Authorization: Bearer tts-... Puedes emitir una nueva en cualquier momento; la anterior deja de funcionar inmediatamente.

¿Qué formato de audio es mejor para museos?

Elige mp3 para equilibrio entre calidad y tamaño, o wav para máxima compatibilidad. También puedes usar opus, flac o pcm. El formato se especifica en el campo response_format de la petición JSON. No hay un formato predeterminado obligatorio; la elección depende de tu infraestructura de reproducción.

¿Se puede usar la API con Python o solo curl?

Funciona con cualquier lenguaje que pueda hacer peticiones HTTP. Las SDK oficiales de OpenAI son compatibles cambiando el base_url a https://api.get68f.com/v1. Puedes usar Python, JavaScript o cualquier herramienta que soporte JSON y autenticación Bearer, sin necesidad de un SDK propio.

¿Cuántos caracteres se pueden enviar en una petición?

El campo input acepta hasta 4096 caracteres por petición. Esto incluye espacios y puntuación. Si tu guion es más largo, debes dividirlo en partes de máximo 4096 caracteres y unir los archivos de audio resultantes posteriormente para crear la narración completa.

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

tts-1-hd es el modelo de alta definición. Utiliza el mismo motor y tiene el mismo precio que tts-1. Ambos modelos generan audio de calidad profesional. La elección entre uno u otro no afecta al coste ni a la velocidad de procesamiento disponible.

¿Por qué tarda tanto la generación en fila?

Las solicitudes se procesan una tras otra. Bajo carga, una petición puede esperar en una cola. El tiempo típico es de unos pocos segundos para frases cortas. La generación larga es aproximadamente en tiempo real, pero la cola de procesamiento puede añadir latencia adicional.

¿Se puede cambiar la voz después de enviar el texto?

No. La voz se especifica en la petición inicial mediante el campo voice. Una vez enviada la solicitud y generado el audio, la voz está fija. Para cambiarla, debes enviar una nueva petición con el texto y la nueva voz deseada.

¿Qué ocurre si se envía un texto muy largo?

Debes dividirlo manualmente en fragmentos de hasta 4096 caracteres. Envía cada fragmento en una petición separada. Luego, une los archivos de audio resultantes. La API no realiza esta división automáticamente ni almacena los fragmentos intermedios para ti.

¿Cómo se especifica el idioma en la petición?

Usa el campo language con un código ISO. Si no se especifica, el sistema intenta adivinarlo, asumiendo inglés para texto en latín. Para textos en otros idiomas con alfabeto latino, es recomendable establecer el campo language explícitamente para evitar errores de pronunciación.

¿La API devuelve el audio como archivo o stream?

Devuelve el archivo de audio completo en la respuesta. No hay streaming ni WebSocket. El audio no se almacena en nuestros servidores tras la respuesta. Solo se conservan metadatos de la solicitud para facturación, como tiempo, caracteres y estado.

¿Se puede usar la API sin conexión a internet?

No. Es una API en la nube. Necesitas conexión a internet para enviar la petición POST a https://api.get68f.com/v1/audio/speech y recibir el archivo de audio. No hay versión offline ni instalación local disponible para este servicio.

¿Qué significa el error 429 en la API?

El error 429 indica que has excedido el límite de velocidad de la API. Por defecto, el límite es de 60 solicitudes por minuto por clave. Antes de realizar el primer recargo, este límite se reduce a 10 solicitudes por minuto. Para continuar, debes esperar a que se reinicie el contador o reducir la frecuencia de tus peticiones.

¿Se pueden usar las mismas claves en varios dispositivos?

Sí, una clave puede usarse desde múltiples dispositivos o aplicaciones simultáneamente. La limitación es de 60 solicitudes por minuto para la clave en total, independientemente de cuántos dispositivos la estén utilizando. No hay límite de dispositivos, solo de velocidad.

¿Hay un límite diario de solicitudes?

No hay límite diario fijo. El límite es por minuto: 60 solicitudes por minuto por clave. Puedes realizar tantas solicitudes como quieras en un día, siempre que respetes el límite de velocidad por minuto y tengas saldo suficiente en tu cuenta.

Primera solicitud

curl

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

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

Para comenzar a generar audioguías, accede a /get-api-key/ y regístrate mediante Google o correo electrónico. Si usas Google, recibes $0.50 de crédito válido por 7 días. Con correo, la cuenta se activa sin crédito inicial, listo para tu primera recarga mediante USDT en la red TRON.

Registro en la página de inicio

El registro es el primer paso para obtener acceso a la API. Puedes elegir autenticación con Google o crear una cuenta con correo y contraseña.

Ubicación de la clave en el panel

Una vez registrado, el panel muestra tu clave API única (formato tts-...), el saldo disponible y el uso de caracteres. Esta clave se usa en la cabecera de autenticación para todas las peticiones.

Emisión de una nueva clave activa

Puedes emitir una nueva clave en cualquier momento desde el panel. Al hacerlo, la clave anterior deja de funcionar inmediatamente, garantizando que solo tengas una clave activa por cuenta.

Primera petición con curl

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

La API de AudioMuseo responde a peticiones POST a https://api.get68f.com/v1/audio/speech. El cuerpo JSON acepta texto, voz y formato, permitiendo generar archivos de audio para audioguías de museos de forma inmediata.

Estructura del cuerpo JSON

La solicitud requiere campos específicos para definir la síntesis. El campo input contiene el texto a narrar (máximo 4096 caracteres). model puede ser "tts-1" o "tts-1-hd", ambos con el mismo motor. voice debe ser uno de los ocho presets disponibles, como "aria" o "atlas".

Parámetros obligatorios y opcionales

input, voice y response_format son esenciales para obtener el audio. speed permite ajustar la velocidad entre 0.25 y 4.0. language es opcional; si no se indica, el sistema detecta el idioma, pero se recomienda especificarlo para textos en latinos que no sean inglés.

Ejemplo completo de código para copiar

Utilice cURL para enviar la petición. Reemplace YOUR_API_KEY por su clave única. Este ejemplo genera un archivo MP3 con la voz "aria" a velocidad normal.

  • curl -X POST https://api.get68f.com/v1/audio/speech \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{"model": "tts-1", "input": "Bienvenidos a esta exposición", "voice": "aria", "response_format": "mp3"}'
Primera petición con curl

Uso con el SDK de OpenAI

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

Puede utilizar las librerías oficiales de OpenAI modificando el punto base URL hacia https://api.get68f.com/v1. Esto permite generar audio con la misma estructura de petición que el endpoint de OpenAI, manteniendo la compatibilidad con sus flujos de trabajo actuales sin necesidad de aprender una nueva sintaxis.

La autenticación se realiza pasando la clave API en la cabecera Authorization: Bearer <su-clave>. Esta configuración es suficiente para que las librerías reconozcan el servicio y envíen las solicitudes correctamente, asegurando que la integración técnica sea directa y predecible.

Modificación del punto base URL ['Ajuste la propiedad base_url de su cliente SDK para apuntar a https://api.get68f.com/v1. Esta dirección reemplaza la infraestructura nativa de OpenAI, redirigiendo las llamadas al motor de AudioMuseo.', 'Al modificar este parámetro, las solicitudes se procesan bajo los límites y la lógica de nuestra API, manteniendo la estructura JSON estándar esperada por las librerías.'] ['URL base: https://api.get68f.com/v1', 'Mantener la estructura de la petición original']

Configuración de la clave de autorización ['Incluya su clave activa en la cabecera Authorization: Bearer. Esta credencial identifica su cuenta y permite el uso de los créditos disponibles.', 'Asegúrese de que la clave tenga los permisos adecuados y esté vigente para evitar errores de autenticación durante la generación de las audioguías.']

Compatibilidad con librerías oficiales ['Las librerías oficiales de OpenAI funcionan correctamente con esta configuración adaptada. No se requiere una SDK propietaria ni plugins adicionales.', 'Esta compatibilidad facilita la integración para equipos que ya utilizan estas herramientas, reduciendo la curva de aprendizaje técnica.']

Parámetros de la petición

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

Los modelos tts-1 y tts-1-hd utilizan el mismo motor de síntesis y tienen el mismo precio ($10 por millón de caracteres), por lo que la elección depende exclusivamente de la calidad de audio deseada para la audioguía. Ambos aceptan texto de hasta 4096 caracteres por petición y devuelven el audio en el formato especificado.

Selección de voces predefinidas

Se pueden elegir entre ocho voces predefinidas, cada una con una personalidad distinta para adaptarse al contenido del museo. Por ejemplo, 'sage' ofrece una calma instruccional ideal para explicaciones técnicas, mientras que 'luna' aporta una voz suave para storytelling histórico.

Las voces no cambian de género ni de acento, pero cada una mantiene un tono constante. Si el texto no está en inglés, es necesario especificar el idioma para asegurar la pronunciación correcta.

  • aria: narradora clara y cálida
  • nova: tono brillante y enérgico
  • luna: voz suave para historias
  • sage: calma instruccional
  • felix: energía promocional
  • milo: conversación amistosa
  • atlas: neutralidad noticiosa
  • orion: profundidad documental

Ajuste de velocidad y formato de salida

La velocidad de reproducción se ajusta mediante un factor numérico entre 0.25 y 4.0, permitiendo ralentizar la voz para audioguías en espacios ruidosos o acelerarla para recorridos rápidos. El formato de salida puede seleccionarse entre mp3, wav, opus, flac y pcm, dependiendo de la necesidad de compatibilidad o calidad de archivo.

Formatos de audio soportados

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

MP3 para compatibilidad general

El formato MP3 es la opción predeterminada y más ampliamente compatible con reproductores de audioguías, sistemas de difusión en museos y aplicaciones móviles. Ofrece un equilibrio adecuado entre calidad de audio y tamaño de archivo, lo que facilita la transmisión rápida a través de redes móviles o Wi-Fi en zonas de alta concurrencia.

WAV para alta fidelidad

Utilice WAV cuando necesite audio sin comprimir para instalaciones fijas o reproducción en altavoces de alta gama dentro de las salas. Este formato preserva la integridad original de la síntesis, ideal para proyectos de audio donde la latencia de decodificación debe ser mínima y la fidelidad sonora es prioritaria sobre el ahorro de almacenamiento.

OPUS, FLAC y PCM para usos específicos

Formatos de audio soportados

Límites y rendimiento

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

Para audioguías de museos, el texto debe dividirse en fragmentos de máximo 4.096 caracteres por petición. Esto permite gestionar narraciones extensas manteniendo la coherencia del flujo de audio generado.

Límite de 4096 caracteres por petición

Si la narración supera este límite, debe dividirse en partes y unirse los archivos de audio resultantes. Los espacios y la puntuación cuentan como caracteres.

Velocidad de generación en tiempo real

La generación suele ser aproximadamente en tiempo real, con una tasa de unos 25 caracteres de texto por segundo de audio generado. Las frases cortas pueden tardar unos segundos.

Cola de procesos bajo carga elevada

Las peticiones se procesan de forma secuencial. Bajo carga elevada, es posible que una petición espere en una cola antes de comenzar la síntesis.

Esta demora es normal y no afecta al precio ni a la calidad del audio final.

Manejo de errores comunes

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

La API devuelve códigos HTTP estándar para indicar el estado de cada solicitud. Un 200 confirma que el audio se generó correctamente, mientras que un 429 indica que has superado los 60 solicitudes por minuto (o 10 antes del primer recargo). Los fallos de servidor (5xx) son temporales; si la síntesis falla por completo, el cargo se devuelve íntegramente.

Códigos de estado HTTP

Utiliza estos códigos para automatizar la gestión de errores en tu flujo de audioguías. Un 400 indica un error de formato en la petición, mientras que un 500 señala un problema interno temporal. Recuerda que las solicitudes fallidas no tienen costo.

  • 200: Éxito. El audio está listo para descarga.
  • 400: Error de sintaxis o parámetros inválidos.
  • 429: Límite de tasa excedido (60 req/min).
  • 500: Error interno del servidor. Reintenta más tarde.

Errores de autenticación

Un 401 indica credenciales inválidas o expiradas. Asegúrate de que la cabecera Authorization contenga tu clave API activa con el prefijo Bearer . Si emites una nueva clave, la antigua deja de funcionar inmediatamente.

Verifica que la clave no haya sido revocada por uso duplicado o seguridad. Si el error persiste, regresa al panel para generar una nueva clave de acceso.

  • 401: Clave ausente, incorrecta o inválida.
  • Verifica el formato Bearer token.
  • Renueva la clave desde el panel si es necesario.

Errores de límite de caracteres

Si el texto supera los 4096 caracteres, la API devolverá un error. Debes dividir el texto en fragmentos más pequeños y unir los archivos de audio resultantes manualmente o mediante un script.

Este límite es estricto por petición. Asegúrate de que tu lógica de división respete los límites antes de enviar la solicitud.

  • Límite máximo: 4096 caracteres por petición.
  • Divide el texto largo en fragmentos manejables.
  • Une los archivos de audio generados para la audioguía final.
Manejo de errores comunes

Autenticación y seguridad

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

La API de AudioMuseo utiliza un modelo de autenticación simple basado en tokens para garantizar que cada solicitud de narración provenga de una cuenta verificada. Para acceder al endpoint de síntesis de voz, es obligatorio incluir la cabecera de autorización en cada petición HTTP.

Este método asegura que solo las claves válidas puedan generar audio, manteniendo la integridad del consumo de caracteres y la facturación. La clave actúa como el identificador único que vincula la solicitud con el saldo disponible en tu cuenta.

Cabecera Authorization Bearer

Cada petición POST al endpoint /v1/audio/speech debe incluir la cabecera Authorization con el formato Bearer seguido de tu clave única. La estructura correcta es Authorization: Bearer tts-tu-clave-aqui, donde tu-clave-aqui es el valor alfanumérico generado en tu panel de control.

Esta cabecera es el único mecanismo de seguridad requerido. No se necesitan certificados adicionales ni firma de solicitudes complejas, lo que facilita la integración en sistemas de audioguías y aplicaciones turísticas sin necesidad de desarrolladores especializados.

Un solo parámetro de clave activo

Cada cuenta de AudioMuseo mantiene una única clave API activa en cualquier momento. Esta clave se asigna al crear la cuenta o al generar una nueva desde la sección de configuración del panel.

La simplicidad de tener un solo token activo reduce los errores de configuración en despliegues de gran escala, como redes de audioguías en museos, donde no es necesario gestionar rotaciones complejas de credenciales.

Invalidación inmediata de claves antiguas

Al emitir una nueva clave desde tu panel, la clave anterior deja de ser válida de forma instantánea. No hay periodo de transición ni retención de accesos antiguos.

Este mecanismo garantiza seguridad inmediata: si una clave se compromete o deseas rotarla por seguridad, la invalidación es automática y total, evitando accesos no deseados a tu saldo de caracteres.

Escucha las 8 voces

Cada muestra a continuación fue generada por esta API a partir de la misma frase. Disfruta del recorrido mientras escuchas las historias más fascinantes de cada sala en tu propio idioma.

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. Creative Commons Attribution 4.0
  3. LibriTTS-R paper (arXiv 2305.18802)
  4. openai-python on GitHub
  5. FFmpeg documentation
  6. OpenAI API reference: create speech
  7. LibriVox public-domain audiobooks
  8. curl documentation
  9. Node.js documentation
  10. LibriTTS-R corpus (OpenSLR 141)
  11. openai-node on GitHub
  12. MDN: Web Speech API

Más en este sitio