FaceRect API Documentation

Contents

Usage Sample

Usage Sample

Feel free to try FaceRect API as much as you like or start using it right now for free!

Overview

FaceRect is a powerful and completely free API for face detection. It finds faces (both frontal and profile) on the image specified by URL or uploaded as a file and is able to find multiple faces on a single photo, producing JSON output with a bounding box for each face found. Additionally FaceRect can find face features for each detected face (eyes, nose and mouth).

For more precise face feature detection please see our FaceMark API (demo and documentation).

Endpoints

Please note: you need a Mashape account to consume the API. Please visit FaceRect on Mashape to learn more.

FaceRect API supports two endpoints that differ only in the way of passing the image:

http://apicloud-facerect.p.mashape.com/process-url.json

HTTP Method: GET

Parameters:

url – URL of the image you wish to find faces on.

features (optional) – Defines whether to search for face features (eyes, nose and mouth) on frontal faces or not. Possible values are "true" and "false". Default is "false", so only face bounding boxes will be returned if not specified. Face features for profile faces are not currently supported.


http://apicloud-facerect.p.mashape.com/process-file.json

HTTP Method: POST

Parameters:

image – Image you wish to find faces on as uploaded file.

features (optional) – Defines whether to search for face features (eyes, nose and mouth) on frontal faces or not. Possible values are "true" and "false". Default is "false", so only face bounding boxes will be returned if not specified. Face features for profile faces are not currently supported.

Image Restrictions

Both endpoints have the same source image restrictions:

Supported formats: JPEG, PNG and GIF

Resolution: up to 4096×4096

File size: up to 10 MBytes


Please note: when using image URL the 'Content-Type' header should be set correctly by the Web-server (as well as the 'Content-Length').

Response

Both endpoints return the same response (with HTTP code 200) which is a JSON object of the following structure:

{
  "faces" : [
    {
      "orientation" : "frontal",
      "x" : 575,
      "y" : 136,
      "width" : 51,
      "height" : 51
    },
    {
      "orientation" : "frontal",
      "x" : 240,
      "y" : 183,
      "width" : 85,
      "height" : 85
    },
    {
      "orientation" : "profile-right",
      "x" : 188,
      "y" : 137,
      "width" : 74,
      "height" : 125
    },
    {
      "orientation" : "profile-right",
      "x" : 116,
      "y" : 177,
      "width" : 100,
      "height" : 169
    }
  ],
  "image" : {
    "width" : 644,
    "height" : 373
  }
}
                

The response object contains the "faces" field which is an array of faces found. Each face is specified by a bounding box in image coordinates. Left top corner of the bounding box has the coordinates of "x" and "y" (both are offsets from the top left corner of the image in pixels), "width" and "height" specify width and height of the bounding box (in pixels). The "orientation" parameter determines face orientation ("frontal", "profile-left" or "profile-right").

Additionally the "image" field provides some image information (width and height in pixels).

If you set `features` parameter to "true", the API will also search for face features on faces with "frontal" orientation (profile feature detection is not currently supported). In this case the response will look like this:

{
  "faces" : [
    {
      "orientation" : "frontal",
      "x" : 111,
      "y" : 87,
      "width" : 294,
      "height" : 294,
      "features" : {
        "eyes" : [
          {
            "x" : 186,
            "y" : 185,
            "width" : 43,
            "height" : 43
          },
          {
            "x" : 285,
            "y" : 179,
            "width" : 55,
            "height" : 55
          }
        ],
        "nose" : {
          "x" : 212,
          "y" : 231,
          "width" : 88,
          "height" : 73
        },
        "mouth" : {
          "x" : 199,
          "y" : 296,
          "width" : 108,
          "height" : 65
        }
      }
    }
  ],
  "image" : {
    "width" : 600,
    "height" : 600
  }
}
                

Each face object will additionally contain the "features" field, that can hold bounding boxes for eyes, nose and mouth (in image coordinates). "eyes" is an array, containing bounding boxes for eyes found for a particular face. Please be aware, that each of the fields ("eyes", "nose" and "mouth") can be missing (if not found on the image). There is also a possibility that only one eye will be reliably detected.

Errors

Errors can be identified by HTTP response codes (codes other than 200 should be considered an unsuccessful call). The following HTTP response codes can be returned by the API:

400 – Indicates bad request (invalid parameter values, URL not found, image size is too large, etc.)

500 – Indicates internal API error. This code, however, is rare and we monitor all the API logs to fix issues as soon as possible. However, if this error persists, please contact us.

Getting Started

First of all, you may wish to try a demo. Using FaceRect API from your application is pretty simple: just visit FaceRect on Mashape. You can perform API calls from the Mashape test console, try cURL examples, download a client library for a language of your choice or simply consume the API in a plain REST.