Image Processor

Image Processor is a Platform Resource that builds a new image, the derived image, from an image on the origin of an Application. On-request image transformation is a delivery model where the server builds each variant of an image at the time of the request. The URL of the request describes the variant, such as a width, a crop, a quality, or a format. Each variant comes from the one original, so the original is the only file you store and update.

In an Application, Image Processor reads the source image, the file on the origin, without changing it. The ims query string of the request describes the derived image, such as ?ims=fit-in/400x400. Even with no ims query string, Image Processor can convert an image to a format the browser accepts. Image Processor processes only the requests that a Request Phase rule with the Optimize Images behavior matches, and you write that rule in the Application’s Rules Engine. Use Image Processor to deliver one image in several sizes, crops, qualities, or formats, such as WEBP for browsers that accept it, without a file per variant.

Request path

An ims query string does not transform an image by itself: a rule with the Optimize Images behavior has to match the request first. Turning Image Processor on in an Application only makes that behavior available to its rules.

Solid arrows carry the request, and dotted arrows carry the response. Each label starts with the number of its step below.

1. A request for a path that holds an image reaches the Application, which runs its Request Phase rules. A rule for images matches on ${uri}, or on ${request_uri} with Application Accelerator on, against an argument such as \.(jpg|jpeg|gif|bmp|png|ico|webp|avif).
2. When no rule with Optimize Images matches, the source image is delivered unprocessed, even when the request carries ims.
3. A matching rule applies its behaviors. Optimize Images marks the request for Image Processor. When the rule also carries Set Cache Policy, that behavior applies the cache setting that holds the derived image. A rule can carry Optimize Images alone, because the behavior takes no argument.
4. When the derived image is already cached, Cache delivers it without processing.
5. Otherwise, Image Processor reads the source image from the origin and applies the ims query string to it. The derived image is delivered. The Application’s cache stores it only when the rule applies a cache setting with Set Cache Policy. Without one, every request reaches Image Processor, which answers a repeated transformation from its own cache.

When a rule with Optimize Images matches a path that does not return an image, the request fails with an empty 400, so the rule’s criteria have to match image paths only. To build that rule step by step, refer to Configure Image Processor on an application.

For how the delivered format is chosen, how the cache tells derived images apart, and where Image Processor stops, refer to Image delivery.

Rule structure

Image Processor acts through a Request Phase rule that carries the Optimize Images behavior. To process every request for an image path and cache each derived image, send this rule as the body of POST /v4/workspace/applications/<application-id>/request_rules:

• criteria compares the path with a list of image extensions through matches. ${request_uri} needs Application Accelerator, and ${uri} matches the same paths without it.
• optimize_images takes no attributes and marks the request for Image Processor. It requires Image Processor on the Application that runs the rule.
• set_cache_policy applies the cache setting whose ID is in attributes.value, and that cache setting stores each derived image. With ims in the fields of its cache_vary_by_querystring allowlist, each distinct ims string gets a cache key of its own. That field belongs to Application Accelerator, so it needs Application Accelerator on.
• Each request then carries its transformation in the URL, such as ?ims=400x. A processed response carries x-ims: Enabled, and x-original-image-size carries the size of the source image before the transformation.

Scope and limits

• Application: Image Processor is off in a new Application, and each Application turns it on separately, in its modules.image_processor.enabled field in the API. Even when it is on, Image Processor processes only the requests that a rule with Optimize Images matches. Main Settings shows where to turn it on in Azion Console and the API.
• Operations: one ims string can carry a resize, a crop, and a chain of filters. The operations are resize, crop, rotation, quality, watermark, format conversion, and fill, and fit-in fits an image inside an area without enlarging it. For the syntax and the values each one accepts, refer to URL parameters.
• Parameter position: ims can sit anywhere in the query string. An ims value that Image Processor cannot parse returns the source image untransformed.
• Formats: Image Processor reads JPEG, GIF, PNG, BMP, ICO, WEBP, and AVIF. Even with no ims parameter, it can convert an image to a format the browser accepts, such as WEBP or AVIF, and it converts a BMP image to JPEG or WEBP. A filters:format() filter returns the format it names, whatever Accept header the request carries. For how the delivered format is chosen, refer to Image delivery.
• Cache: once ims is in the allowlist of the cache setting, each distinct ims string, in each delivered format, is a separate stored object. A page that asks for four fixed widths stores four objects per delivered format, while a page that asks for arbitrary widths stores one per width and format. Once a derived image is in cache, it is delivered without processing. For the practices, refer to Applications best practices.
• Storage: Image Processor returns each derived image without saving it as an asset of the account, and you cannot upload images to Image Processor. The cache holds the derived images, and the source image stays where it already lives. A workflow that needs to keep a transformed file saves the response itself.
• Neighbors: WASM Image Processor is a WebAssembly library that processes images inside a Function. It runs in the code of that Function, separately from the Image Processor Platform Resource and its settings.
• Interfaces: you turn on Image Processor on the Main Settings tab of an Application in Azion Console, and through Azion API at /v4/workspace/applications/<application-id>. Azion CLI sets it with --image-processor on azion create application or azion update application. azion.config.js and Azion Lib set it with imageProcessorEnabled. For each field, flag, behavior, and header, refer to Image Processor settings.
• Observability: in Azion Console, Real-Time Metrics has an Image Processor tab with request charts, and Real-Time Events has an Image Processor dataset, which requires Image Processor on.
• Limits: one image takes up to 150 MB, 3840 pixels of width, and 2160 pixels of height. For every bound, refer to Applications limits, and for the rates, refer to Pricing. Azion pricing lists what each plan includes.
• Terms: the Applications glossary defines the words the Image Processor pages give a specific meaning, such as derived image, source image, autocrop, and fit-in.

Next steps