Enable image transformation

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.

In the ESA console, go to Site Management. In the Website column, click your target site.
In the navigation pane on the left, choose Speed and Network > Optimize.
Go to the Speed Optimization tab. Turn on the Image Transformations 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.

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.