CDN de imágenes

Cuando consultas contenido, los campos de archivo devuelven URL del CDN que puedes usar directamente en tus aplicaciones. En las imágenes, puedes agregar parámetros de consulta para redimensionar, recortar, convertir el formato y ajustar la calidad al vuelo, sin un flujo de imágenes aparte.

La entrega por CDN es pública: las solicitudes GET no necesitan una clave de API. En aplicaciones de TypeScript, usa buildCdnUrl de @contismo/sdk para armar URL de transformación con opciones tipadas.

URL de los recursos

Los campos de archivo exponen:

url: el recurso completo en el CDN
thumbnailUrl: una vista previa más pequeña generada al subir el archivo (cuando está disponible)

Usa estos valores de GraphQL o de la API REST de recursos tal como vienen. Las rutas incluyen el proyecto y el entorno, así que siempre obtén el contenido del entorno que quieres entregar.

Forma típica de la ruta:

/{projectId}/{environmentId}/{assetId}.{ext}

Transformaciones de imagen

Agrega parámetros de consulta a la url de una imagen para pedir una variante transformada. Los parámetros corresponden a las opciones de código abierto (no Pro) de imgproxy.

Los valores compuestos usan dos puntos, en el mismo orden de argumentos de imgproxy. Por ejemplo, g=fp:0.5:0.3 o pad=10:20:10:20.

Tamaño y redimensionado

Parámetro	Alias	Valores	Predeterminado	Propósito
`w`		entero positivo	ninguno	Ancho en píxeles
`h`		entero positivo	ninguno	Alto en píxeles
`fit`		`fit`, `fill`, `fill-down`, `force`, `auto` o `crop`	`fit`	Modo de redimensionado (`crop` es un alias de `fill`)
`mw`		entero positivo	ninguno	Ancho mínimo
`mh`		entero positivo	ninguno	Alto mínimo
`z`	`zoom`	número, o `x:y`	`1`	Factores de zoom
`dpr`		número positivo	`1`	Relación de píxeles del dispositivo
`el`	`enlarge`	`1`, `t` o `true`	desactivado	Permitir ampliar orígenes más pequeños
`ex`	`extend`	`1` o `1:gravity...`	desactivado	Ampliar el lienzo hasta el tamaño objetivo
`exar`	`extend_ar`	`1` o `1:gravity...`	desactivado	Ampliar hasta la relación de aspecto solicitada

Modos de fit:

fit: escalar para caber dentro de w × h, conservando la relación de aspecto
fill / crop: llenar w × h y recortar el excedente
fill-down: como fill, pero recorta hacia abajo si el resultado es más pequeño de lo solicitado
force: estirar hasta w × h exactos
auto: fill cuando la orientación coincide; de lo contrario, fit

Recorte, gravedad y recorte de bordes

Parámetro	Alias	Valores	Propósito
`g`	`gravity`	ver abajo	Punto focal al recortar o ampliar
`c`	`crop`	`width:height[:gravity...]`	Recortar antes de redimensionar (tamaños absolutos o relativos)
`trim`		`threshold[:color[:equal_hor[:equal_ver]]]`	Quitar el fondo circundante

Tipos de gravedad (g):

Bordes y esquinas: no, so, ea, we, noea, nowe, soea, sowe, ce
Desplazamientos opcionales: ce:10:20 (absoluto si es 1 o mayor, relativo si está entre 0 y 1)
Inteligente: sm
Punto de enfoque: fp:0.5:0.3 (x/y de 0 a 1)

Relleno, rotación y volteo

Parámetro	Alias	Valores	Propósito
`pad`	`padding`	`top[:right[:bottom[:left]]]`	Relleno al estilo CSS después de las transformaciones
`autorotate`		`1` / `true` o `0` / `false`	Respetar la orientación EXIF
`rot`	`rotate`	`0`, `90`, `180`, `270`, …	Rotar en ángulos rectos
`flip`		`horizontal[:vertical]` (`1`/`true`)	Voltear ejes
`bg`	`background`	hexadecimal (`fff`, `ffffff`) o `R:G:B`	Relleno de fondo (útil para JPEG a partir de orígenes transparentes)

Efectos

Parámetro	Alias	Valores	Propósito
`bl`	`blur`	número positivo (sigma)	Desenfoque gaussiano
`sh`	`sharpen`	número positivo (sigma)	Enfocar
`pix`	`pixelate`	entero positivo	Tamaño del bloque de pixelado

Calidad y formato de salida

Parámetro	Alias	Valores	Predeterminado	Propósito
`q`		entero 0–100	`75`	Calidad de salida
`fq`		pares `format:quality:...`		Calidad por formato, p. ej. `jpeg:80:webp:70`
`fmt`		`webp`, `avif`, `jpg`, `jpeg`, `png`, `gif`, `ico`, `heic`, `bmp`, `tiff`	origen	Formato de salida (`jpeg` → `jpg`)
`mb`	`max_bytes`	entero positivo	ninguno	Bajar la calidad hasta quedar por debajo de este tamaño en bytes (`jpg`, `webp`, `heic`, `tiff`)

Metadatos y color

Parámetro	Alias	Valores	Propósito
`sm`	`strip_meta`	`1`/`true` o `0`/`false`	Quitar metadatos EXIF/IPTC
`kcr`	`keep_copyright`	`1`/`true`	Conservar el copyright al quitar metadatos
`scp`	`strip_icc`	`1`/`true` o `0`/`false`	Convertir ICC a sRGB y quitar el perfil
`ph`	`preserve_hdr`	`1`/`true` o `0`/`false`	Conservar la profundidad de bits alta
`eth`	`enforce_thumb`	`1`/`true`	Preferir la miniatura HEIC/AVIF incrustada cuando exista

Ayudas de entrega

Parámetro	Alias	Valores	Propósito
`raw`		`1` / `true`	Transmitir el archivo de origen sin procesarlo
`fn`	`filename`	nombre de archivo	Nombre de archivo de `Content-Disposition`
`att`	`attachment`	`1` / `true`	Forzar la descarga (`attachment`)

Ejemplos

<img src="https://cdn.contismo.com/.../photo.jpg?w=800&fmt=webp" alt="" />

<img
  src="https://cdn.contismo.com/.../photo.jpg?w=400&h=400&fit=fill&g=fp:0.5:0.35&q=80&dpr=2"
  alt=""
/>

<img
  src="https://cdn.contismo.com/.../photo.jpg?w=1200&fmt=avif&q=70&bl=0.5"
  alt=""
/>

<img
  src="https://cdn.contismo.com/.../logo.png?w=200&bg=ffffff&fmt=jpg"
  alt=""
/>

<!-- Recortar y luego redimensionar; quitar metadatos -->
<img
  src="https://cdn.contismo.com/.../photo.jpg?c=0.8:0.8:ce&w=800&fit=fill&sm=1"
  alt=""
/>

Puedes combinar los parámetros con libertad. Omite los que no necesites.

Miniaturas

Para listas, tarjetas y otras vistas previas pequeñas, prefiere thumbnailUrl cuando esté presente. Las miniaturas se generan al subir el archivo (hasta 640×640) y evitan una solicitud de transformación extra para los tamaños habituales de la interfaz.

Usa la url completa con parámetros de transformación cuando necesites un tamaño, recorte o formato específico para la imagen principal.

Caché

Las respuestas transformadas se almacenan en caché de forma agresiva (Cache-Control: public, max-age=31536000, immutable). La misma URL de recurso y la misma cadena de consulta siempre resuelven a la misma variante, lo que mantiene la entrega rápida en distintos canales y dispositivos.

Límites de ancho de banda

Cada plan incluye una cuota mensual de ancho de banda del CDN. Si un proyecto supera su límite, el CDN responde con HTTP 429.

Revisa el uso actual y los límites del plan en el Studio. Reduce el tráfico de salida sirviendo transformaciones del tamaño adecuado (y miniaturas para las vistas previas) en lugar de los originales a resolución completa en todas partes.