Facial Recognition Made Easy with Filestack

Facial Recognition is a common feature for sites with social computing features.  There are several examples of facial recognition that you encounter every day:

  • Allowing end users to tag people based on faces in pictures
  • Extracting a thumbnail of a face to be used as a profile picture
  • Preventing faces from being visible in any images uploaded to a site.

The Filestack API allows you to quickly and programmatically detect faces in an image.  You may highlight the faces, crop the photo to show only the area immediately around a person’s face, or obscure detected faces through pixelation or blurring.  All these actions can be done through simple URLs and using JSON data returned by the API.

Want to talk?

Get in contact now

Detecting Faces

Given a URL to a photo (or an identifier to a photo you’ve already uploaded with Filestack), you can invoke Filestack’s facial recognition feature using the “detect_faces” function.  By default, this will return an image with all the faces that are detected overlaid with a black box with a number in the center.   The number corresponds to the order in which the face was found when scanning from top to bottom and left to right.  This number can be used to manipulate a specific face that was detected using other Filestack API operations described below.  The color of the box and number can be modified using hexadecimal color codes or recognized color words.

The original image to the left is transformed to the second image on the right with the following URL:

An example of facial recognition
The original photo and the output of the “detect_faces” function


More importantly, you can get the number of detected faces and even their actual pixel coordinates as a series of JSON objects.  These coordinates will include x and y values as well as the width and height of the detected faces within the image (think of your image as a grid with x and y values set to 0 in the top left most pixel of the image).

The following URL:


Produces this JSON data for our sample image:

An example of JSON data produced using Filestack's Facial Recognition
example JSON data produced using Filestack’s Facial Recognition

These coordinates would themselves be enough to further manipulate the image, but Filestack provides a variety of utility methods to simplify common operations.

Cropping Faces with Facial Recognition

As part of its overall set of image transformation features, Filestack provides functionality for cropping images using pixel based coordinates and dimensions.  However, for facial detection in particular, some convenience features have been added to simplify the task.  These features eliminate many of the calculations and much of the guesswork that would otherwise go into trying to create portraits from these images.

You can create a thumbnail by invoking the “crop_faces” method and specifying a face based on its place in the list of faces returned when you invoked “detect_faces” (i.e. face 1, face 2). You can even specify more than one face to include multiple faces in the same cropped out thumbnail.

The following URLs create the images below from the original image at the top of this article.

1st Face Found:


Face “5”:


Faces “1,””2,” and “3,”:



An example of facial recognition by Filestack
Individually cropped out faces versus multiple faces


Note that no identifier is specified for the URL of the first image —  a thumbnail is simply created from the first face detected.  The second image shown is specified as the 5th face (faces:5), while the third image is specified as an array of the first three detected faces (faces:[1,2,3]).

If necessary, you can adjust the size of buffer around the face created by the thumbnail to provide more context to the image.  You can also adjust the resulting image to fit a particular set of dimensions and make use of a variety of different modes (thumb, crop and fill) to determine how the resulting image will be sized.

various image sizes using Filestack's Facial Recognition
Variations on how an image may be cropped and resized using the Filestack API


All of the above manipulations can be done simply by creating URLs to the Filestack API.

Pixelating or Blurring Faces

Another case to consider is when you don’t want faces to be shown for reasons of privacy or legal liability.   For that reason, Filestack provides utility functions that will allow you to pixelate or blur all or some of the faces detected in a photo as shown below.

Blurred faces using Filestack's Facial Recognition
To the left, an image with blurred faces. To the right, selectively pixelated faces.


The leftmost image above blurring out all the faces is created with the “blur_faces” function and following URL:


The right image with selectively pixelated faces is created with the “pixelate_faces” function with an array parameter passed to indicate the faces to pixelate (the 1st, 3rd and 5th as faces:[1,3,5]).  The image was created with the following URL:


The amount of pixelation or blur and the size of the region affected by the transformation can all be specified through parameters to pixelate_faces and blur_faces operations.

Next Steps

In summary, any business can utilize Filestack’s Facial Recognition to identify multiple faces in an image. Once the faces are identified, you can easily crop, blur, create thumbnails and do much more with the face in question.

If you’re looking to go further with this feature, we suggest you check these out:

  1. Read our Facial Detection API documentation to go into more depth with this functionality.
  2. Look at workflows to see what other manipulations you can do to the image of a face that you’ve cropped out of a photo.
  3. Use image enhancements such as red eye removal to improve the thumbnails you create.

With Filestack, our goal is to make facial recognition as easy as possible. Reach out to us today to and start a conversation about incorporating facial recognition into your content workflow.

Happy Hacking!

Read More →