Face detection crop

On this page

Automatically detect faces in your image and crop them. Sirv uses deep learning neural networks, trained on millions of images to accurately detect faces in images. Faces can be detected in as little as 200ms.

How to use face detection

Use the crop.type parameter to initiate face detection on an image. Specify face as the type of crop you want to apply, like so:


Original image, not cropped Face detection cropped image

To scale down the size of the face, use ch and/or cw:


Face detected image, scaled to 150px

Crop to uniform size

To create a paricular aspect ratio for images, add crop.aspectratio=1:1. The ratio is width:height, so 1:1 will make a square image. Use any value to choose another e.g. 16:9.


To scale the image to a particular width or height, use crop.scale.width and/or crop.scale.height:


All these images have crop.aspectratio=1:1 and crop.scale.height=180:

AI image face detection, cropped square to 180px AI image face detection, cropped square to 180px AI image face detection, cropped square to 180px AI image face detection, cropped square to 180px

Face identification

To see which faces Sirv detected, add crop.dev=1 to the URL. A red box will be drawn around the face:


AI image face detection with confidence value

Face confidence

Sirv's AI algorithm provides a level of confidence for each face detected. Values range from 0.00 to 1.00, where 1.00 is complete confidence. By default, face crop will initiate if confidence is at least 0.50. This can be adjusted by setting crop.confidence.

The following example has confidence of 0.36 so face crop won't initiate by default:

AI face detection image with 30% confidence value

By lowering the crop.confidence to 0.3, the face will be cropped:


Face detected on image with confidence value at least 30%

Multiple faces

If an image contains more than one face, the face with the highest confidence level will be shown first i.e. the face which the AI algorithm deems most likely a human face. This image has 2 faces with confidence of 1.00 and one incorrectly identified face with confidence of 0.83:

AI face detection on image with multiple people

To specify a particular face to crop, use crop.face. Face numbering starts from 0. When multiple faces have the same confidence level, the first face identified will be 0.

The following URLs will show the first 2 faces:


First face detected
Second face detected

Face coordinates

You can check how many faces were detected and what their coordinates are.

Face detection is triggered the first time crop.type=face is used, so to ensure that you receive face meta data, make a request e.g.


Then you can request JSON meta data by appending ?info in the image URL e.g.


You will see a "faces" section in the JSON response:

  "faces": {
        "_fileversion": 0,
        "_version": 1,
        "faces": [

The example above shows that 3 faces were detected. Each face has 5 numbers - the first 4 are coordinates for the corners of the box around the face and the 5th is the confidence score, where 0.00 is zero confidence and 1.00 is total confidence.

Was this article helpful?

Get help from a Sirv expert

help ukraine help ukraine Powered by Ukrainian determination and British ingenuity

How can you support Ukraine