Detect faces on images

Purpose

Use this call when you need the faces on an image without any identity decision: where each face is, how it is turned, and optionally features such as age or gender. The call does not store anything.

Request

POST <API_BASE_URL>/face/detect. All calls are POST under your API address. Replace <API_BASE_URL> with the API address provided with your access.

Send a permanent API token in the token field of the body, or a user token in the token header. See authentication.

Content type: multipart/form-data. Send the fields as a multipart form.

Field	Type	Required	Description
`token`	string (uuid)	if no header	Your permanent API token. Required unless you send a user token in the `token` header.
`images`	array of file	yes	The image files to process. An image can contain several faces; see `multi`.
`multi`	boolean	no	Process every face found. When `false`, only the largest face of each image is processed.
`feature_check`	array of object or string	no	A feature name or an array of names to detect on each found face, for example `age`, `gender`, `mood`, `glasses`, `mask` or `quality`. The schema lists the full set of names.
`check_blur`	boolean	no	Also return blur scores for each face.
`thumb`	boolean	no	Return a pre-processed crop of each face, base64 encoded.
`bbox`	boolean	no	Return the top-left and bottom-right corners of each face rectangle. On this operation it is on by default.
`bbox_pro`	boolean	no	Return four `[x, y]` corner points of each face rectangle.
`bbox_real`	boolean	no	Return the four corner points in the coordinate space of the uploaded image.

Response

A body that cannot be processed arrives with status of error. See response format and errors.

HTTP 200. Detection finished. Read results per uploaded image.

Field	Type	Description
`status`	string	Always `ok` on this body.
`spent`	integer	Processing time in milliseconds.
`results`	array of array of object or object	One entry per uploaded image, in upload order. An image with no face contributes an entry that carries `message` only. Otherwise the entry lists the faces of that image, highest detection score first.
`results[].confidence`	string	The detector confidence that this is a face, as a percentage string.
`results[].yaw`	number	Head rotation left or right, in degrees.
`results[].pitch`	number	Head tilt up or down, in degrees.
`results[].features`	array of object	The results of the checks named in `feature_check`, one entry per feature, each with `name`, `result` and `spent`.
`results[].bbox`	array of number	The face rectangle as `[x1, y1, x2, y2]`.
`results[].thumb`	string (base64)	The cropped face, base64 encoded. Present only when `thumb` was requested.
`results[].origin_shape`	array of integer	The size of the processed image, as `[width, height]`.

Errors

400: The body failed validation. The answer has status of error and a details list with one entry per offending field (path, expected, actual).
401: The token is missing, expired or unknown.

A refusal can also come before the operation runs: an address outside your IP allowlist, a token bound to another address, or a body that is not valid JSON. See response format and errors.

Example

Request:

curl -X POST "<API_BASE_URL>/face/detect" \
  -F "token=<your permanent API token>" \
  -F "images=@photo.jpg" \
  -F "multi=false"

Response:

{
  "status": "ok",
  "spent": 412,
  "results": [
    [
      {
        "confidence": "99%",
        "yaw": 4,
        "pitch": -2,
        "features": [],
        "bbox": [
          120,
          84,
          232,
          196
        ],
        "origin_shape": [
          640,
          480
        ]
      }
    ]
  ]
}