Skip to main content
Crop is a feature that trims original JPG or PNG images before delivery over the CDN. Add crop query parameters to image URLs in the website source code to specify the target area and its location. When a user requests a webpage, the CDN returns it with cropped images. An origin server hosts a 750×1150 px image. With Crop configured, the CDN delivers a 500×400 cropped version to end users while the original 750×1150 image remains on the origin.
Original image

​
Enable the crop feature

Crop is part of the paid Image Stack option. Image Stack also supports converting images to WebP or AVIF, resizing, and adjusting quality. To use Crop, activate Image Stack following the Enable Image Stack guide.

​
Use crop

1. Open the website source code. 2. Find the strings with the URLs of the images to crop. 3. Add the query strings to the URLs of the images as follows:
where image.jpg is the image URL on the website. The Crop parameters section lists all available parameters. 4. Save the changes in the website source code. After saving, the CDN delivers cropped images to users requesting the webpage.

​
Crop parameters

Crop cuts out a section of an original image for delivery to users. Append a query string to the image URL to specify the target area and its location.

​
Crop an image by customizing its aspect ratio

Parameter: ?crop=16:9 where:
  • 16 = the width component of the target aspect ratio
  • 9 = the height component of the target aspect ratio
The tool crops an image evenly to fit the specified aspect ratio. Example. An origin server hosts a 400×300 image with a 4:3 aspect ratio. To illustrate this, a grid has been placed on the picture.
Crop an image by customizing its aspect ratio
Set a new aspect ratio (4:5) by adding the query parameter to the image URL:
The tool selects a section with this aspect ratio at the center of the original image.
Crop an image by customizing its aspect ratio
Then it cuts off the unwanted parts. The resulting image looks as follows:
Crop an image by customizing its aspect ratio
How the tool defines what to crop: It compares the values in the aspect ratio (4 and 5, in this example) and chooses the greater one (5). This determines which side of the original image is not cropped. The value 5 corresponds to the height, so the height remains the same: 300 px. It calculates the width to fit the aspect ratio by multiplying the original height by the ratio of 4:5: 300 × (4/5) = 240 px. It places a 240×300 area at the center of the original image and crops it.

​
Crop an image at its center

Parameter: ?crop=300,200 where:
  • 300 = the target width
  • 200 = the target height
The tool keeps the target area at the center and cuts off the unwanted parts. Example. An origin server hosts a 400×300 image. To keep only a 200×100 section at the center, add the desired parameter to the image URL:
Crop an image at its center
The tool crops a 200×100 area from the center. The resulting image looks as follows:
Crop an image at its center

​
Crop from a specific location

To cut out a section from a specific location, add the target width and height parameters (?crop=(width),(height)) and then the location of the section. The location can be specified in four ways, described in the subsections below.

​
Specify a location with two offsets measured in pixels

Parameter: ?crop=300,200,x100,y50 where:
  • 300 = the target width
  • 200 = the target height
  • 100 = the number of pixels to offset from the original left side
  • 50 = the number of pixels to offset from the original top
The tool positions the target area so that its upper-left corner is at the specified coordinate, then cuts out the section. Example. An origin server hosts a 400×300 image; the goal is to cut out a 200×100 section with the dog’s muzzle.
Crop a section of an original image from a specific location
To crop an image, add the query parameter to the URL:
Before being delivered to an end user, the image goes through the following conversions: 1. The target area is 200×100 (crop=200,100), so the tool selects this area in the picture.
Crop a section of an original image from a specific location
2. The coordinates of the starting point are 107 px from the left side and 30 pixels from the top (x107,y30). The tool drags the target area so that its upper-left corner is at this point.
Crop a section of an original image from a specific location
3. The tool cuts out the section. The cropped image looks as follows:
Crop a section of an original image from a specific location

​
Specify a location using two coordinates measured as a percentage of the original image

Parameter: ?crop=300,200,x25p,y10p where:
  • 300 = the target width
  • 200 = the target height
  • 25 = the percent of the original width to offset from the left side
  • 10 = the percent of the original height to offset from the top
The tool positions the target area so that its upper-left corner is at the specified coordinate, then cuts out the section. Example. An origin server hosts a 400×300 image; the goal is to cut out a 200×100 section with the dog’s muzzle.
Crop a section of an original image from a specific location
To crop an image, add the query parameter to the URL:
Before being delivered to an end user, the image goes through the following conversions: 1. The target area is 200×100 (crop=200,100), so the tool selects this area in the picture.
Crop a section of an original image from a specific location
2. The starting point for cropping (x25p,y10p): offset 25% of the original width from the left side and 10% of the original height from the top. The tool drags the target area so that its upper-left corner is at this point.
Crop a section of an original image from a specific location
3. Then it cuts out the section. The cropped image looks as follows:
Crop a section of an original image from a specific location

​
Specify a location using the ratio of unwanted areas

Parameter: ?crop=300,200,offset-x20,offset-y40 where:
  • 300 = the target width
  • 200 = the target height
  • 20 = the percent of the unwanted width that should be cropped from the left side
  • 40 = the percent of the unwanted height that should be cropped from the top
The tool positions the target area so that the specified percentage of unwanted area remains on the left and on the top, then crops the image. Example. An origin server hosts a 400×300 image; the goal is to cut out a 100×100 section with the dog’s paws.
Crop a section of an original image from a specific location
To crop the image, add the query parameter to the URL:
Before being delivered to an end user, the image goes through the following conversions: 1. The target area is 100×100 (crop=100,100). The tool selects the target area in the picture.
Crop a section of an original image from a specific location
2. The tool drags the target area to the right until 50% of the unwanted width remains on the left (offset-x50). Accordingly, 50% of the unwanted area remains on the right.
Crop a section of an original image from a specific location
3. It moves the target area down until 81% of the unwanted height remains on the top (offset-y81). Accordingly, 19% of the unwanted height remains at the bottom.
Crop a section of an original image from a specific location
4. The tool cuts out the target area. The cropped image looks as follows:
Crop a section of an original image from a specific location

​
Specify a location using one offset measured in pixels and one coordinate measured as a percentage of the original image

The previous options can be combined to crop an original image from a specific place — set the horizontal coordinate in pixels and the percentage of unwanted vertical area, or vice versa. Examples of combined query parameters:
  • ?crop=width,height,x(x-axis value),offset-y(percentage of unwanted area to be cropped from the top)
  • ?crop=width,height,offset-x(percentage of unwanted area to be cropped from the left),y(y-axis value)
  • ?crop=width,height,x(percentage of original image width from the left),offset-y(percentage of unwanted area to be cropped from the top)
The cropping behavior for combined parameters follows the same rules as the individual options above.

​
Check HTTP headers

Check the HTTP response headers to verify that the crop was applied. The X-Img-Operations header lists all conversions performed. If the value includes crop, the image has been cropped.
Check HTTP headers
If X-Img-Operations does not include crop and the CDN returns the original uncropped image, check the img-skip-reason header. This explains why the conversion failed.
Check HTTP headers