--- name: azion-configure-image-processor-on-an-application description: >- Turn on Image Processor and create a Rules Engine rule that optimizes and caches images by the ims query string, from Console, API v4, or API v3. --- # Configure Image Processor on an application You configure [Image Processor](/en/documentation/platform/applications/#image-processor) on an application from Azion Console, the Azion API v4, or the Azion API v3. For a first look at the product, refer to the [Image Processor quickstart](/en/documentation/platform/applications/image-processor/quickstart/). --- ## Prerequisites - An application. To create one, refer to [Applications quickstart](/en/documentation/platform/applications/quickstart/). - Access to Azion Console, for the Console procedure. Refer to [Access Azion Console](/en/documentation/guides/platform/account-and-billing/how-to-access-azion-console/). - A [personal token](/en/documentation/guides/platform/account-and-billing/personal-tokens/), for the API procedures. --- ## Configure through Azion Console To turn on Image Processor and Application Accelerator: 1. **Open the application** Access [Azion Console](https://console.azion.com/) > **Applications** > **your application**. 2. **Go to Main Settings > Modules > Default Modules** 3. **Turn on Image Processor** 4. **Turn on Application Accelerator** 5. **Select Save** The application runs with both modules. Application Accelerator is required to vary the cache on the `ims` query string, because the **Cache vary by Query String** control sits in the cache setting's **Application Accelerator** section. It is not required to process an image. To create the cache setting that gives the derived images a time-to-live (TTL) and varies the cache key by `ims`: 1. **Open the Cache Settings tab** Access [Azion Console](https://console.azion.com/) > **Applications** > **your application**, then go to the **Cache Settings** tab. 2. **Select + Cache** 3. **Name the cache setting** In **Name**, enter a name that identifies the setting. For example: `Images`. 4. **Honor the browser cache** Under **Browser Cache**, select *Honor cache policies*. 5. **Override the cache behavior** Under **Cache**, select *Override cache behavior*. 6. **Set how long the derived image stays cached** Set **Max Age** under **Cache** to a long duration. Images change less often than other content, so a long duration reduces requests to the origin. Refer to [Cache Settings](/en/documentation/platform/applications/cache/cache-settings/) for the maximum you can set. 7. **Set the query string behavior** Under **Application Accelerator**, open **Cache vary by Query String** and set **Behavior** to *Allowlist*. 8. **Add the ims field** In **Fields**, enter `ims`. 9. **Select Save** The cache setting appears in the **Cache Settings** tab, with a long TTL and the cache key varying by the `ims` field. To create the rule that applies the cache setting and optimizes images: 1. **Go to the Rules Engine tab** 2. **Select + Rule** 3. **Name the rule** Enter a name for the rule. For example: `Optimize images`. 4. **Select Request Phase** 5. **Select the variable in the Criteria section** In the **Criteria** section, select the `${request_uri}` variable. 6. **Select matches as the comparison operator** 7. **Enter the argument** Enter `\.(jpg|jpeg|gif|bmp|png|ico|webp|avif)` as the argument. 8. **In the Behaviors section, select Set Cache Policy** 9. **Select the cache setting you created** 10. **Select + Add Behavior** 11. **Add the Optimize Images behavior** 12. **Select Save** > **Note** > > The rule adds no `Accept` header. Image Processor detects whether the browser supports WEBP from the browser's own `Accept` header and converts the image when it does, so each browser receives a format it reads. Forcing `Accept: image/webp` would send WEBP to browsers that never asked for it. Requests whose URI matches the argument carry the cache setting and run through Image Processor. To confirm that an image is optimized, inspect the page with your browser's developer tools and find the request for the image. The query string carries `ims=x`, the resolution requested; remove the query string to load the original file. --- ## Configure through the Azion API v4 To turn on Image Processor and Application Accelerator, send a `PATCH` request, replacing `[TOKEN VALUE]` with your personal token and `` with your application ID: ```bash curl --request PATCH \ --url https://api.azion.com/v4/workspace/applications/ \ --header 'Accept: application/json' \ --header 'Authorization: Token [TOKEN VALUE]' \ --header 'Content-Type: application/json' \ --data '{ "modules": { "application_accelerator": { "enabled": true }, "image_processor": { "enabled": true } }, "active": true }' ``` Read back, the application carries the following modules: ```json { "modules": { "application_accelerator": { "enabled": true }, "cache": { "enabled": true }, "functions": { "enabled": true }, "image_processor": { "enabled": true } } } ``` Application Accelerator is required to vary the cache on the `ims` query string, because that field belongs to `modules.application_accelerator` in a cache setting. It is not required to process an image. To create the cache setting that gives the derived images a time-to-live (TTL) and varies the cache key by `ims`, send a `POST` request: ```bash curl --request POST \ --url https://api.azion.com/v4/workspace/applications//cache_settings \ --header 'Accept: application/json' \ --header 'Authorization: Token [TOKEN VALUE]' \ --header 'Content-Type: application/json' \ --data '{ "name": "Images", "browser_cache": { "behavior": "honor" }, "modules": { "cache": { "behavior": "override", "max_age": }, "application_accelerator": { "cache_vary_by_querystring": { "behavior": "allowlist", "fields": ["ims"] } } } }' ``` For every field a cache setting carries, refer to [Cache Settings](/en/documentation/platform/applications/cache/cache-settings/). The response returns the cache setting Azion created: ```json { "state": "executed", "data": { "id": , "name": "Images", "browser_cache": { "behavior": "honor", "max_age": 0 }, "modules": { "cache": { "behavior": "override", "max_age": , "stale_cache": { "enabled": false }, "large_file_cache": { "enabled": false, "offset": 1024 }, "tiered_cache": { "enabled": false } }, "application_accelerator": { "cache_vary_by_querystring": { "behavior": "allowlist", "fields": ["ims"], "sort_enabled": false }, "cache_vary_by_cookies": { "behavior": "ignore", "cookie_names": [] }, "cache_vary_by_devices": { "behavior": "ignore", "device_group": [] }, "cache_vary_by_method": [] } } } } ``` Copy the `id` value. To create the rule that applies the cache setting and optimizes images, replacing `` with the ID you copied, send a `POST` request: ```bash curl --request POST \ --url https://api.azion.com/v4/workspace/applications//request_rules \ --header 'Accept: application/json' \ --header 'Authorization: Token [TOKEN VALUE]' \ --header 'Content-Type: application/json' \ --data '{ "name": "Optimize images", "description": "Apply the cache setting and optimize images", "active": true, "criteria": [ [ { "variable": "${request_uri}", "operator": "matches", "conditional": "if", "argument": "\\.(jpg|jpeg|gif|bmp|png|ico|webp|avif)" } ] ], "behaviors": [ { "type": "set_cache_policy", "attributes": { "value": } }, { "type": "optimize_images" } ] }' ``` The response echoes the criteria and behaviors Azion accepted: ```json { "data": { "criteria": [ [ { "variable": "${request_uri}", "operator": "matches", "conditional": "if", "argument": "\\.(jpg|jpeg|gif|bmp|png|ico|webp|avif)" } ] ], "behaviors": [ { "type": "set_cache_policy", "attributes": { "value": } }, { "type": "optimize_images" } ] } } ``` > **Note** > > The rule adds no `Accept` header. Image Processor detects whether the browser supports WEBP from the browser's own `Accept` header and converts the image when it does, so each browser receives a format it reads. Forcing `Accept: image/webp` would send WEBP to browsers that never asked for it. Requests whose URI matches the argument carry the cache setting and run through Image Processor. To confirm that an image is optimized, inspect the page with your browser's developer tools and find the request for the image. The query string carries `ims=x`, the resolution requested; remove the query string to load the original file. In the [Optimize images for websites and mobile apps](/en/documentation/use-cases/improve-performance-and-reliability/optimize-images-for-websites-and-mobile-apps/) use case, this section takes these values: | Setting | Value | | -------------------------- | ------------------------------------------------- | | Cache setting | `images` | | Browser Cache | *Honor cache policies* (`honor` in the API) | | Cache | *Override cache behavior*, **Max Age** `31536000` | | Cache vary by Query String | *Allowlist*, with `ims` as the only argument | The application has a cache setting that stores one object per distinct `ims` value, for up to a year. | Setting | Value | | ------------- | ------------------------------------------------------------------------------------------------------------------ | | **Name** | `images - optimize`, in the Request Phase | | **Criteria** | `${uri}` *starts with* `/images/` | | **Behaviors** | **Set Cache Policy** with the `images` cache setting, then **Optimize Images**. No **Add Request Header** behavior | Every request under `/images/` now reaches Image Processor and carries the `images` cache setting. --- ## Configure through the Azion API v3 To turn on Image Processor and Application Accelerator, send a `PATCH` request, replacing `[TOKEN VALUE]` with your personal token and `` with your application ID: ```bash curl --location --request PATCH 'https://api.azionapi.net/edge_applications/' \ --header 'Accept: application/json; version=3' \ --header 'Content-Type: application/json' \ --header 'Authorization: Token [TOKEN VALUE]' \ --data '{ "application_acceleration": true, "image_optimization": true }' ``` The response returns the updated value. Application Accelerator is required to vary the cache on the `ims` query string. It is not required to process an image. To create the cache setting that gives the derived images a time-to-live (TTL) and varies the cache key by `ims`, send a `POST` request: ```bash curl --location 'https://api.azionapi.net/edge_applications//cache_settings' \ --header 'Accept: application/json; version=3' \ --header 'Content-Type: application/json' \ --header 'Authorization: Token [TOKEN VALUE]' \ --data '{ "name": "QS15D img", "browser_cache_settings": "honor", "cdn_cache_settings": "override", "cdn_cache_settings_maximum_ttl": , "cache_by_query_string": "whitelist", "query_string_fields": [ "ims" ] }' ``` For every field a cache setting carries, refer to [Cache Settings](/en/documentation/platform/applications/cache/cache-settings/). The response returns the cache setting Azion created: ```json { "results": { "id": , "name": "QS15D img", "browser_cache_settings": "honor", "browser_cache_settings_maximum_ttl": 0, "cdn_cache_settings": "override", "cdn_cache_settings_maximum_ttl": , "cache_by_query_string": "whitelist", "query_string_fields": [ "ims" ], "enable_query_string_sort": false, "cache_by_cookies": "ignore", "cookie_names": null, "adaptive_delivery_action": "ignore", "device_group": [], "enable_caching_for_post": false, "l2_caching_enabled": false, "is_slice_configuration_enabled": false, "is_slice_edge_caching_enabled": false, "is_slice_l2_caching_enabled": false, "slice_configuration_range": 1024, "enable_caching_for_options": false, "enable_stale_cache": true, "l2_region": null } } ``` Copy the `id` value. To create the rule that applies the cache setting and optimizes images, replacing `` with the ID you copied, send a `POST` request: ```bash curl --location --globoff 'https://api.azionapi.net/edge_applications//rules_engine/request/rules' \ --header 'Accept: application/json; version=3' \ --header 'Authorization: Token [TOKEN VALUE]' \ --header 'Content-Type: application/json' \ --data '{ "name": "ImgProcessor", "behaviors": [ { "name": "set_cache_policy", "target": "" }, { "name": "optimize_images", "target": null } ], "criteria": [ [ { "variable": "${request_uri}", "operator": "matches", "conditional": "if", "input_value": "\\.(jpg|jpeg|gif|bmp|png)" }, { "variable": "${uri}", "operator": "matches", "conditional": "or", "input_value": "\\.(jpg|jpeg|gif|bmp|png)$" } ] ] }' ``` The response returns the rule Azion created: ```json { "results": { "id": , "name": "ImgProcessor", "phase": "request", "behaviors": [ { "name": "set_cache_policy", "target": "132186" }, { "name": "optimize_images", "target": null } ], "criteria": [ [ { "variable": "${request_uri}", "operator": "matches", "conditional": "if", "input_value": "\\.(jpg|jpeg|gif|bmp|png)" }, { "variable": "${uri}", "operator": "matches", "conditional": "or", "input_value": "\\.(jpg|jpeg|gif|bmp|png)$" } ] ], "is_active": true, "order": 3, "description": null } } ``` Requests whose URI matches either argument carry the cache setting and run through Image Processor. To confirm that an image is optimized, inspect the page with your browser's developer tools and find the request for the image. The query string carries `ims=x`, the resolution requested; remove the query string to load the original file. --- ## Request a fixed set of sizes from your pages Each distinct `ims` string is a separate object in cache and a separate transformation on its first request, so pages that ask for a few fixed sizes keep the number of variants small. The example asks for widths of `400`, `800`, and `1200` pixels with `fit-in` and `quality(85)`, for images under `/images/` on `www.example.com`. Replace each value with your own. In the template that renders an image, write the three sizes in the `srcset` of the `img` element, so the browser picks the smallest one that fits: ```html Blue shirt, front view ``` Keep `ims` as the last argument of the query string. Pages built from the template request one of three variants of each image, and each variant is processed once and then served from cache. The [Optimize images for websites and mobile apps](/en/documentation/use-cases/improve-performance-and-reliability/optimize-images-for-websites-and-mobile-apps/) use case uses the values of this example. --- ## Confirm that each variant is processed and cached Request one size of an image with a browser's `Accept` header: ```bash curl -sI -H "Accept: image/webp" "https://www.example.com/images/blue-shirt.jpg?ims=fit-in/800x800/filters:quality(85)" ``` The response carries `x-ims: Enabled`, `content-type: image/webp`, and `x-original-image-size` with the size of the original before the transformation. Request the same URL twice with the `Pragma: azion-debug-cache` header: ```bash curl -sI -H "Accept: image/webp" -H "Pragma: azion-debug-cache" "https://www.example.com/images/blue-shirt.jpg?ims=fit-in/800x800/filters:quality(85)" ``` The second response carries `x-cache: HIT`, and `x-cache-key` ends with the `ims` value and `@@webp`, the format the variant was converted to. The `400x400` URL, requested with the same headers, has a different `x-cache-key`, and its first response carries `x-cache: MISS`. The `800x800` URL requested with `-H "Accept: image/jpeg"` and the `Pragma: azion-debug-cache` header carries the original format in `content-type`, and its `x-cache-key` carries no `@@webp`. For how to read the debug headers, refer to [Check the cache status of a response](/en/documentation/guides/application-performance/cache-and-purge/check-page-cache-time/). In the [Build and run marketing websites](/en/documentation/use-cases/build-and-run-applications/build-and-run-marketing-websites/) use case, expect: - **Images are processed**, when Image Processor is on. Request an image with an `ims` query string, such as `https://www.example.com/images/hero.jpg?ims=400x`. The response carries `x-ims: Enabled`. In the [Build e-commerce storefronts](/en/documentation/use-cases/build-and-run-applications/build-e-commerce-storefronts/) use case, expect: - **Product images are processed.** An image requested with an `ims` query string, such as `https://www.example.com/media/blue-shirt.jpg?ims=400x`, carries `x-ims: Enabled`. These checks confirm the [Optimize images for websites and mobile apps](/en/documentation/use-cases/improve-performance-and-reliability/optimize-images-for-websites-and-mobile-apps/) use case. --- ## Next steps - [Image Processor URL parameters](/en/documentation/platform/applications/image-processor/url-parameters/) - the full `ims` grammar for resize, crop, rotate, filters, and format conversion. - [Image Processor settings](/en/documentation/platform/applications/image-processor/settings/) - every field the module and its cache setting carry, with their values and defaults. - [Applications limits](/en/documentation/platform/applications/limits/#image-processor) - the maximum size and dimensions Image Processor accepts. - [Cache Settings](/en/documentation/platform/applications/cache/cache-settings/) - every field a cache setting carries, including the maximum TTL. - [Build and run marketing websites](/en/documentation/use-cases/build-and-run-applications/build-and-run-marketing-websites/) - a marketing site deployed from GitHub on every push, served from Object Storage through Cache, and purged after each deploy. - [Build e-commerce storefronts](/en/documentation/use-cases/build-and-run-applications/build-e-commerce-storefronts/) - a storefront whose catalog pages are cached, whose cart and checkout stay dynamic, and whose product pages are purged when the catalog changes. - [Optimize images for websites and mobile apps](/en/documentation/use-cases/improve-performance-and-reliability/optimize-images-for-websites-and-mobile-apps/) - an image path that resizes on request, caches every variant, and serves a fixed set of sizes.