Image Processor quickstart

Turn on Image Processor, cache each transformation separately, and request your first derived image in Azion Console, the Azion CLI, or the API.

Last updated

View as Markdown Agent setup

This guide instructs you through requesting your first derived image from an application. By the end you will have:

  • Image Processor turned on for one application.
  • A cache setting that stores each transformation as its own object.
  • A Rules Engine rule that sends image requests to the module.
  • A resized image returned from a URL you wrote.

Four objects carry that result, and each one is linked to the one before it. The application holds the module switch. The cache setting belongs to the application and decides that two different transformations are two different cached objects. The rule belongs to the application, matches image requests, and applies both the cache setting and the Optimize Images behavior. The image URL then carries the transformation in its ims query string. A request that no rule matches is delivered unprocessed, so the rule is what makes the query string mean anything.

Select the interface you will use. The prerequisites and every stage below follow that choice.

Prerequisites

  • An Azion account.
  • An application that already delivers images from an origin. To create one, refer to Applications quickstart.
  • The path of one image the application serves, so you can request it at the end.

Turn on Image Processor

The module is a switch on the application, and it is off until you set it. This stage turns on two modules.

Application Accelerator is the second for one reason: the field that varies the cache by a query string belongs to it, and the cache setting uses that field. Processing an image does not require the module, but caching each transformation separately does.

To turn on both modules in Azion Console:

Open the application

Access Azion Console > Applications, then select the application that delivers your images.

Go to the Main Settings tab
Turn on Image Processor

In the Modules section, turn on Image Processor, described as Enable dynamic image editing options.

Turn on Application Accelerator

The toggle is in the same section.

Select Save

The application now carries both modules, and the Optimize Images behavior becomes available to its rules.

One command sets both modules. Replace <application_id> with your application ID:

Run the update command
azion update application --application-id <application_id> --image-processor true --application-accelerator true
Read the output

The command confirms the application it changed:

Updated Application with ID <application_id>

The application now carries both modules, and the Optimize Images behavior becomes available to its rules.

One request sets both modules. Replace [TOKEN VALUE] with your personal token and <application_id> with your application ID:

Send the update request
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": { "enabled": true },
09 "image_processor": { "enabled": true }
10 }
11}
Read the response

A 202 carries "state": "pending", because the change is still propagating. The modules object of the response echoes every module of the application, including the ones you left alone:

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

The application now carries both modules, and the Optimize Images behavior becomes available to its rules.

Create a cache setting that varies on the ims query string

Without this step the cache cannot tell one transformation from another, and it may answer a request for a 400 pixel image with a 200 pixel one.

To create the cache setting in Azion Console:

Go to the Cache Settings tab
Select + Cache
Name the cache setting

In Name, enter images.

Expand Cache vary by Query String

The panel is in the Application Accelerator section.

Set Behavior to Allowlist
Add the ims field

In Fields, enter ims.

Select Save

The application now has a cache setting that stores one object per distinct ims value.

The create flags do not reach the maximum age, so the command sends the whole body from a file.

Write the cache setting to a file

Save the following as cache-setting.json:

JSON
01{
02 "name": "images",
03 "browser_cache": { "behavior": "honor" },
04 "modules": {
05 "cache": { "behavior": "override", "max_age": 31536000 },
06 "application_accelerator": {
07 "cache_vary_by_querystring": {
08 "behavior": "allowlist",
09 "fields": ["ims"],
10 "sort_enabled": true
11 }
12 }
13 }
14}

31536000 seconds is the ceiling of max_age, which suits images because they change rarely.

Create the cache setting

Replace <application_id> with your application ID:

azion create cache-setting --application-id <application_id> --file cache-setting.json

The command prints the id of the new cache setting:

Created Cache Settings configuration with ID 123464
Read the cache setting back
azion describe cache-setting --application-id <application_id> --cache-setting-id 123464 --format json

The output reports the ims allowlist and the maximum age the file set.

The application now has a cache setting that stores one object per distinct ims value. Record the id the command printed, because the rule applies it. For every flag the command accepts, refer to Azion CLI create.

One request carries the cache behavior and the query string allowlist together.

Send the create request

Replace <application_id> with your application ID:

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": { "behavior": "honor" },
09 "modules": {
10 "cache": { "behavior": "override", "max_age": 31536000 },
11 "application_accelerator": {
12 "cache_vary_by_querystring": {
13 "behavior": "allowlist",
14 "fields": ["ims"],
15 "sort_enabled": true
16 }
17 }
18 }
19}

31536000 seconds is the ceiling of max_age, which suits images because they change rarely.

Read the response

A 201 carries "state": "executed" and the cache setting it created. The response brings modules.cache.max_age back as 31536000 and echoes cache_vary_by_querystring exactly as you sent it.

Record data.id, such as 123463, because the rule applies it.

The application now has a cache setting that stores one object per distinct ims value.

For the rest of the fields a cache setting carries, including how long an object stays cached, refer to Cache Settings.

Create a rule that sends image requests to the module

The rule is what turns the query string into a transformation. It matches requests for image paths, applies the cache setting you created, and adds the Optimize Images behavior.

To create the rule in Azion Console:

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

In Name, enter Optimize images.

Select Request Phase
Select the variable

In the criteria, select ${request_uri}.

Select the operator matches
Enter the argument

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

Add the Set Cache Policy behavior

In the behaviors, select Set Cache Policy, then choose the images cache setting.

Select Add Behavior
Select Optimize Images
Select Save

Every request for a path ending in one of those extensions now reaches Image Processor, carries the images cache setting, and is processed when its URL asks for a transformation.

The criteria carry ${request_uri}, which a shell expands, and the argument carries backslashes, so the rule goes in a file.

Write the rule to a file

Save the following as rule.json, with the id of your cache setting in the set_cache_policy behavior:

JSON
01{
02 "name": "Optimize images",
03 "description": "Apply the cache setting and optimize images",
04 "active": true,
05 "criteria": [
06 [
07 {
08 "conditional": "if",
09 "variable": "${request_uri}",
10 "operator": "matches",
11 "argument": "\\.(jpg|jpeg|gif|bmp|png|ico|webp|avif)"
12 }
13 ]
14 ],
15 "behaviors": [
16 { "type": "set_cache_policy", "attributes": { "value": 123464 } },
17 { "type": "optimize_images" }
18 ]
19}

One rule carries both behaviors, and optimize_images takes no attributes.

Create the rule
azion create rules-engine --application-id <application_id> --phase request --file rule.json

The command prints the id of the new rule:

Created Rules Engine with ID 234571

Every request for a path ending in one of those extensions now reaches Image Processor, carries the images cache setting, and is processed when its URL asks for a transformation.

The criteria carry ${request_uri}, which a shell expands, and the argument carries backslashes, so the body is sent from a file.

Write the rule to a file

Save the following as rule.json, with the id of your cache setting in the set_cache_policy behavior:

JSON
01{
02 "name": "Optimize images",
03 "description": "Apply the cache setting and optimize images",
04 "active": true,
05 "criteria": [
06 [
07 {
08 "conditional": "if",
09 "variable": "${request_uri}",
10 "operator": "matches",
11 "argument": "\\.(jpg|jpeg|gif|bmp|png|ico|webp|avif)"
12 }
13 ]
14 ],
15 "behaviors": [
16 { "type": "set_cache_policy", "attributes": { "value": 123463 } },
17 { "type": "optimize_images" }
18 ]
19}

One rule carries both behaviors, and optimize_images takes no attributes.

Send the create 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 @rule.json
Read the response

A 202 carries "state": "pending", because the rule is still propagating. It echoes the criteria and both behaviors, and it carries the order the rule holds among the rules of the application.

Every request for a path ending in one of those extensions now reaches Image Processor, carries the images cache setting, and is processed when its URL asks for a transformation.

Optional — Converting an image to WEBP or AVIF requires the request to carry Accept: image/webp or Accept: image/avif. The Add Request Header behavior adds it to the same rule, so the conversion stops depending on what the browser sent. In the Azion CLI and the API, it is a behavior of type add_request_header, whose attributes carry "value": "Accept: image/webp". For the behavior’s fields, refer to Image Processor settings.

Request a derived image

Ask for a width and see the response change.

Request one of your images with an ims query string, replacing the host and the path with your own:

Shell
01curl -s -o /dev/null -w "%{http_code} %{content_type} %{size_download} bytes\n" \
02 -H "Accept: image/webp,image/*" \
03 "https://www.example.com/images/photo.jpg?ims=400x"

The response reports its status, its type, and its size:

200 image/webp 8312 bytes

Request the same image with no query string and compare the size. The processed response is smaller, and it may also carry a different format from the file on your origin, because Image Processor delivers WEBP to the browsers that accept it.

To confirm the module handled the response rather than the origin, read the headers:

curl -sI -H "Accept: image/webp" "https://www.example.com/images/photo.jpg?ims=400x"

A processed response carries x-ims: Enabled and the size of the source image before the transformation:

Text
01HTTP/2 200
02content-type: image/webp
03x-ims: Enabled
04x-original-image-size: 484156

You now have an application that transforms images on request, and a URL that describes the transformation.

Keep ims= as the last parameter in the URL. A request that carries another query string parameter after it may return a 504 error.

Next steps

Image Processor URL parametersEvery operation the ims query string expresses, beyond the resize you just used.Image deliveryWhat happens between the request and the derived image, and why the rule is required.Applications best practicesThe quality value, the caching choices, and the headers that keep a transformation cheap.Applications limitsThe bounds on one image, and what counts against the monthly Images meter.Configure Image Processor on an applicationThe same setup with the full API v3 object, when your automation still uses it.Troubleshoot ApplicationsWhat to check when an image comes back unprocessed or in the wrong format.