Facial Detection

Filestack offers an accurate and versatile facial detection feature. The below will illustrate how to use the function to detect faces and crop pictures automatically based on the face detection information.


The feature is divided into four endpoints, one for detection, one for cropping and two filters. We will discuss the detection first.

Task Quick Jump:

Detect Faces Crop Faces Pixelate Faces Blur Faces


Facial Detection URL Format:
https://process.filestackapi.com/detect_faces=[options]/Filestack_FileLink_Handle
or
https://process.filestackapi.com/<API_KEY>/detect_faces=[options]/File_URL

detect_faces
String

The root task cannot be abbreviated

Users can use detect_faces without any options and the default settings will be used.
detect_faces=minSize:N
Integer or Float

Can be abbreviated as n:.35

This parameter is used to weed out objects that most likely are not faces. This can be an integer or a float in a range from 0.01 to 10000. The default value is 0.35. If the value set is larger than 1, it is used as the expected minimum size of face objects in pixels. So for example if the value is set to 200, then the smallest face object it will detect is 200x200 pixels. If the value that is set is less than 1, i.e. 0.3, then it filters out all face objects it detects that are smaller than the middle/average object size by 30%. This means that if a set of 3 objects are detected that are (size in pixels) ['100x100', '200x200', '300x300'], then setting minsize to 0.3 will result in a calculation where the middle object size 200 is used: 200-0.30*200=140 and all objects smaller than 140x140 would be eliminated.
detect_faces=maxsize:N
Integer or Float

Can be abbreviated as x:.35

This parameter is used to weed out objects that most likely are not faces. This can be an integer or a float in a range from 0.01 to 10000. The default value is 0.35. If the value set is larger than 1, it is used as the expected maximum size of face objects in pixels. So for example if the value is set to 200, then the largest face object it will detect is 200x200 pixels. If the value that is set is less than 1, i.e. 0.3, then it filters out all face objects it detects that are larger than the middle/average object size by 30%. This means that if a set of 3 objects are detected that are (size in pixels) ['100x100', '200x200', '300x300'], then setting maxsize to 0.3 will result in a calculation where the middle object size 200 is used: 200+0.30*200=260 and all objects larger than 260x260 would be eliminated.
detect_faces=color:white or FFFFFFFF
Integer or Float

Can be abbreviated as c:white or FFFFFFFF

Will change the color of the "face object" boxes and text. This can be the word for a color, or the hex color code. Click here for a list of accepted colors.
detect_faces=export:true
Boolean

Can be abbreviated as e:true

Will export all face objects to a JSON object.

Detect Faces Examples

Original image

the original photo to be used in the face detection examples

Faces Detected using Default Settings

example of face detection using default parameters on the original photo

Changing the Color of "Face Object" boxes

illustration of how to change the color of the face detection boxes

The image below shows the "face objects" that appear when we set the value of maxsize to 140, reducing the number of "face objects" detected.

The default value for the maxsize parameter is .35, but once the maxsize becomes greater than 1, the calculation changes. The largest face this example will now detect is 140x140 pixels which limits the number of faces detected in this image.

example of how to use the maxsize parameter to control the amount of faces that get detected

The following example shows the data you receive when you export detected faces to a JSON payload:

[{"x":642,"y":298,"width":137,"height":137,"id":1},
{"x":446,"y":731,"width":138,"height":138,"id":2},
{"x":953,"y":673,"width":147,"height":147,"id":3},
{"x":1254,"y":371,"width":135,"height":135,"id":4},
{"x":1425,"y":692,"width":145,"height":145,"id":5}]

Crop Faces

Crop Faces URL Format:
https://process.filestackapi.com/crop_faces=[options]/Filestack_FileLink_Handle
or
https://process.filestackapi.com/<API_KEY>/crop_faces=[options]/File_URL
crop_faces=mode:thumb, crop or fill
String

Can be abbreviated as m:thumb

mode:thumb Adds a buffer around the face object by default. Part of the image inside the buffer is always resized to the desired dimensions (w & h parameters).
mode:crop Ignores the buffer around the face object.
mode:fill Works in a similar manner to thumb mode, except that while thumb mode will always crop an image to fit in the whole face object while still trying to respect width and height transformations, fill mode will prioritze width and height parameters over displaying the whole face object.
crop_faces=width:100
Integer

Can be abbreviated as w:100

Specify the width of the crop in pixels.
crop_faces=height:100
Integer

Can be abbreviated as h:100

Specify the height of the crop in pixels.
crop_faces=faces:1, [1,2,3,4], or all
Integer, Array, or String

Can be abbreviated as f:1

The faces parameter can be a single face object, an array of face objects, or you can use 'all' to choose all the detected face objects. This parameter governs the faces you want included in your crop.
crop_faces=buffer:200
Integer

Can be abbreviated as b:1

Adjusts the buffer around the face object as a percentage of the original object.

Crop Faces Examples

When used by itself, mode:thumb will crop to the face with id=1 by default. It also uses a default buffer size of 135% of the original object size.

original image cropped to the first face detected

Selecting a single face using the Crop Faces Parameter. The following request will crop the 5th identified face object using the default buffer for thumbnails.

original photo automatically cropped to the fifth face detected in the image

Selecting multiple identified face objects and cropping to fit them all in one image with the default buffer.

image automatically cropped to include multiple detected face objects

Selecting all identified face objects and cropping to fit them all in one image with the default buffer.

original image automatically cropped to include all detected face images using thumb mode

Adjusting the buffer around the face object (as a percentage of the original object). Here we choose 200% of the original object.

original image automatically cropped to the first identified face when the buffer size has been increased to 200%

Adjusting the buffer around the face object (as a percentage of the original object). Here we choose 50% of the original object.

original image automatically cropped to the first face detected using a buffer size of 50%

Understanding the difference between mode:thumb, mode:crop, and mode:fill

This is what the default for mode:thumb looks like:

original image automatically cropped to the first face using default settings in thumb mode

Now this is what it looks like when you use the default parameters with mode:crop:

original image automatically cropped to the first face using default settings in crop mode

And this is what it looks like when you use the default parameters with mode:fill

Identical to mode:thumb when used with default parameters:

original image automatically cropped to the first face using default settings in fill mode

Resizing the image to 100x100 with a buffer of 200 and the mode:thumb parameter

mode:fill will produce identical results when used with these parameters and this image:

cropping the image to the first face object detected with a set width and height of 100x100 using thumb mode

Resizing the image to 100x100 with a buffer of 200 and the mode:crop parameter:

cropping the image to the first face object detected with a set width and height of 100x100 using crop mode

Resizing the image to 800x800 with a buffer of 200 and the mode:thumb parameter

mode:fill will produce identical results when used with these parameters and this image:

cropping the image to the first face object detected with a set width and height of 800x800 using thumb mode

Resizing the image to 800x800 with a buffer of 200 and the mode:crop parameter:

cropping the image to the first face object detected with a set width and height of 800x800 using crop mode

Resizing the image to 200x400 with the mode:thumb parameter

mode:fill will produce identical results when used with these parameters and this image:

cropping the image to the first face object detected with a set width and height of 200x400 using thumb mode

Resizing the image to 200x400 with the mode:crop parameter:

cropping the image to the first face object detected with a set width and height of 200x400 using crop mode

Resizing the image to 400x200 with the mode:thumb parameter

mode:fill will produce identical results when used with these parameters:

cropping the image to the first face object detected with a set width and height of 400x200 using thumb mode

Resizing the image to 400x200 with the mode:crop parameter:

cropping the image to the first face object detected with a set width and height of 400x200 using crop mode

Resizing the image to 400x200 with a buffer of 300 and the mode:thumb parameter:

cropping the image to the first face object detected with a set width and height of 400x200 using thumb mode and a buffer of 300%

Resizing the image to 400x200 with a buffer of 300 and the mode:crop parameter (note that the buffer is ignored):

cropping the image to the first face object detected with a set width and height of 400x200 using crop mode and a buffer of 300%

Resizing the image to 400x200 with an array of face objects and the mode:thumb parameter

mode:fill will produce identical results when used with these parameters and this image:

cropping the image to the first three face objects detected with a set height and width of 400x200 using thumb mode

Resizing the image to 400x200 with an array of face objects and the mode:crop parameter

Note that crop mode does not make sure that the face objects are visible, it crops to the center of the image inbetween the space where the 3 face objects specified appear:

cropping the image to the first three face objects detected with a set height and width of 400x200 using crop mode

For reference, here is the same function without the width and height parameters

cropping the image to the first three face objects detected using crop mode

Resizing the image to 3200x100 with the mode:thumb parameter.

In this case thumb mode will resize the image to fit the whole face object in 100 pixels of vertical space. This creates an image that is 1081x100, without distoring the contents of the image:

cropping the image to the first face object detected with a set height and width of 3200x100 using thumb mode

Resizing the image to 3200x100 with the mode:crop parameter

In this case crop mode will produce an image that is 2000x100 (the original width of the image) and crop off part of the face object to fit the 100 pixel width:

cropping the image to the first face object detected with a set height and width of 3200x100 using crop mode

Resizing the image to 3200x100 with the mode:fill parameter

In this case, fill will resize the image so that it has a width of 3200 pixels (instead of the original 3000) and cut off part of the face object to fit the 100 pixel height restriction. The final image that is produced is 3200x100:

cropping the image to the first face object detected with a set height and width of 3200x100 using fill mode

Pixelate Faces

Pixelate Faces URL Format:
https://process.filestackapi.com/pixelate_faces=[options]/Filestack_FileLink_Handle
or
https://process.filestackapi.com/<API_KEY>/pixelate_faces=[options]/File_URL
pixelate_faces=faces:1, [1,2,3,4], or all
Integer, Array, or String

Can be abbreviated as f:all

The faces parameter can be a single face object, an array of face objects, or you can use 'all' to choose all the detected face objects. This parameter governs the faces you want pixelated.
pixelate_faces=faces:1, [1,2,3,4], or all
Integer, Array, or String

Can be abbreviated as f:all

The faces parameter can be a single face object, an array of face objects, or you can use 'all' to choose all the detected face objects. This parameter governs the faces you want pixelated.
pixelate_faces=minSize:N
Integer or Float

Can be abbreviated as n:.35

Defaults to 0.35. This parameter is used to weed out objects that most likely are not faces. This can be an integer or a float in a range from 0.01 to 10000. If the value set is larger than 1, it is used as the expected minimum size of face objects in pixels. So for example if the value is set to 200, then the smallest face object it will detect is 200x200 pixels. If the value that is set is less than 1, i.e. 0.3, then it filters out all face objects it detects that are smaller than the middle/average object size by 30%. This means that if a set of 3 objects are detected that are (size in pixels) ['100x100', '200x200', '300x300'], then setting minsize to 0.3 will result in a calculation where the middle object size 200 is used: 200-0.30*200=140 and all objects smaller than 140x140 would be eliminated.
pixelate_faces=maxsize:N
Integer or Float

Can be abbreviated as x:.35

Defaults to 0.35. This parameter is used to weed out objects that most likely are not faces. This can be an integer or a float in a range from 0.01 to 10000. If the value set is larger than 1, it is used as the expected maximum size of face objects in pixels. So for example if the value is set to 200, then the largest face object it will detect is 200x200 pixels. If the value that is set is less than 1, i.e. 0.3, then it filters out all face objects it detects that are larger than the middle/average object size by 30%. This means that if a set of 3 objects are detected that are (size in pixels) ['100x100', '200x200', '300x300'], then setting maxsize to 0.3 will result in a calculation where the middle object size 200 is used: 200+0.30*200=260 and all objects larger than 260x260 would be eliminated.
pixelate_faces=buffer:200
Integer or Float

Can be abbreviated as b:200

Adjusts the buffer around the face object as a percentage of the original object. Must be an integer in a range from 0 to 1000. There is no default value.
pixelate_faces=amount:5
Integer

Can be abbreviated as a:10

The amount of pixelation to apply to the selected faces. The value for this parameter can be any integer in a range from 2 to 100. The default value for this parameter is 10.
pixelate_faces=blur:10
Float

Can be abbreviated as l:4.0

The amount to blur the pixelated faces. The value for this parameter can be any float in a range from 0 to 20. The default value for this parameter is 4.0.
pixelate_faces=type:rect
String

Can be abbreviated as t:rect

The shape of the pixelated faces. The value for this parameter is a string. The options are rect (for a rectangle shape) or oval (for and oval shape). The default value for this parameter is rect.

Pixelate Faces Examples

Pixelating all faces with oval pixelation areas pixelate_faces=faces:all,amount:10,type:oval,buffer:120,blur:14

original image with all detected faces pixelated with oval pixelation areas

Selecting an array of faces to pixelate with rectangular pixelation areas. pixelate_faces=faces:[1,3,5],amount:10,type:rect,buffer:120,blur:14

original image with an array of detected faces pixelated using rectangular pixelation areas

Blur Faces

Blur Faces URL Format:
https://process.filestackapi.com/blur_faces=[options]/Filestack_FileLink_Handle
or
https://process.filestackapi.com/<API_KEY>/blur_faces=[options]/File_URL
blur_faces=faces:1, [1,2,3,4], or all
Integer, Array, or String

Can be abbreviated as f:[1,2,3,4]

The faces parameter can be a single face object, an array of face objects, or you can use 'all' to choose all the detected face objects. This parameter governs the faces you want blurred.
blur_faces=minSize:N
Integer or Float

Can be abbreviated as n:.35

Defaults to 0.35. This parameter is used to weed out objects that most likely are not faces. This can be an integer or a float in a range from 0.01 to 10000. If the value set is larger than 1, it is used as the expected minimum size of face objects in pixels. So for example if the value is set to 200, then the smallest face object it will detect is 200x200 pixels. If the value that is set is less than 1, i.e. 0.3, then it filters out all face objects it detects that are smaller than the middle/average object size by 30%. This means that if a set of 3 objects are detected that are (size in pixels) ['100x100', '200x200', '300x300'], then setting minsize to 0.3 will result in a calculation where the middle object size 200 is used: 200-0.30*200=140 and all objects smaller than 140x140 would be eliminated.
blur_faces=maxSize:N
Integer or Float

Can be abbreviated as x:.35

Defaults to 0.35. This parameter is used to weed out objects that most likely are not faces. This can be an integer or a float in a range from 0.01 to 10000. If the value set is larger than 1, it is used as the expected maximum size of face objects in pixels. So for example if the value is set to 200, then the largest face object it will detect is 200x200 pixels. If the value that is set is less than 1, i.e. 0.3, then it filters out all face objects it detects that are larger than the middle/average object size by 30%. This means that if a set of 3 objects are detected that are (size in pixels) ['100x100', '200x200', '300x300'], then setting maxsize to 0.3 will result in a calculation where the middle object size 200 is used: 200+0.30*200=260 and all objects larger than 260x260 would be eliminated.
blur_faces=buffer:200
Integer

Can be abbreviated as b:200

Adjusts the buffer around the face object as a percentage of the original object. Must be an integer in a range from 0 to 1000. There is no default value.
blur_faces=amount:5
Float

Can be abbreviated as a:4.0

The amount of blur to apply to the selected faces. The value for this parameter can be any float in a range from 0 to 20. The default value for this parameter is 4.0.
blur_faces=blur:5.5
Float

Can be abbreviated as l:4.0

The amount to blur the obscured faces. The value for this parameter can be any float in a range from 0 to 20. The default value for this parameter is 4.0.
blur_faces=type:rect
String

Can be abbreviated as t:rect

The shape of the blur on the faces. The value for this parameter is a string. The options are rect (for a rectangle shape) or oval (for and oval shape). The default value for this parameter is rect.

Blur Faces Examples

Blurring all faces with oval blur areas blur_faces=faces:all,amount:10,type:oval,buffer:120,blur:14

original image with all faces blurred using oval blurring areas

Selecting an array of faces to blur with rectangular blurring areas. blur_faces=faces:[1,3,5],amount:10,type:rect,buffer:120,blur:14

original image with an array of detected faces blurred using rectangular blurring areas