What is your developer-dependent CMS actually costing you? Calculate your costs and get a full report
What is your developer-dependent CMS actually costing you? Calculate your costs and get a full report
APIs
Every query parameter the Agility image CDN applies (w, h, c, q, format), what it returns, AVIF and WebP, focal point, GIF and SVG rules, and measured limits.
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.
| 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. |
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.
https://cdn.aglty.io/{instance}/{folder}/{file}.jpg?format=auto&w=800
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.
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.
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.
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.
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.
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.
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.
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.
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 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) |
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.
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.
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.404.These are measured results, not published limits:
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.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.
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.
curl -sI "https://cdn.aglty.io/{instance}/{folder}/{file}.jpg?w=200" | grep -i fastly-io-info
The parameters on this page apply to files in your Agility media library. Images picked with the Bynder app are Bynder resources. Since July 2025, you can include Bynder's own transformation parameters when you pick an asset with the Bynder app.