The crop parameter removes pixels from an image. When specifying a crop, the values always start with width followed by height (for example, crop=4:3 or crop=640,480 or crop=0.8,0.4). When cropping a region of interest from an image (a.k.a., "art direction"), the x and y parameters determine the position of the sub-region of the source image, whereas the offset-x and offset-y parameters move the horizontal or vertical offset of the crop. When specifying smart cropping, content-aware algorithms attempt to crop an image to a fixed aspect ratio while intelligently focusing on the most important visual content, including the detection of faces.


API Pattern

Aspect Ratio Crop
Smart cropping


Parameter Description
crop Remove pixels from an image.

Parameter Values

Value Units Description
width Pixels or Percentage The width of the image.
height Pixels or Percentage The height of the image.
x{value} Pixels or Percentage The x coordinate sub-region of the source image.
y{value} Pixels or Percentage The y coordinate sub-region of the source image.
offset-x{value} Percentage The horizontal offset of the source image.
offset-y{value} Percentage The vertical offset of the source image.
smart   Content-aware image cropping.


  1. The x and y or offset-x and offset-y parameters are optional.
  2. The optional x and y or offset-x and offset-y parameters can be supplied in any order after the width and height.
  3. If no x, y or offset-x,offset-y parameters are supplied the image is cropped form the center point.
  4. The x parameter can be supplied without y and visa versa.
  5. The offset-x parameter can be supplied without offset-y and visa versa.
  6. When using aspect ratio cropping, the crop parameter must be used in conjunction with a width or height parameter (or both) in order to return the correct output image size. If no width or height are supplied the largest area of the requested aspect ratio will be returned based on the dimensions of the source image.
  7. Pixel rounding is performed on all calculations in a decimal format (with as much accuracy as possible). The final value is then rounded down.


Description HTML Demo
Crop - Crop the image to 150px by 100px. <img src="image.jpg?crop=150,100"/> Example
Aspect Ratio Crop - Crop the image to an aspect ratio of 16:9. <img src="image.jpg?crop=16:9"/> Example
Crop Sub Region - Crop the image to 150px by 100px and select the starting sub region x coordinate to be 50px and the y sub region to be 50px. <img src="image.jpg?crop=150,100,x50,y50"/> Example
Aspect Ratio Crop & Offset - Crop the image square and offset the x-axis 25% and the y-axis 50% <img src="image.jpg?crop=1:1,offset-x0.25,offset-y0.50"/> Example
Advanced Examples (Combining Additional Parameters)
Description HTML Additional Param Demo
Aspect ratio crop (with width) - Crop the image square and resize the width to 200px. <img src="image.jpg?crop=1:1&width=200"/> width Example
Smart cropping - Trim 30% of the image, resize the width to 200px and crop the image square using content-aware image cropping. <img src="mountaineer.jpg?trim=0.30&width=200&crop=1:1,smart"/> width, trim Example