---
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. **Override the browser cache**

   Under **Browser Cache**, select *Override cache settings*.

5. **Set how long the browser keeps the image**

   Set **Max Age** under **Browser Cache** to the duration the browser keeps the image.

6. **Override the cache behavior**

   Under **Cache**, select *Override cache behavior*.

7. **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.

8. **Set the query string behavior**

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

9. **Add the ims field**

   In **Fields**, enter `ims`.

10. **Turn on Sort**

    Turn on **Sort** to keep the cache key consistent regardless of the order the query string parameters arrive in.

11. **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**

> **Optional**
>
> To convert images to WEBP or AVIF format, add the **Add Request Header** behavior and set its value to `Accept: image/webp` or `Accept: image/avif`.

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:

```bash
curl --request PATCH \
  --url https://api.azion.com/v4/workspace/applications/<application_id> \
  --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/<application_id>/cache_settings \
  --header 'Accept: application/json' \
  --header 'Authorization: Token [TOKEN VALUE]' \
  --header 'Content-Type: application/json' \
  --data '{
  "name": "Images",
  "browser_cache": {
    "behavior": "override",
    "max_age": <browser_ttl_in_seconds>
  },
  "modules": {
    "cache": {
      "behavior": "override",
      "max_age": <edge_ttl_in_seconds>
    },
    "application_accelerator": {
      "cache_vary_by_querystring": {
        "behavior": "allowlist",
        "fields": ["ims"],
        "sort_enabled": true
      }
    }
  }
}'
```

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": <cache_setting_id>,
    "name": "Images",
    "browser_cache": {
      "behavior": "override",
      "max_age": <browser_ttl_in_seconds>
    },
    "modules": {
      "cache": {
        "behavior": "override",
        "max_age": <edge_ttl_in_seconds>,
        "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": true
        },
        "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 `<cache_setting_id>` with the ID you copied, send a `POST` request:

```bash
curl --request POST \
  --url https://api.azion.com/v4/workspace/applications/<application_id>/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": <cache_setting_id> }
      },
      {
        "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": <cache_setting_id> }
      },
      {
        "type": "optimize_images"
      }
    ]
  }
}
```

> **Optional**
>
> To convert images to WEBP or AVIF format, add a behavior of type `add_request_header` with `"attributes": {"value": "Accept: image/webp"}` or `"attributes": {"value": "Accept: image/avif"}`.

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 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:

```bash
curl --location --request PATCH 'https://api.azionapi.net/edge_applications/<application_id>' \
--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/<application_id>/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": "override",
    "browser_cache_settings_maximum_ttl": <browser_ttl_in_seconds>,
    "cdn_cache_settings": "override",
    "cdn_cache_settings_maximum_ttl": <edge_ttl_in_seconds>,
    "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": <cache_setting_id>,
        "name": "QS15D img",
        "browser_cache_settings": "override",
        "browser_cache_settings_maximum_ttl": <browser_ttl_in_seconds>,
        "cdn_cache_settings": "override",
        "cdn_cache_settings_maximum_ttl": <edge_ttl_in_seconds>,
        "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 `<cache_setting_id>` with the ID you copied, send a `POST` request:

```bash
curl --location --globoff 'https://api.azionapi.net/edge_applications/<application_id>/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": "<cache_setting_id>"
        },
        {
            "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": <rule_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=<width>x<height>`, the resolution requested; remove the query string to load the original file.

---

## 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.
- [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.