In Cloudflare Images, how does a /cdn-cgi/image/ URL resize and convert a remote image, and what must the zone enable first?
answer
- a fixed path prefix on your zone
- options sit between prefix and source
- comma-separated, at least one
- Images > Transformations, per zone
- Cf-Resized on the response
basics
~10 sA /cdn-cgi/image/<OPTIONS>/<SOURCE> URL asks Cloudflare to fetch the original, apply comma-separated options such as width=640,format=auto, and cache the result. It works only after transformations are enabled for that zone under Images > Transformations.
solid answer
~40 sThe URL shape is `https://<ZONE>/cdn-cgi/image/<OPTIONS>/<SOURCE-IMAGE>`. The options are comma-separated (`width=640,quality=80,format=auto`), at least one is required, and the source is either an absolute path on the zone or a full `https://` URL. Someone first enables transformations for the zone in **Images > Transformations**; by default the zone then accepts source images only from itself. On a miss Cloudflare fetches and caches the original, applies the options and caches the derivative, so the next request with the same options is served from the edge. `format=auto` serves the most efficient format the browser supports, such as AVIF or WebP, and is billed as one unique transformation however many formats it produces. A response that resizing was attempted on carries a `Cf-Resized` header, with `err=<code>` when it failed.
code
http · 3 linesGET /cdn-cgi/image/width=640,format=auto/uploads/sellers/42/chair.jpg HTTP/1.1
Host: shop.example
Accept: image/avif,image/webp,*/*go deeper
Recall the URL shape: zone, the /cdn-cgi/image/ prefix, comma-separated options, then the source path or URL, and that the zone must have transformations enabled first.
Explain the miss path: original fetched and cached, derivative generated and cached, and how format=auto and the unique-transformation count interact.
Show you can debug from headers: a missing Cf-Resized means resizing never ran, an err code says why, and purges target the source URL.
Frame which defaults a team must own: who may change the zone's sources, how custom paths are published, and how unique transformations are budgeted.
## The URL shape **Cloudflare Images** can optimize images it does not store, called **remote images**: photos on your own origin server, in an object storage bucket, or anywhere else reachable over HTTP. The simplest way to ask for one is the **URL interface**, a specially formatted path on any zone (a domain on Cloudflare) that has transformations turned on. ```plaintext https://<ZONE>/cdn-cgi/image/<OPTIONS>/<SOURCE-IMAGE> https://shop.example/cdn-cgi/image/width=640,quality=80,format=auto/uploads/sellers/42/chair.jpg ``` | Part | Meaning | |---|---| | `<ZONE>` | your proxied hostname | | `/cdn-cgi/image/` | a fixed, Cloudflare-managed prefix that marks the request as an image transformation | | `<OPTIONS>` | comma-separated parameters; a valid URL needs at least one | | `<SOURCE-IMAGE>` | an absolute path on the zone (`/uploads/...`) or an absolute `https://` or `http://` URL | The `/cdn-cgi/` endpoint exists on every proxied domain and is managed and served by Cloudflare, not by your origin. ## Turning it on Nothing happens until someone opens **Images > Transformations** in the dashboard, selects the zone and enables transformations. Two defaults matter from day one: - **Sources default to allowed origins.** The zone always accepts source images from itself; any other host must be added to the list under **Sources**. Switching to **Any origin** lets any public image be transformed on your zone, which is how resizing abuse starts. - **Billing is per unique transformation.** Each distinct combination of source image and parameters requested in a calendar month counts once, whatever its cache status; repeats that month are free. The Images Free plan includes 5,000 unique transformations a month. ## What one request does 1. Cloudflare checks the edge cache for a derivative with exactly these parameters. On a hit it is served without touching the origin. 2. On a miss it fetches the original, following the usual HTTP caching rules, and caches that original too, so other sizes of the same photo reuse it. 3. It applies the parameters, caches the derivative and returns it. Derivatives are cached for at least one hour, and longer when the original's `Cache-Control` allows. They are stored as variants under the source image's URL, so purging that source URL clears them. ## The options people actually use - `width` / `w` and `height` / `h`: target size in pixels; `width=auto` picks a width from client hints or the user agent. - `fit`: how the box is filled; the default `scale-down` never enlarges, `cover` crops to fill, `pad` adds a background. - `quality` / `q`: 1 to 100 or a perceptual level such as `medium-high`; the default is 85. - `format` / `f`: `auto`, `avif`, `webp`, `jpeg`, `baseline-jpeg` or `json` (metadata instead of pixels). - `dpr`: a density multiplier, at most 2, for high-density screens. - `metadata`: for JPEG output, `copyright` (the default) keeps only the copyright tag, `keep` keeps most EXIF including GPS, `none` drops it all. `format=auto` serves the most efficient format the requesting browser supports. AVIF encoding can be an order of magnitude slower, so a large image may come back as WebP or JPEG instead. Serving one URL as AVIF to some visitors and WebP to others is still one unique transformation. ## Reading the result A response that resizing was attempted on carries a **`Cf-Resized`** header. If it is missing, resizing never ran: transformations are off for the zone, or another Worker on the route intercepted the request. When resizing fails, `Cf-Resized` holds `err=<code>`, for example `9404` (the original does not exist), `9412` (the origin returned a non-image such as an HTML login page), `9413` (over 100 megapixels) or `9422` (the Free plan's monthly allowance is used up). With `onerror=redirect`, a failure on a same-zone source redirects the browser to the original instead. ## Limits worth knowing - A remote source can be up to **100 MB** and **100 megapixels** (for example 10,000x10,000), with at most 12,000 pixels on a side for formats other than WebP and AVIF. - **SVG** files are never resized; Cloudflare ignores the parameters and serves a sanitized SVG with scripts, links to other documents and cross-origin references removed. - Animations are limited by the total pixels across all frames: up to 100 megapixels can be delivered, but anything over 50 megapixels is served without transformations. - AVIF output is slower to encode, which is why `format=auto` and `format=avif` can fall back to WebP or JPEG for large images. These limits apply per image. A seller who uploads a 150 MB panorama will see an error code in `Cf-Resized`, not a resized photo, so validate uploads before they reach the catalogue. ## Custom paths To publish `/images/...` instead of `/cdn-cgi/image/...`, a Transform Rule rewrites the path, and the rule excludes requests whose `Via` header contains `image-resizing` so fetching the original does not loop. Wildcard rewrites work on every plan; regex rewrites need Business or Enterprise. If `robots.txt` disallows `/cdn-cgi/`, add `Allow: /cdn-cgi/image/` above it so search engines can still index the transformed images.
- How do you clear an updated product photo from every size Cloudflare has generated?Purge the full-size source image's URL. Resized versions are cached as variants under the source URL, so one purge of the original clears every derivative. Changing the options in the URL needs no purge at all, because a new set of options is a new derivative.
- Why might a /cdn-cgi/image/ URL return an error with err=9412 in Cf-Resized?Code 9412 means the origin answered with something that is not an image, typically an HTML error or login page. Check the source path, whether the origin requires authentication, and whether a redirect sends the fetch somewhere unexpected.
- Putting the options in a query string after the source image path
- Expecting /cdn-cgi/image/ URLs to work before transformations are enabled for the zone
- Believing format=auto is billed once per output format served
- Purging the /cdn-cgi/image/ URL instead of the original image's URL
- Assuming the zone accepts any public image as a source by default