Image CDN

When you query content, asset fields return CDN URLs you can use directly in your applications. For images, you can append query parameters to resize, crop, convert format, and adjust quality on the fly, with no separate image pipeline required.

CDN delivery is public: GET requests do not need an API key. In TypeScript apps, use buildCdnUrl from @contismo/sdk to build transform URLs with typed options.

Asset URLs

Asset fields expose:

url: the full asset on the CDN
thumbnailUrl: a smaller preview generated at upload (when available)

Use these values from GraphQL or the REST assets API as-is. Paths include the project and environment, so always fetch content for the environment you intend to deliver.

Typical path shape:

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

Image transforms

Append query parameters to an image url to request a transformed variant. Parameters map to imgproxy open-source (non-Pro) options.

Compound values use colons, matching imgproxy argument order. For example, g=fp:0.5:0.3 or pad=10:20:10:20.

Size and resize

Param	Aliases	Values	Default	Purpose
`w`		positive integer	none	Width in pixels
`h`		positive integer	none	Height in pixels
`fit`		`fit`, `fill`, `fill-down`, `force`, `auto`, or `crop`	`fit`	Resize mode (`crop` is an alias for `fill`)
`mw`		positive integer	none	Minimum width
`mh`		positive integer	none	Minimum height
`z`	`zoom`	number, or `x:y`	`1`	Zoom factors
`dpr`		positive number	`1`	Device pixel ratio
`el`	`enlarge`	`1`, `t`, or `true`	off	Allow enlarging smaller sources
`ex`	`extend`	`1` or `1:gravity...`	off	Extend canvas to the target size
`exar`	`extend_ar`	`1` or `1:gravity...`	off	Extend to the requested aspect ratio

fit modes:

fit: scale to fit inside w × h, keep aspect ratio
fill / crop: fill w × h and crop overflow
fill-down: like fill, but crops down if the result is smaller than requested
force: stretch to exact w × h
auto: fill when orientation matches, otherwise fit

Crop, gravity, and trim

Param	Aliases	Values	Purpose
`g`	`gravity`	see below	Focal point when cropping or extending
`c`	`crop`	`width:height[:gravity...]`	Crop before resize (absolute or relative sizes)
`trim`		`threshold[:color[:equal_hor[:equal_ver]]]`	Remove surrounding background

Gravity types (g):

Edges / corners: no, so, ea, we, noea, nowe, soea, sowe, ce
Optional offsets: ce:10:20 (absolute if 1 or greater, relative if between 0 and 1)
Smart: sm
Focus point: fp:0.5:0.3 (x/y from 0 to 1)

Padding, rotate, and flip

Param	Aliases	Values	Purpose
`pad`	`padding`	`top[:right[:bottom[:left]]]`	CSS-style padding after transforms
`autorotate`		`1` / `true` or `0` / `false`	Honor EXIF orientation
`rot`	`rotate`	`0`, `90`, `180`, `270`, …	Rotate by right angles
`flip`		`horizontal[:vertical]` (`1`/`true`)	Flip axes
`bg`	`background`	hex (`fff`, `ffffff`) or `R:G:B`	Background fill (useful for JPEG from transparent sources)

Effects

Param	Aliases	Values	Purpose
`bl`	`blur`	positive number (sigma)	Gaussian blur
`sh`	`sharpen`	positive number (sigma)	Sharpen
`pix`	`pixelate`	positive integer	Pixelate block size

Output quality and format

Param	Aliases	Values	Default	Purpose
`q`		integer 0–100	`75`	Output quality
`fq`		`format:quality:...` pairs		Per-format quality, e.g. `jpeg:80:webp:70`
`fmt`		`webp`, `avif`, `jpg`, `jpeg`, `png`, `gif`, `ico`, `heic`, `bmp`, `tiff`	source	Output format (`jpeg` → `jpg`)
`mb`	`max_bytes`	positive integer	none	Lower quality until under this byte size (`jpg`, `webp`, `heic`, `tiff`)

Metadata and color

Param	Aliases	Values	Purpose
`sm`	`strip_meta`	`1`/`true` or `0`/`false`	Strip EXIF/IPTC metadata
`kcr`	`keep_copyright`	`1`/`true`	Keep copyright when stripping metadata
`scp`	`strip_icc`	`1`/`true` or `0`/`false`	Convert ICC to sRGB and strip profile
`ph`	`preserve_hdr`	`1`/`true` or `0`/`false`	Keep high bit depth
`eth`	`enforce_thumb`	`1`/`true`	Prefer embedded HEIC/AVIF thumbnail when present

Delivery helpers

Param	Aliases	Values	Purpose
`raw`		`1` / `true`	Stream the source file without processing
`fn`	`filename`	filename	`Content-Disposition` filename
`att`	`attachment`	`1` / `true`	Force download (`attachment`)

Examples

<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=""
/>

<!-- Crop then resize; strip metadata -->
<img
  src="https://cdn.contismo.com/.../photo.jpg?c=0.8:0.8:ce&w=800&fit=fill&sm=1"
  alt=""
/>

You can combine parameters freely. Omit any you do not need.

Thumbnails

For lists, cards, and other small previews, prefer thumbnailUrl when it is present. Thumbnails are generated at upload (up to 640×640) and avoid an extra transform request for common UI sizes.

Use the full url with transform parameters when you need a specific size, crop, or format for the main image.

Caching

Transformed responses are cached aggressively (Cache-Control: public, max-age=31536000, immutable). The same asset URL and query string always resolve to the same variant, which keeps delivery fast across channels and devices.

Bandwidth limits

Each plan includes a monthly CDN bandwidth allowance. If a project exceeds its limit, the CDN responds with HTTP 429.

Check current usage and plan limits in the Studio. Reduce egress by serving appropriately sized transforms (and thumbnails for previews) instead of full-resolution originals everywhere.