FaceMark API Documentation

Contents

Usage Sample

Usage Sample

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

Overview

FaceMark is a powerful API for facial feature detection. It finds 68 points for a frontal face and 35 for a profile one. FaceMark detects landmarks for faces on the image specified by URL or uploaded as a file and produces JSON output containing a vector of facial landmarks and orientation for each face found. Free usage plan available!

Endpoints

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

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

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

HTTP Method: GET

Parameters:

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


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

HTTP Method: POST

Parameters:

image – Image you wish to find facial features on (as uploaded file).

Image Restrictions

FaceMark works best on upright faces, eyes open, with no objects that obscure face.

Both endpoints have the same source image restrictions:

Supported formats: JPEG, PNG and GIF

Resolution: up to 8192×8192

File size: up to 20 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" : "profile-right",
      "landmarks" : [
        {"x" : 549, "y" : 125},
        {"x" : 568, "y" : 189},
        {"x" : 562, "y" : 226},
        {"x" : 584, "y" : 261},
        {"x" : 607, "y" : 297},
        {"x" : 585, "y" : 319},
        {"x" : 595, "y" : 341},
        {"x" : 585, "y" : 364},
        {"x" : 590, "y" : 385},
        {"x" : 573, "y" : 401},
        {"x" : 571, "y" : 427},
        {"x" : 530, "y" : 454},
        {"x" : 470, "y" : 451},
        {"x" : 385, "y" : 316},
        {"x" : 331, "y" : 301},
        {"x" : 310, "y" : 245},
        {"x" : 331, "y" : 213},
        {"x" : 357, "y" : 246},
        {"x" : 366, "y" : 264},
        {"x" : 375, "y" : 290},
        {"x" : 344, "y" : 284},
        {"x" : 574, "y" : 379},
        {"x" : 560, "y" : 367},
        {"x" : 578, "y" : 353},
        {"x" : 560, "y" : 302},
        {"x" : 574, "y" : 285},
        {"x" : 542, "y" : 242},
        {"x" : 523, "y" : 230},
        {"x" : 546, "y" : 225},
        {"x" : 517, "y" : 195},
        {"x" : 543, "y" : 180},
        {"x" : 458, "y" : 29},
        {"x" : 368, "y" : 12},
        {"x" : 256, "y" : 41},
        {"x" : 199, "y" : 149}
      ],
      "image" : {
        "width" : 800,
        "height" : 600
      }
    }
  ]
}
                

Response object contains the "faces" field which is an array of faces found. Please note that the number of faces FaceMark can process on a single image depends on your pricing plan. If the image contains more faces than your pricing plan supports, FaceMark will choose faces that are closer to the center of the image. Each object in the "faces" array contains the "orientation" field which determines face orientation ("frontal", "profile-left" or "profile-right"). The "landmarks" field contains an array of facial landmarks for each face found. Please note that frontal and profile faces have different landmark sets. For more information on landmark placement see the following section.

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

Please note: you will not be charged for an API call if FaceMark fails to find at least one face (the "faces" array is empty).

Landmarks

FaceMark returns an array of facial landmarks for each face. The number of landmarks and their order are always the same within each set (however new points may eventually be added to the end of the array). The following images show the reference landmark placement (numbers represent indices in the "landmarks" array starting with zero):

Frontal Landmarks

This is a common landmark set of 68 points originated in XM2VTS database markup.

Frontal Landmarks

Profile Landmarks

Profile landmark set currently contains 35 points placed as shown on the image:

Profile Landmarks

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 a bad request (URL not found, image size is too large, etc.)

500 – Indicates an 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.

Please note: you will not be charged for unsuccessful calls - only successful calls count.

Getting Started

First of all, you may wish to try a demo. Using FaceMark API from your application is pretty simple: just visit FaceMark on Mashape and subscribe a pricing plan you need (including a free one). After that you can perform API calls from the test console, try cURL examples, download a client library for a language of your choice or simply consume the API in a plain REST.