# Image Transformation Reference

> Source: https://agilitycms.com/docs/developers/image-transformation-reference

Every image in your Agility media library is served from Agility's image CDN. Add a query string to an image URL and the CDN resizes, crops or converts it on the fly, then caches the result. The original file is never changed.

This page lists the parameters the CDN applies and what it returns for each one. The behavior below was measured on 3 October 2026 with live requests against images in an Agility instance. If you need the editor steps for setting a focal point, see [Transforming Images with Query Strings and Focal Point](/docs/editors/transforming-images-using-query-strings).

## Parameters at a glance

| Parameter | Values | What it does |
| --- | --- | --- |
| `w` | Width in pixels | Resizes to this width. The height follows the original aspect ratio unless you also pass `h`. |
| `h` | Height in pixels | Resizes to this height. The width follows the original aspect ratio unless you also pass `w`. |
| `c` | `1`, `2` or `3` | How to fit the image when you pass both `w` and `h`. See [Fitting to a width and height](#fitting-to-a-width-and-height). |
| `q` | `1` to `100` | Output quality. Lower values give smaller files. |
| `format` | `auto`, `webp`, `avif`, `png`, `jpg`, `gif` | Output format. `auto` picks AVIF, WebP or the original format based on what the browser accepts. |

Parameter names are short and case-sensitive. `width=400`, `height=300` and `W=400` are ignored, and the original image is returned.

```text
https://cdn.aglty.io/{instance}/{folder}/{file}.jpg?format=auto&w=800
```

## Resizing with w and h

Pass `w` or `h` on its own to resize and keep the aspect ratio. Measured on a 2800 × 1575 JPEG:

| Query string | Returned |
| --- | --- |
| (none) | 2800 × 1575 JPEG, 417 KB |
| `?w=400` | 400 × 225 JPEG, 18.6 KB |
| `?h=300` | 533 × 300 JPEG, 28.8 KB |
| `?w=400&h=400` | 400 × 400 JPEG, cropped |

The CDN will upscale. `?w=5000` on the same 2800 px image returned a 5000 × 2813 image, which is larger and no sharper than the original. Request sizes up to the original's dimensions and let the browser scale beyond that if it must.

## Fitting to a width and height

When you pass both `w` and `h`, `c` controls how the image fits. `c` has no effect unless both are present. Measured on the same 2800 × 1575 JPEG with `?w=400&h=100`:

| `c` | Behavior | Returned |
| --- | --- | --- |
| not set | Crops to exactly `w` × `h`. Centered on the image's focal point if one is set, otherwise on the center. | 400 × 100 |
| `3` | Same as not set: crop to exactly `w` × `h`. | 400 × 100 |
| `1` | Resizes to `w` and keeps the aspect ratio. `h` is not applied, so the result can be taller than `h`. | 400 × 225 |
| `2` | Fits the whole image inside `w` × `h`, then pads it to exactly `w` × `h`. The padding is white for JPEG output and transparent for PNG output. | 400 × 100 (image 178 × 100 inside) |

Use the default crop for cards, thumbnails and anything with a fixed aspect ratio. Use `c=2` when no part of the image may be cut off, such as a logo in a fixed-size box.

## Focal point

An editor can set a focal point on an image in the image editor. The CDN uses it when it crops, that is, when you pass both `w` and `h` and leave `c` unset or set it to `3`. The crop is centered on the focal point as far as the image edges allow.

The focal point is not used for `c=1`, `c=2` or a single `w` or `h`, because none of those crop. You can't set or override a focal point in the query string.

Responses for an image with a focal point include `agility-focal-x` and `agility-focal-y` headers, in pixels from the top-left corner of the original. For example, a 1920 × 1080 image with its focal point set near the top right returned `agility-focal-x: 1600` and `agility-focal-y: 370`.

## Quality

`q` sets the output quality from `1` to `100`. On a 400 px wide JPEG, `q=1` returned 2.3 KB, `q=50` returned 9.9 KB and `q=100` returned 59.8 KB.

Values outside that range, such as `q=0` or `q=101`, are ignored and the original image is returned.

When you use `format=auto` without `q`, the CDN applies a quality of 60. Add `q` to override it, for example `?format=auto&q=80`.

## Output formats

### format=auto

`format=auto` returns the best format the requesting client says it accepts, based on the request's `Accept` header. The response carries `Vary: Accept`, so each format is cached separately. Measured on a 2800 × 1575 JPEG:

| Request `Accept` header includes | Returned |
| --- | --- |
| `image/avif` | AVIF, 124 KB |
| `image/webp` (no AVIF) | WebP, 162 KB |
| neither | JPEG, 225 KB (recompressed at quality 60) |

Current browsers list AVIF and WebP in the `Accept` header when they request an image, so they get the smaller formats. A client that lists neither, such as a server-side fetch that sends `Accept: */*`, gets JPEG.

> [!WARNING]
> A transparent PNG requested with `format=auto` by a client that accepts neither AVIF nor WebP is returned as a JPEG, and its transparent areas become white. Browsers that accept AVIF or WebP keep the transparency. If a transparent image must stay transparent for every client, request it without `format=auto` or with `format=png`.

### Choosing a format explicitly

`format=webp`, `format=avif`, `format=png`, `format=jpg` and `format=gif` convert to that format regardless of the `Accept` header. An unsupported value, such as `format=bmp`, is ignored and the original format is returned.

`format=auto` is the better choice for web pages, because it only sends AVIF or WebP to clients that can display them.

### Uploading WebP and AVIF

Since 28 October 2025, `.webp` is one of the default allowed image types in an image field's attributes. You can upload WebP files, but uploading a high-quality JPG or PNG and letting `format=auto` produce WebP or AVIF avoids compressing an already compressed file twice. See [Image Best Practices](/docs/overview/image-best-practices).

## GIFs

Animated GIFs can be resized and keep their animation. A 25-frame, 1350 × 786 GIF requested with `?w=300` returned a 300 × 175 GIF with all 25 frames.

GIFs stay GIFs. `format=auto` and `format=webp` both returned the GIF in its original format, even when the browser accepted AVIF and WebP.

## SVGs

SVGs are vector images and don't need resizing by the CDN. What the CDN returns depends on the query string:

| SVG URL | Returned |
| --- | --- |
| No query string | The original SVG (`image/svg+xml`) |
| `format` only, for example `?format=auto` or `?format=png` | The original SVG (`image/svg+xml`) |
| Any `w`, `h`, `c` or `q`, with or without `format` | A rasterized PNG (`image/png`) |

> [!CAUTION]
> Don't add `w`, `h`, `c` or `q` to an SVG URL. The CDN converts the SVG to a PNG, so it loses its vector sharpness and can render incorrectly. Use the plain URL and size the image on the page with CSS or the `width` and `height` attributes of the `<img>` tag. If your code adds transformation parameters to every image, skip URLs that end in `.svg`.

## Parameters that are not applied

Agility's image pipeline runs on Fastly. Fastly's own image optimizer documents many more parameters, but in our tests the Agility CDN applied only the parameters on this page. Adding any of these had no effect on the returned image: `width`, `height`, `quality`, `fit`, `crop`, `precrop`, `canvas`, `pad`, `dpr`, `orient`, `bg-color`, `blur`, `brightness`, `contrast`, `saturation`, `sharpen`, `trim`, `auto`, `optimize`, `enable`, `disable`, `frame`, `level`, `resize-filter` and `metadata`.

## Invalid values and errors

- An invalid value, such as `w=abc`, `w=-5`, `q=0` or `q=101`, is ignored. The CDN returns `200` with the image as if that parameter weren't there.
- A path that doesn't exist returns `404`.

## Size limits

These are measured results, not published limits:

- Output size is capped. A 16:9 image requested at `w=12000`, `w=20000` or `h=9000` was returned at 10922 × 6144, about 67 million pixels, rather than at the requested size. Requests at `w=8192` and `w=10000` were returned at the requested width.
- For upload size limits and how files over 15 MB are delivered, see [Introduction to Assets](/docs/editors/introduction-to-assets).

## Caching

Image responses we measured, transformed or not, carried `Cache-Control: public, max-age=604800` (seven days). Every distinct URL is a separate cached image, so use a small, fixed set of widths across your site, for example 400, 800, 1200 and 1600, rather than a different width for every layout.

## Checking that your images go through the image pipeline

Agility moved its image optimization to Fastly in May 2025. The changelog for that release notes that customers not using Fastly were not affected, so some features on this page, including AVIF and the focal point, may not apply to every instance.

To check yours, request one of your images with `?w=200` and look at the response headers. On the instance we measured, transformed responses included a `fastly-io-info` header describing the input and output images. If you don't see it, or a parameter on this page doesn't take effect, contact Agility support.

```bash
curl -sI "https://cdn.aglty.io/{instance}/{folder}/{file}.jpg?w=200" | grep -i fastly-io-info
```

## Bynder assets

The parameters on this page apply to files in your Agility media library. Images picked with the [Bynder app](/docs/apps/bynder) are Bynder resources. Since July 2025, you can include Bynder's own transformation parameters when you pick an asset with the Bynder app.

## Related articles

- [Transforming Images with Query Strings and Focal Point](/docs/editors/transforming-images-using-query-strings)
- [Image Best Practices](/docs/overview/image-best-practices)
- [Using the AgilityPic Component for Responsive Images](/docs/nextjs/using-the-agilitypic-component-for-responsive-images)
- [CDNs, Assets and Caching](/docs/editors/cdns-assets-and-caching)
- [Introduction to Assets](/docs/editors/introduction-to-assets)
- [Finding Where an Asset Is Used](/docs/editors/finding-where-an-asset-is-used)