Face-detection based transformations

Uploadcare allows you to use face recognition algorithms to make transformations based on detected faces in an image.

In the most popular use cases, such as creating user pics, blurring faces and cropping based on detected faces, and overlaying text or special things on specified facial attributes, face-based transformations are used in combination with other image processing operations.

List of face-detection based processing operations

Face-detection based cropping

Cropping by faces

Crops the image to the object specified by the :tag parameter with :face value — the largest detected face in the image is used as a crop basis.

There are several ways to crop a file:

Crop by face
Crop to square
Crop by face with space

Keeping proportions

If you want to keep the proportions but fill the entire tile, use -/smart_resize/ to generate missing parts of the picture.

Smart resize

Create a user's pic

If you want to create a circular user profile photo, combine the operations -/crop/face/ and -/border_radius/.

Smart resize

You can also create a circular user photo, combine the operations -/scale_crop/ and -/border_radius/.

Scale crop

Filling an empty area

If you have an empty space when creating a user's pic, you can fill it using the -/setfill/:color/ operation.

You can find out the required fill color with the -/main_colors/ operation or through other external apps.

Original image
Crop image
Crop image
Fill empty area
Fill empty area

Blur faces

If you need to blur faces in photos to comply with privacy laws, apply a blur effect to automatically detect faces in the image using the -/blur_region/faces/ operation.

You can adjust the strength of the blur effect. It determines with an optional additional strength value, ranging to 5000 (default: 10).

For example, -/blur_region/faces/100/ uses a small blur effect with a strength of 100:

Small blur effect with a strength=100

You can "bake in" the applied changes and create a new file that can no longer be reverted to its original state.

Coordinates of facial landmarks


The detect_faces operation returns the coordinates of faces found in an input image. The output is similar to the json operation. The output is a JSON with the additional list of faces that holds the coordinates of faces that were detected.

Data for each of the found faces are put into separate lists that look like this:

[x, y, x_size, y_size]

Further, lists within faces contain:

  • x, y — coordinates of the upper-left corner of an area where a face was found.
  • x_size, y_size — dimensions of that area.

Note, detect_faces is not divided from a file UUID by the /-/ separator. Hence, it can not be piped to other operations.

Run a face-check for the following image on our CDN:

Compound image with three faces

Put detect_faces into the image URL, separating it with the forward slash / from the UUID:


Get the following faces list in the response JSON:

"faces": [
  [45, 142, 207, 207],
  [460, 113, 238, 238],
  [892, 43, 265, 265]

detect_faces uses an algorithm that better detects the fronts of faces rather than facial profiles. Also, covering important face features with different objects leads to a decline in detection accuracy.

Technically, the operation detects faces using Haar Cascades. That approach deals with machine learning processes that rely on classifiers holding cascades of features specific to faces, eyes, etc.

Position overlays avoiding detected faces

You can combine text overlay and -/detect_faces/ operations to add text to an image while avoiding text overlapping with faces.

Overlaying text without affecting the face

Overlaying text without affecting the face