Face Detection

Detects faces in an image.

The Face Detection API analyzes an image to find faces. It returns the position of the left and top edges of a bounding box that contains the face, and the width and height of the bounding box.

For a list of file formats that you can use for images, see Supported Media Formats.

Quick Start

The following example request analyzes the image in the specified file for faces.

curl -X POST http://api.havenondemand.com/1/api/[sync|async]/detectfaces/v1 --form "file=@family.jpg"

The API response contains the position of the left and top edges of a bounding box that contains the face, and the width and height of the bounding box:

{
  "face": [
    {
      "left": 266,
      "top": 196,
      "width": 60,
      "height": 67
    },
    {
      "left": 147,
      "top": 283,
      "width": 102,
      "height": 112
    },
    {
      "left": 126,
      "top": 126,
      "width": 82,
      "height": 74
    },
    {
      "left": 373,
      "top": 259,
      "width": 60,
      "height": 67
    }
  ]
}

For all image formats except PDF, the coordinate values are in pixels and the edge positions are defined from the upper left corner of the image. For images in PDF format, the values are given in points (1/72 of an inch).

Optimize Results

The quality of the images that you send to the Detect Faces API can have a significant effect on the quality of the API output. For example, face detection works best when:

Additional Metadata

You can set the additional parameter to true if you want Haven OnDemand to estimate age information for the detected faces in the picture.

curl -X POST http://api.havenondemand.com/1/api/[sync|async]/detectfaces/v1 --form "file=@family.jpg" --form "additional=true"

{
  "face": [
    {
      "left": 266,
      "top": 196,
      "width": 60,
      "height": 67,
      "additional_information": {
        "age": "adult"
      }
    },

The age response returns one of the following values:

  • child
  • youth
  • adult
  • elderly
Synchronous
https://api.havenondemand.com/1/api/sync/detectfaces/v1
Asynchronous
https://api.havenondemand.com/1/api/async/detectfaces/v1
Authentication

This API requires an authentication token to be supplied in the following parameter:

Parameter Description
apikey The API key to use to authenticate the API request.
Parameters

This API accepts the following parameters:

Required
Name Type Description
file
binary The image file to process.
reference
string A Haven OnDemand reference obtained from either the Expand Container or Store Object API. The corresponding document is passed to the API.
url
string A publicly accessible HTTP URL from which the image can be retrieved.
Optional
Name Type Description
additional
boolean Whether to estimate the ages of the faces. Default value: false.
face_orientation
enum Information about the face orientation in the images that you are submitting. Default value: upright.
Enumeration Types

This API's parameters use the enumerations described below:

face_orientation
Information about the face orientation in the images that you are submitting.
upright Upright
The faces in the image are always upright.
any Any
The faces in the image may be rotated (horizontal or upside down).

This API returns a JSON response that is described by the model below. This single model is presented both as an easy to read abstract definition and as the formal JSON schema.

Asynchronous Use

Additional requests are required to get the result if this API is invoked asynchronously.

You can use /1/job/status/<job-id> to get the status of the job, including results if the job is finished.

You can also use /1/job/result/<job-id>, which waits until the job has finished and then returns the result.

Model
This is an abstract definition of the response that describes each of the properties that might be returned.
Face Detection Response {
face ( array[Face] ) The details of a detected face.
page_count ( integer , optional) The total number of pages in the document.
}
Face Detection Response:Face {
additional_information ( Additional_information , optional)
height ( integer ) The height of the bounding box for the face (or points for PDF images).
left ( integer ) The position of the left edge of the bounding box for the face, in pixels from the left edge of the image (for PDF images, position is in points).
top ( integer ) The position of the top edge of the bounding box for the face, in pixels from the top edge of the image (for PDF images, position is in points).
width ( integer ) The width of the bounding box for the face, in pixels (or points for PDF images).
page_num ( integer , optional) The page in the document that the face belongs to.
}
Face Detection Response:Face:Additional_information {
age ( string , optional) The age range of the face
}
Model Schema
This is a JSON schema that describes the syntax of the response. See json-schema.org for a complete reference.
{
    "properties": {
        "face": {
            "items": {
                "properties": {
                    "additional_information": {
                        "properties": {
                            "age": {
                                "enum": [
                                    "child",
                                    "youth",
                                    "adult",
                                    "elderly"
                                ],
                                "type": "string"
                            }
                        },
                        "type": "object"
                    },
                    "height": {
                        "type": "integer"
                    },
                    "left": {
                        "type": "integer"
                    },
                    "top": {
                        "type": "integer"
                    },
                    "width": {
                        "type": "integer"
                    },
                    "page_num": {
                        "type": "integer"
                    }
                },
                "required": [
                    "left",
                    "top",
                    "width",
                    "height"
                ],
                "type": "object"
            },
            "type": "array"
        },
        "page_count": {
            "type": "integer"
        }
    },
    "required": [
        "face"
    ],
    "type": "object"
}
https://api.havenondemand.com/1/api/sync/detectfaces/v1
/api/api-example/1/api/sync/detectfaces/v1
Examples
See this API for yourself - select one of our examples below.
Greyscale
Single Face
Four Faces
Parameters
Required
Select file Change Remove
Optional
Name Type Value
additional
boolean
(Default: False)
face_orientation
enum


ASync – Response An error occurred making the API request
Response Code:
Response Body

	
Making API Request…
Checking result of job

To try this API with your own data and use it in your own applications, you need an API Key. You can create an API Key from your account page - API Keys.

Output Refresh An error occurred making the API request View Input
Rendered RawHtml Response
Result Display
Response Code:
Response Body:

			
Make this call with curl


If you would like to provide us with more information then please use the box below:

We will use your submission to help improve our product.