Media

El gestor de medios de Ágora CMS te permite acceder a todos los archivos subidos al workspace: imágenes, PDFs, vídeos y documentos. Las URLs son públicas, absolutas y permanentes — puedes usarlas directamente en tu frontend sin ningún procesamiento adicional. Este endpoint es útil para construir galerías, listados de documentos descargables o cualquier sección que consuma archivos gestionados desde el panel.

GET /media — Listado de archivos

Devuelve los archivos multimedia del workspace con paginación. Los archivos se ordenan por fecha de subida descendente (los más recientes primero). Ten en cuenta que este endpoint no acepta el parámetro lang porque los archivos multimedia no tienen traducción — son el mismo archivo para todos los idiomas.

Este endpoint no acepta el parámetro lang porque los archivos multimedia no tienen traducción.

curl "https://tu-panel.com/api/v1/media?web_id=abc-123&page=1&limit=20" \
  -H "X-API-Key: tu-api-key"

const response = await fetch(
  'https://tu-panel.com/api/v1/media?web_id=abc-123&page=1&limit=20',
  { headers: { 'X-API-Key': 'tu-api-key' } }
)
const { data, meta } = await response.json()

{
  "data": [
    {
      "id": "media-001",
      "filename": "mi-imagen.jpg",
      "url": "https://tu-panel.com/uploads/workspace-id/abc-123/mi-imagen.jpg",
      "mime_type": "image/jpeg",
      "size": 245120,
      "alt_text": "Descripción de la imagen para accesibilidad",
      "created_at": "2026-01-10T09:00:00Z"
    }
  ],
  "meta": { "total": 48, "page": 1, "limit": 20, "pages": 3 }
}

Campos de respuesta

El campo url es una URL absoluta lista para usar directamente como atributo src de una etiqueta <img> o href de un enlace de descarga. No necesitas construir ni transformar la URL — úsala tal cual.

Para filtrar por tipo de archivo en el cliente usa el campo mime_type. Por ejemplo, para mostrar solo imágenes filtra por mime_type.startsWith('image/'), y para PDFs comprueba mime_type === 'application/pdf'. Si necesitas filtrado por tipo en el servidor, contacta con soporte — esta funcionalidad puede añadirse como parámetro de query en futuras versiones.

Casos de uso

Galería de imágenes paginada. Llama al endpoint con limit=12 o limit=24 y filtra en cliente los resultados donde mime_type empieza por image/. Implementa un botón "Cargar más" que incremente la página y concatene los nuevos resultados al array existente.

// Galería paginada — ejemplo con fetch
let page = 1
let allImages = []

async function loadImages() {
  const res = await fetch(
    `/api/v1/media?web_id=${WEB_ID}&page=${page}&limit=24`,
    { headers: { 'X-API-Key': API_KEY } }
  )
  const { data, meta } = await res.json()
  const images = data.filter(f => f.mime_type.startsWith('image/'))
  allImages = [...allImages, ...images]
  page++
  return meta.page < meta.pages // devuelve true si hay más páginas
}

Listado de documentos descargables. Filtra por mime_type === 'application/pdf' para mostrar una sección de "Documentos" con enlaces de descarga. Muestra el filename como texto del enlace y el size formateado en KB o MB.

Carrusel de imágenes con lazy loading. Obtén las imágenes de una página y renderiza las etiquetas <img> con el atributo loading="lazy". Usa el campo alt_text en el atributo alt — si es null, usa una cadena vacía para las imágenes decorativas o el nombre del archivo como fallback.

Consejos y buenas prácticas

• Usa el campo url directamente como valor del atributo src en etiquetas <img>. La URL es absoluta y no necesita ningún prefijo adicional.
• Añade siempre loading="lazy" a las imágenes que no estén en el viewport inicial (above the fold). Mejora el rendimiento de carga significativamente en galerías con muchos elementos.
• Para imágenes grandes o galerías con mucho tráfico, considera poner un proxy de imágenes o CDN delante del dominio del panel. Servicios como Cloudflare Images, imgproxy o Cloudinary pueden redimensionar y optimizar las imágenes en vuelo a partir de la URL original de Ágora CMS.
• Muestra siempre el alt_text en el atributo alt. Si es null, usa alt="" para imágenes decorativas — nunca omitas el atributo.
• El campo size está en bytes. Para mostrarlo al usuario conviértelo: Math.round(size / 1024) para KB o (size / 1048576).toFixed(1) para MB.

Errores frecuentes

Ver también

• Posts — los posts incluyen el campo featured_image_url que apunta a un archivo del gestor de medios
• Tipos de contenido — las entradas CPT también pueden tener campos de tipo imagen que usan URLs del gestor de medios