Last updated May 18, 2020

    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
    Fail-safe cropping

    Appending the fail-safe mode parameter safe to the crop API ensures an output image will never return an error due to the specified crop region being out of bounds. When appended, the image gets delivered as an intersection of the origin image and the specified crop region. This avoids the error entirely, but the image may not match the specified dimensions.


    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.
    width-ratio float The width ratio of the image.
    height-ratio float The height ratio 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 none Content-aware image cropping.
    safe none Fail-safe crop mode.


    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
    Fail-safe Crop - Fail-safe crop the image to 3000x600 and select the starting sub region x coordinate to be 100px and the y sub region to be 100px. <img src="image.jpg??crop=3000,600,x100,x100,safe"/> 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
    Back to Top