Face detection crop

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:

https://demo.sirv.com/lady.jpg?crop.type=face

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

https://demo.sirv.com/lady.jpg?crop.type=face&ch=150

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.

https://demo.sirv.com/lady.jpg?crop.type=face&crop.aspectratio=1:1

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

https://demo.sirv.com/lady.jpg?crop.type=face&crop.aspectratio=1:1&crop.scale.width=350

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

Face identification

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

https://demo.sirv.com/lady.jpg?crop.type=face&crop.dev=1

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:

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

https://demo.sirv.com/waiting.jpg?crop.type=face&crop.confidence=0.3

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:

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:

https://demo.sirv.com/dance.jpg?crop.type=face&crop.face=0
https://demo.sirv.com/dance.jpg?crop.type=face&crop.face=1

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.

https://demo.sirv.com/lady.jpg?crop.type=face

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

https://demo.sirv.com/lady.jpg?info

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

  "faces": {
        "_fileversion": 0,
        "_version": 1,
        "faces": [
          [
            0.2400001585483551,
            0.20457066595554352,
            0.3113246262073517,
            0.32810765504837036
            0.9958600401878357
          ],
          [
            0.4909583628177643,
            0.18004164099693298,
            0.5581685900688171,
            0.2961938679218292,
            0.9856602967173639
          ],
          [
            0.7377604842185974,
            0.17373570799827576,
            0.803407609462738,
            0.2935556173324585,
            0.9716298648296017
          ]
        ]

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.