Why isn't the face detected when using the 'face' gravity?

Cloudinary provides smart image cropping based on face detection algorithms. You can automatically get a cropped version of an uploaded image or a Facebook profile picture, while centering on a single or multiple faces.

For example, here's the original image:

And here's a 100x100 cropped thumbnail centered on the person's face:

Unfortunately automatic face detection algorithms do not guarantee 100% accuracy. However, you can update the face's coordinates by yourself.

Cloudinary now supports a new parameter which you can pass either while uploading or even for already uploaded images. For such cases you can tell Cloudinary where the face is placed within an image. 
The new parameter is the face_coordinates parameter. The coordinates is an array of x,y,width.height. Then the cropping, using face gravity, uses these custom coordinates instead of auto face detection.

For example, here's the original image:

This is an example where the automatic face detection do not work:

You can use the explicit API to tell Cloudinary where the face is placed exactly in the image (in Ruby):

Cloudinary::Uploader.explicit("face_smile", :type => 'upload', :face_coordinates => [[108,3,152,163]])

Or you can pass the coordinates while uploading, for example:

Cloudinary::Uploader.upload("image.jpg", :face_coordinates => [[108,3,152,163]])

In the following example, we re-uploaded the image while setting the face_coordinates parameter. Now we can use the same transformation (including the 'face' gravity), but this time Cloudinary will return the following result:

The face_coordinates parameter is also supported for multiple faces, as referenced here:


You can now add/remove faces' coordinates interactively via the Media library too.
Simply click on the image you'd like to edit, then click on the 'Edit crop coordinates' button:


Then, you'll be able to add/delete/clear the faces coordinates.


Have more questions? Submit a request


  • Avatar
    Farmers Setup

    When I update the face coordinates through the web tool, it seems that previous transformations keep the old coordinates. There are no derived resources listed that I can delete, and changing the version number does not help.

    Is this simply due to cache issues or is there something else I can do?

  • Avatar
    Roee Ben-Ari

    Can you please send us the URL which wasn't properly invalidated? If privacy is an issue, please open a support ticket and share your details. We'll be happy to assist.

Powered by Zendesk