Enable image transformation-Edge Security Acceleration(ESA)-阿里云帮助中心

Edge Security Acceleration (ESA) transforms origin images at the edge—converting formats, adjusting quality, cropping, and scaling—then caches the results to improve delivery speed and reduce back-to-origin traffic.

Limits

Image processing is subject to the following limits.

Original image limits:

Supported image formats include JPEG, JPG, PNG, WebP, BMP, GIF, TIFF, and JPEG 2000.
The original image size must not exceed 10 MB.
The product of width × height must not exceed 16,777,216 pixels.
Note
For GIF images, the total width × height is the sum across all frames. You can use tools such as ImageMagick to view frame details of a GIF image.

Transformed image limits:

The product of width × height must not exceed 16,777,216 pixels.
When converting to WebP format, the product of width × height must not exceed 16,777,216 pixels, and neither width nor height may exceed 16,384 pixels individually. If the source image is animated, it becomes a static image after conversion to WebP.

Cache prefetching limits:

Image transformations do not apply to cache-prefetched content. During cache prefetch, ESA nodes fetch only the original image files without performing transformations.

Enable image transformation

In the ESA console, select Websites, and in the Website column, click the target site.
In the left navigation pane, select Speed and Network > Optimize.
Go to the Speed Optimization tab. Turn on the Status toggle. Then, add image processing parameters to your request URL to apply different image transformations.
For example, in JavaScript, you can write a URL-handling function to convert an image to another format.
```
function updateImageUrl(format) {
  let baseUrl = "https://example.com/image_01";
  let newUrl = `${baseUrl}.png?image_process=format,${format}`;
  document.getElementById('imageElement').src = newUrl;
}

// Example call to convert to BMP format
updateImageUrl("bmp");

// To convert to another format, such as JPG:
// updateImageUrl("jpg");
```
In the code above, image_process=format,${format} specifies the image transformation parameter. For more supported parameters and their valid values, see Supported image processing methods.

Adaptive WebP and Adaptive AVIF

After you turn on Adaptive WebP or Adaptive AVIF, ESA nodes detect browser compatibility and convert origin images to WebP or AVIF format before returning them to clients, which reduces the transmission size. You can turn on either setting independently.

To enable Adaptive WebP or Adaptive AVIF

In the Image Transform card, click Settings to expand the configuration form.
If the Status toggle is turned off, turn it on.
Turn on the Adaptive WebP or Adaptive AVIF toggle. You can turn on both toggles at the same time.
Click OK to save the configuration.

Adaptive conversion applies only when all of the following conditions are met:

The Accept header of the request contains image/avif or image/webp.
The size and resolution of the origin image do not exceed the limits of the image transformation feature. For details, see Limits.
The format of the origin image is JPEG, JPG, PNG, WebP, BMP, GIF, TIFF, JPEG 2000, or AVIF. The format is determined by the Content-Type response header or by the file extension in the request.
If you turn on both Adaptive WebP and Adaptive AVIF, ESA nodes convert images to AVIF format.

Transformation validation

Original request

Request example.com/bb.jpeg. The response returns a normally oriented image in .jpeg format.

Transformed request

Format conversion: To convert a .jpeg image to .png, change the request URL to example.com/bb.jpeg?image_process=format,png. The response returns a .png image.
Image rotation: To rotate the image 90° clockwise, change the request URL to example.com/bb.jpeg?image_process=rotate,90. The response returns the image rotated 90° clockwise.

Supported image processing methods

ESA supports applying one or more transformation parameters to an image. The following table lists supported parameters.

Image processing feature	Processing parameter	Description
Format conversion	format	Convert the image format.
Quality conversion	quality	Adjust image quality.
Image cropping	crop	Crop the image to a specified size.
Image scaling	resize	Scale the image to a specified size. Currently, only downscaling is supported; upscaling is not available.
Image rotation	Automatic rotation: auto-orient Specified rotation: rotate	Automatically rotate the image based on its metadata, or rotate it clockwise by a specified angle.
Image color	Brightness: bright Contrast: contrast Sharpening: sharpen	Adjust image brightness, contrast, and definition.
Add watermark	watermark	Add an image or text watermark to the picture.
Get info	info	Retrieve image information, including dimensions, format, and quality.

Relationship between site-wide and rule-based features

Site-wide configurations apply to all requests for a site. To enable image transformations only for specific requests, use rule-based configurations with conditions that match the desired requests. The rule-based counterpart of site-wide image transformation is Image Optimization.

Comparison with OSS image processing

Both ESA image transformation and OSS image processing transform images by using URL parameters. ESA processes images at the edge, making it suitable for edge acceleration scenarios. Object Storage Service (OSS) processes images on the storage service side, making it suitable for storage scenarios. If you already use OSS image processing, choose based on your scenario: use ESA for edge acceleration, and OSS for storage.