Can I crop images by custom shapes?

You can use your own custom image as a mask for cropping by adding an overlay and using the 'cutter' transformation flag.

Using the API (in Ruby): :overlay => "my_shape", :flags => "cutter".
In URLs: l_my_shape,fl_cutter.

For example, the following PNG image was uploaded to Cloudinary with the 'hexagon_sample' public ID.

Now you can use this image with the cutter flag. For example, applying on an image with the 'sample' public ID:,h_200,c_fill/l_hexagon_sample,fl_cutter/sample.png

You can also add the relative flag to automatically adjust the dimensions of the mask to match the resulting image you need. For example:,fl_cutter.relative,w_1.0,h_1.0/sample.png

The mask image can be a semi-transparent PNG file to make the edges more smooth.

Here's such an uploaded mask:

And here's a sample result while creating a 200x220 face detection based thumbnail of an uploaded images:,h_220,c_thumb,g_face/l_hexagon_feather_sample,fl_cutter/face_left.png


Have more questions? Submit a request


  • Avatar
    Daniel Hinchliff

    Following this example I get hexagonal image with a white background instead of a transparent one. I have uploaded the same image you provide here as a mask.

  • Avatar
    Roee Ben-Ari

    Hi Daniel, can you please share a URL example which demonstrates the issue? if you rather keep it private, please feel free to open a support ticket with all the necessary information.

    Edited by Roee Ben-Ari
Powered by Zendesk