Configure Image Processor on an application

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.

Last updated

View as Markdown Agent setup

You configure 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.

Prerequisites

Configure through Azion Console

To turn on Image Processor and Application Accelerator:

Open the application

Access Azion Console > Applications > your application.

Go to Main Settings > Modules > Default Modules
Turn on Image Processor
Turn on Application Accelerator
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:

Open the Cache Settings tab

Access Azion Console > Applications > your application, then go to the Cache Settings tab.

Select + Cache
Name the cache setting

In Name, enter a name that identifies the setting. For example: Images.

Honor the browser cache

Under Browser Cache, select Honor cache policies.

Override the cache behavior

Under Cache, select Override cache behavior.

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 for the maximum you can set.

Set the query string behavior

Under Application Accelerator, open Cache vary by Query String and set Behavior to Allowlist.

Add the ims field

In Fields, enter ims.

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:

Go to the Rules Engine tab
Select + Rule
Name the rule

Enter a name for the rule. For example: Optimize images.

Select Request Phase
Select the variable in the Criteria section

In the Criteria section, select the ${request_uri} variable.

Select matches as the comparison operator
Enter the argument

Enter \.(jpg|jpeg|gif|bmp|png|ico|webp|avif) as the argument.

In the Behaviors section, select Set Cache Policy
Select the cache setting you created
Select + Add Behavior
Add the Optimize Images behavior
Select Save

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=<width>x<height>, 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 <application_id> with your application ID:

Shell
01curl --request PATCH \
02 --url https://api.azion.com/v4/workspace/applications/<application_id> \
03 --header 'Accept: application/json' \
04 --header 'Authorization: Token [TOKEN VALUE]' \
05 --header 'Content-Type: application/json' \
06 --data {
07 "modules": {
08 "application_accelerator": {
09 "enabled": true
10 },
11 "image_processor": {
12 "enabled": true
13 }
14 },
15 "active": true
16}

Read back, the application carries the following modules:

JSON
01{
02 "modules": {
03 "application_accelerator": { "enabled": true },
04 "cache": { "enabled": true },
05 "functions": { "enabled": true },
06 "image_processor": { "enabled": true }
07 }
08}

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:

Shell
01curl --request POST \
02 --url https://api.azion.com/v4/workspace/applications/<application_id>/cache_settings \
03 --header 'Accept: application/json' \
04 --header 'Authorization: Token [TOKEN VALUE]' \
05 --header 'Content-Type: application/json' \
06 --data {
07 "name": "Images",
08 "browser_cache": {
09 "behavior": "honor"
10 },
11 "modules": {
12 "cache": {
13 "behavior": "override",
14 "max_age": <edge_ttl_in_seconds>
15 },
16 "application_accelerator": {
17 "cache_vary_by_querystring": {
18 "behavior": "allowlist",
19 "fields": ["ims"]
20 }
21 }
22 }
23}

For every field a cache setting carries, refer to Cache Settings.

The response returns the cache setting Azion created:

JSON
01{
02 "state": "executed",
03 "data": {
04 "id": <cache_setting_id>,
05 "name": "Images",
06 "browser_cache": {
07 "behavior": "honor",
08 "max_age": 0
09 },
10 "modules": {
11 "cache": {
12 "behavior": "override",
13 "max_age": <edge_ttl_in_seconds>,
14 "stale_cache": { "enabled": false },
15 "large_file_cache": { "enabled": false, "offset": 1024 },
16 "tiered_cache": { "enabled": false }
17 },
18 "application_accelerator": {
19 "cache_vary_by_querystring": {
20 "behavior": "allowlist",
21 "fields": ["ims"],
22 "sort_enabled": false
23 },
24 "cache_vary_by_cookies": { "behavior": "ignore", "cookie_names": [] },
25 "cache_vary_by_devices": { "behavior": "ignore", "device_group": [] },
26 "cache_vary_by_method": []
27 }
28 }
29 }
30}

Copy the id value. To create the rule that applies the cache setting and optimizes images, replacing <cache_setting_id> with the ID you copied, send a POST request:

Shell
01curl --request POST \
02 --url https://api.azion.com/v4/workspace/applications/<application_id>/request_rules \
03 --header 'Accept: application/json' \
04 --header 'Authorization: Token [TOKEN VALUE]' \
05 --header 'Content-Type: application/json' \
06 --data {
07 "name": "Optimize images",
08 "description": "Apply the cache setting and optimize images",
09 "active": true,
10 "criteria": [
11 [
12 {
13 "variable": "${request_uri}",
14 "operator": "matches",
15 "conditional": "if",
16 "argument": "\\.(jpg|jpeg|gif|bmp|png|ico|webp|avif)"
17 }
18 ]
19 ],
20 "behaviors": [
21 {
22 "type": "set_cache_policy",
23 "attributes": { "value": <cache_setting_id> }
24 },
25 {
26 "type": "optimize_images"
27 }
28 ]
29 }

The response echoes the criteria and behaviors Azion accepted:

JSON
01{
02 "data": {
03 "criteria": [
04 [
05 {
06 "variable": "${request_uri}",
07 "operator": "matches",
08 "conditional": "if",
09 "argument": "\\.(jpg|jpeg|gif|bmp|png|ico|webp|avif)"
10 }
11 ]
12 ],
13 "behaviors": [
14 {
15 "type": "set_cache_policy",
16 "attributes": { "value": <cache_setting_id> }
17 },
18 {
19 "type": "optimize_images"
20 }
21 ]
22 }
23}

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=<width>x<height>, the resolution requested; remove the query string to load the original file.

In the Optimize images for websites and mobile apps use case, this section takes these values:

SettingValue
Cache settingimages
Browser CacheHonor cache policies (honor in the API)
CacheOverride cache behavior, Max Age 31536000
Cache vary by Query StringAllowlist, 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.

SettingValue
Nameimages - optimize, in the Request Phase
Criteria${uri} starts with /images/
BehaviorsSet 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 <application_id> with your application ID:

Shell
01curl --location --request PATCH 'https://api.azionapi.net/edge_applications/<application_id>' \
02--header 'Accept: application/json; version=3' \
03--header 'Content-Type: application/json' \
04--header 'Authorization: Token [TOKEN VALUE]' \
05--data {
06 "application_acceleration": true,
07 "image_optimization": true
08}

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:

Shell
01curl --location 'https://api.azionapi.net/edge_applications/<application_id>/cache_settings' \
02--header 'Accept: application/json; version=3' \
03--header 'Content-Type: application/json' \
04--header 'Authorization: Token [TOKEN VALUE]' \
05--data {
06 "name": "QS15D img",
07 "browser_cache_settings": "honor",
08 "cdn_cache_settings": "override",
09 "cdn_cache_settings_maximum_ttl": <edge_ttl_in_seconds>,
10 "cache_by_query_string": "whitelist",
11 "query_string_fields": [
12 "ims"
13 ]
14}

For every field a cache setting carries, refer to Cache Settings.

The response returns the cache setting Azion created:

JSON
01{
02 "results": {
03 "id": <cache_setting_id>,
04 "name": "QS15D img",
05 "browser_cache_settings": "honor",
06 "browser_cache_settings_maximum_ttl": 0,
07 "cdn_cache_settings": "override",
08 "cdn_cache_settings_maximum_ttl": <edge_ttl_in_seconds>,
09 "cache_by_query_string": "whitelist",
10 "query_string_fields": [
11 "ims"
12 ],
13 "enable_query_string_sort": false,
14 "cache_by_cookies": "ignore",
15 "cookie_names": null,
16 "adaptive_delivery_action": "ignore",
17 "device_group": [],
18 "enable_caching_for_post": false,
19 "l2_caching_enabled": false,
20 "is_slice_configuration_enabled": false,
21 "is_slice_edge_caching_enabled": false,
22 "is_slice_l2_caching_enabled": false,
23 "slice_configuration_range": 1024,
24 "enable_caching_for_options": false,
25 "enable_stale_cache": true,
26 "l2_region": null
27 }
28}

Copy the id value. To create the rule that applies the cache setting and optimizes images, replacing <cache_setting_id> with the ID you copied, send a POST request:

Shell
01curl --location --globoff 'https://api.azionapi.net/edge_applications/<application_id>/rules_engine/request/rules' \
02--header 'Accept: application/json; version=3' \
03--header 'Authorization: Token [TOKEN VALUE]' \
04--header 'Content-Type: application/json' \
05--data {
06 "name": "ImgProcessor",
07 "behaviors": [
08 {
09 "name": "set_cache_policy",
10 "target": "<cache_setting_id>"
11 },
12 {
13 "name": "optimize_images",
14 "target": null
15 }
16 ],
17 "criteria": [
18 [
19 {
20 "variable": "${request_uri}",
21 "operator": "matches",
22 "conditional": "if",
23 "input_value": "\\.(jpg|jpeg|gif|bmp|png)"
24 },
25 {
26 "variable": "${uri}",
27 "operator": "matches",
28 "conditional": "or",
29 "input_value": "\\.(jpg|jpeg|gif|bmp|png)$"
30 }
31 ]
32 ]
33}

The response returns the rule Azion created:

JSON
01{
02 "results": {
03 "id": <rule_id>,
04 "name": "ImgProcessor",
05 "phase": "request",
06 "behaviors": [
07 {
08 "name": "set_cache_policy",
09 "target": "132186"
10 },
11 {
12 "name": "optimize_images",
13 "target": null
14 }
15 ],
16 "criteria": [
17 [
18 {
19 "variable": "${request_uri}",
20 "operator": "matches",
21 "conditional": "if",
22 "input_value": "\\.(jpg|jpeg|gif|bmp|png)"
23 },
24 {
25 "variable": "${uri}",
26 "operator": "matches",
27 "conditional": "or",
28 "input_value": "\\.(jpg|jpeg|gif|bmp|png)$"
29 }
30 ]
31 ],
32 "is_active": true,
33 "order": 3,
34 "description": null
35 }
36}

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=<width>x<height>, 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
01<img
02 src="https://www.example.com/images/blue-shirt.jpg?ims=fit-in/800x800/filters:quality(85)"
03 srcset="https://www.example.com/images/blue-shirt.jpg?ims=fit-in/400x400/filters:quality(85) 400w,
04 https://www.example.com/images/blue-shirt.jpg?ims=fit-in/800x800/filters:quality(85) 800w,
05 https://www.example.com/images/blue-shirt.jpg?ims=fit-in/1200x1200/filters:quality(85) 1200w"
06 alt="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 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:

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:

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.

In the 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 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 use case.

Next steps