Image Processor settings
Look up the interfaces that turn Image Processor on, the rule behaviors it adds, the cache fields it varies, and the data it reports.
Image Processor is a module of Applications, turned on for one application at a time. With the module on, a request for an image can carry an ims query string that describes a transformation. Azion returns a derived image built from the source image on the origin. This page carries the field, the flag, and the interface that sets each one, plus the behaviors, cache fields, headers, and datasets the module reaches.
Module activation
Five interfaces set the same switch, and the switch belongs to the application: one application can carry the module while another does not.
| Interface | Where you set it | Field or flag |
|---|---|---|
| Azion Console | The Default Modules group of the Modules section, on the Main Settings tab of an application | The Image Processor toggle, with the helper text “Enable dynamic image editing options.” |
| Azion API v4 | PATCH /v4/workspace/applications/<id> | modules.image_processor.enabled |
| Azion API v3 | PATCH https://api.azionapi.net/edge_applications/<id> | image_optimization |
| Azion CLI | azion create application and azion update application | --image-processor |
azion.config.js and Azion Lib | The application object | imageProcessorEnabled |
modules.image_processor.enabled and imageProcessorEnabled are booleans, and imageProcessorEnabled defaults to false. The Azion CLI flag takes a string: --image-processor true. In Azion Console, the toggle is saved with Save.
API v4 carries the switch in the modules object of the application:
The same modules object carries application_accelerator, cache, and functions, each with its own enabled boolean. API v3 names the switch image_optimization and takes it at the top level of the body.
Rules Engine behaviors
Three Rules Engine behaviors build the rule that processes an image. Optimize Images requires the Image Processor module on the application that runs the rule.
| Behavior | Phase | API type | What it does |
|---|---|---|---|
| Optimize Images | Request Phase | optimize_images | Enables Image Processor for the matched request. It takes no attributes. |
| Set Cache Policy | Request Phase | set_cache_policy | Applies a cache setting to the matched request. attributes.value carries the id of the cache setting, and Azion Console names it in a second dropdown. |
| Add Request Header | Request Phase | add_request_header | Adds a header to the request. attributes.value takes the form Field: value, such as Accept: image/webp or Accept: image/avif, which is what a conversion to those formats requires. |
A criterion of the same rule carries variable, operator, conditional, and argument. A rule that matches image requests reads ${request_uri} or ${uri} with the matches operator, against an argument such as \.(jpg|jpeg|gif|bmp|png|ico|webp|avif).
Cache variation
A derived image is cached under its own key. The cache key includes the ims query string, and a variation with a converted format carries the file format after the separator, as in httpsstatic.yourdomain.com/static/images/image_1.jpg?ims=880x@@webp.
Varying the cache on a query string is an Application Accelerator field: cache_vary_by_querystring lives under modules.application_accelerator in a cache setting. Varying the cache on ims therefore requires that module. Processing an image does not require it.
| Field | Console control | What it sets |
|---|---|---|
cache_vary_by_querystring.behavior | Behavior | How the cache handles query string parameters. The dropdown offers Allowlist, Denylist, Ignore, and All. |
cache_vary_by_querystring.fields | Fields | The query string parameters considered for cache variation, one per line. A cache setting for images carries ims. |
cache_vary_by_querystring.sort_enabled | Sort | Whether query string parameters are sorted, so that cache behavior does not depend on the order they arrive in. |
In Azion Console, the three controls sit in the Cache vary by Query String panel of the Application Accelerator section of a cache setting. For the rest of the fields a cache setting carries, including the maximum age of the cached object, refer to Cache Settings. For the other fields the module unlocks, refer to Application Accelerator settings.
Response headers
Azion returns two headers on the response to a request that carries an ims query string.
| Header | What it carries |
|---|---|
x-ims | Whether Image Processor handled the response. A processed response carries x-ims: Enabled. |
x-original-image-size | The size in bytes of the source image, before the transformation. |
Usage and event data
Azion reports Image Processor activity on six surfaces: two in Real-Time Metrics, two in Real-Time Events, and two in GraphQL.
| Surface | What it carries |
|---|---|
| The Image Processor tab of Real-Time Metrics | Metrics for the requests made to the images processed through Image Processor in your account, as Total Requests and Total Requests per Second charts. |
| The Bandwidth Saving graph of Real-Time Metrics, under Applications | The traffic the account saved. |
| The Image Processor dataset of Real-Time Events | The event records of requests made to applications using Image Processor. The dataset requires the module. |
| The Proxy Upstream field of Real-Time Events | ims_http, the value the field reads when the Tiered Cache origin is Image Processor. |
| The consumption dataset of GraphQL | productId 1441110021 and the metric images_processed, the total number of images processed by Image Processor. |
| The metrics datasets of GraphQL | The imageProcessedMetrics dataset and its fields. |
The data is available for up to 24 months. To build the consumption query and read its response, refer to Query usage data from Image Processor.
WASM Image Processor library
WASM Image Processor is a WebAssembly library that processes images inside a Functions function. It carries loadImage, resize, getImageResponse, and clean, and it writes webp, jpeg, and png. It is a different product surface from the Image Processor module, and no field on this page configures it. For more information, refer to WASM Image Processor.