Welcome to Sightcorp's F.A.C.E. API, the face analysis cloud engine based on Sightcorp Face analysis technologies.

This web service has been designed from the ground up to give developers easy access to face information present in images. By sending a picture with one or more faces, the service will reply with a JSON response containing the following information:

The basic account gives you access to a limited amount of API requests per month for free with a base rate limit of one request per second. In order to guarantee continuation of operation for your application, you will have to upgrade to one of our paid monthly subscriptions. For more information, see the pricing page

Overview

F.A.C.E. is a very simple and easy to use web API. It consists of just one endpoint on which the system can be asked to perform face analysis on images through standard HTTP POST requests.
The address of the F.A.C.E. service is api-face.sightcorp.com and the endpoint is /api/detect/.

HTTP POST requests containing an image (or the URL of an image) can be sent to this endpoint. After request validation, face analysis is performed on the image and the results are sent back in JSON format to the client through an HTTP response.
For each successfull image analysis, one credit is subtracted from the account credits. Uppon credit termination the service will stop serving requests.

The Credis System

After registering to the service, you 'll be able to create applications. Each app is assigned an amount of credits depending on the subscription plan. One credit is consumed for each successfull image analysis. Uppon credit termination the service will stop serving requests. Credits are reset at the beginning of every month.

Credits consumption is limited on a rate basis depending on the subscription. The free subscription allows for a rate of one credit per second. This means that the F.A.C.E. servers won't accept more that one analysis request per second. If you want more credits per month or a higher rate you need to pass to one of our paid subscriptions.

F.A.C.E. request

A F.A.C.E. request is an HTTP POST request to the api-face.sightcorp.com/api/detect/ that can have the following parameters:

F.A.C.E. response

A F.A.C.E. response is an HTTP response containing a JSON format string representing the result of the image analysis.

Face analysis result JSON format

{
  "$schema"    : "http://json-schema.org/draft-04/schema#",
  "type"       : "object",
  "properties" : {
    "error_code"  : { "type" : "integer" },
    "description" : { "type" : "string" },
    "img_size"    : { "type" : "object", "properties" : {
      "w" : { "type" : "integer" },
      "h" : { "type" : "integer" } }
    },
    "people" : { "type" : "array", "items" : { "type" : "object",
      "properties" : {
        "age"      : { "type" : "integer", "minimum" : 0 },
        "gender"   : { "type" : "integer", "minimum" : -100, "maximum" : 100 },
        "mood"     : { "type" : "integer", "minimum" : 0,    "maximum" : 100 },
        "position" : { "type" : "object", "properties" : {
          "x" : { "type" : "integer" },
          "y" : { "type" : "integer" },
          "w" : { "type" : "integer" },
          "h" : { "type" : "integer" } }
        },
        "rotation" : { "type" : "object", "properties" : {
          "pitch"  : { "type" : "integer", "minimum" : -180, "maximum" : 180 },
          "roll"   : { "type" : "integer", "minimum" : -180, "maximum" : 180 },
          "yaw"    : { "type" : "integer", "minimum" : -180, "maximum" : 180 } }
        },
        "landmarks" : { "type" : "object", "properties" : {
          "lefteye" : { "type" : "object", "properties" : {
            "x" : { "type" : "integer" },
            "y" : { "type" : "integer" } }
          },
          "righteye" : { "type" : "object", "properties" : {
            "x" : { "type" : "integer" },
            "y" : { "type" : "integer" } }
          },
          "maskpoints" : { "type" : "array", "items" : { "type" : "object",
            "properties" : {
              "x" : { "type" : "integer" },
              "y" : { "type" : "integer" } }
          } }
        } },
        "clothingcolors" : { "type" : "array", "items" : { "type" : "string",
          "pattern" : "^#[a-fA-F0-9]{6}$" }
        },
        "ethnicity" : { "type" : "object", "properties" : {
          "african"   : { "type" : "integer", "minimum" : 0, "maximum" : 100 },
          "asian"     : { "type" : "integer", "minimum" : 0, "maximum" : 100 },
          "caucasian" : { "type" : "integer", "minimum" : 0, "maximum" : 100 },
          "hispanic"  : { "type" : "integer", "minimum" : 0, "maximum" : 100 } }
        },
        "emotions" : { "type" : "object", "properties" : {
          "happiness" : { "type" : "integer", "minimum" : 0, "maximum" : 100 },
          "surprise"  : { "type" : "integer", "minimum" : 0, "maximum" : 100 },
          "anger"     : { "type" : "integer", "minimum" : 0, "maximum" : 100 },
          "disgust"   : { "type" : "integer", "minimum" : 0, "maximum" : 100 },
          "fear"      : { "type" : "integer", "minimum" : 0, "maximum" : 100 },
          "sadness"   : { "type" : "integer", "minimum" : 0, "maximum" : 100 } }
        }
      } }
    }
  }
}
    

In order to keep the JSON schema simpler and more readable, we'll enumerate here additional rules:

• error_code and description are always present.
• error_code reports only F.A.C.E. functionality errors. HTTP errors are reported in the HTTP status code.
• An error_code equal to 0 means a successfull request.
• In each people array item, all the fields are reported.
• A positive gender value indicates a female gender estimation. A negative gender value indicates a male gender estimation.
• mood is meant to represent the smile quantity.
• yaw, roll and pitch values are represented in degrees.
• Each clothingcolors array item string represents an hex code color. 3 main clothing colors are reported or none.
• x and y values represent coordinates relative to the analyzed image where the origin is top left corner.
• w and h values represent respectively the width and the height of a rectangle.
• In position x and y represent the top left corner.

Javascipt examples

You can find a package containing Javascript examples here. This gives you a good understanding on how the F.A.C.E. API works.

F.A.C.E. Detect PHP example

<?php
  require_once 'HttpClient.class.php';

  $parameters = array(
        'app_key' => '<your application key>',
        'url' => '<URL to face image>',
        );

  $face = new HttpClient('api-face.sightcorp.com');
  $response = $face->post("/api/detect/", $parameters);

  echo $face->getContent();
?>
                                     

F.A.C.E. Detect Python example

import requests

json_resp = requests.post( 'https://api-face.sightcorp.com/api/detect/',
              data  = { 'app_key' : '<your application key>', 'ethnicity' : True },
              files = { 'img'     : ( 'filename', open( '<path to file>', 'rb' ) ) } )

print "Response : ", json_resp.text
                                    

F.A.C.E. Response Example

The schema specification of the JSON response can be found documentation along with the POST request specification. The following JSON snippet is an example of a typical F.A.C.E. response:

{
  "error_code": 0,
  "description": "",
  "img_size": { "w": 1280, "h": 960 },
  "people": [
  {
    "age":    29,
    "gender": 99,
    "mood":   64,
    "position": { "x": 432, "y": 246, "w": 503, "h": 503 },
    "rotation": { "yaw": 1, "pitch": -8, "roll": 1 },
    "landmarks": { "lefteye":      { "x": 800, "y": 379 },
                   "righteye":     { "x": 562, "y": 374 },
                   "maskpoints": [ { "x": 800, "y": 379 },
                                   { "x": 562, "y": 374 },
                                   { "x": 412, "y": 410 },
                                    ...
                                    ...
                                    ...
                                   { "x": 664, "y": 616 }]
                                },
    "clothingcolors": [ "#111122", "#112233", "#222233" ],
    "ethnicity": { "african":    7,
                   "asian":     23,
                   "caucasian": 60,
                   "hispanic":   8 },
    "emotions": { "happiness": 0,
                  "surprise":  3,
                  "anger":     0,
                  "disgust":   1,
                  "fear":     10,
                  "sadness":   6 }
  }
  ]
}
                                

Here you can find a set of examples that demonstrate how to use the F.A.C.E. API and its features. You can download the source code of the examples contained in this page as a reference.

Download example code

Example 1 : Basic request

Here is the most basic example. It demonstrates how to perform an API call through a basic html form.

<html>
  <body>
    <form method="post" action="https://api-face.sightcorp.com/api/detect/"
          enctype="multipart/form-data">
      <input type="text" name="app_key" value="Your Key"/>
      <input type="file" name="img"/>
      <input type="submit"/>
    </form>
  </body>
</html>
                               

Example 2 : Remote image resource

The F.A.C.E. API accepts images embedded in the request as well as a url pointing to a remote image. In this example the remote location of an image resource is given.

<html>
  <body>
    <form method="post" action="https://api-face.sightcorp.com/api/detect/"
          enctype="multipart/form-data">
      <input type="text" name="app_key" value="Your Key"/>
      <input type="text" name="url"
          value="http://www.naircare.co.uk/images/main/hub/bg-face.jpg"/>
      <input type="submit"/>
    </form>
  </body>
</html>
                               

Example 3 : Ajax

In this example you can see how to perform asyncronous calls with Javascript. The code below preprocesses the API request before it is sent. Uppon receipt of the F.A.C.E. API response, the successCallback() function is triggered and its code executed.

<html>
  <head>
    <script src="http://code.jquery.com/jquery-1.11.0.min.js"></script>
  </head>
  <body>
    <form id="myform" method="post" action="https://api-face.sightcorp.com/api/detect/"
          enctype="multipart/form-data">
      <input type="text" name="app_key" value="Your Key"/>
      <input type="file" name="img"/>
      <input type="submit"/>
    </form>
    <div id="result">
    </div>

    <script>
      $(document).ready(function() {

        var successCallback = function( data, textStatus, jqXHR ) {
          alert( JSON.stringify( data ) );
          alert( "First person Age : " + data.people[0].age );
        };

        var failCallback = function( jqXHR, textStatus, errorThrown ) {
          alert( "There has been an error!" );
        };

        $( "#myform" ).submit(
          function(e) {
            e.preventDefault();
            var formdata = new FormData( document.getElementById( "myform" ) );
            $.ajax( { url         :  $( this ).attr( 'action' ),
                      type        : "POST",
                      data        : formdata,
                      success     : successCallback,
                      error       : failCallback,
                      processData : false,
                      contentType : false } );
          });

      });
    </script>
  </body>
</html>
                               

Example 4 : Interactivity

This example shows how to add interactivity to a web page by changing the advertisment banner depending on the gender of the person in front of the webcam. To achieve this, a small Javascript library (FACE-1.0.js, included in the example package) is used in order to facilitate the control of the webcam and the communication with the F.A.C.E. API server.

<html>
  <head>
    <style>
      .hidden { display : none; }
      .container { width : 100%; }
      .center { display : block; margin : auto; }
    </style>
  </head>
  <body>

    <!-- Main page content -->
    <video id="webcam_preview" class="hidden" autoplay></video>
    <img id="img_snapshot" src="" class="hidden"/>
    <div class="container"><img class="center" id="advertisement" src="man.jpg"/></div>


    <!-- Load jquery and FACE libraries -->
    <script src="../FACE-1.0.js">
    </script>
    <script src="https://ajax.googleapis.com/ajax/libs/jquery/1.11.0/jquery.min.js">
    </script>

    <!-- Page control -->
    <script>
      // FOR JAVASCRIPT DEMONSTRATION PURPUSES ONLY,
      // NEVER DISCLOSE YOUR KEY TO THIRD PARTIES!
      var options = {};
      options.app_key = '';
      options.onSuccessCallback = success;
      options.onFailureCallback = failure;

      function success( result ) {
        if( result.people.length > 0 ) {
          age    = result.people[0].age;
          gender = result.people[0].gender;

          if( gender < 0 )
            $('#advertisement').attr( 'src', 'man.jpg' )
          else
            $('#advertisement').attr( 'src', 'woman.jpg' )
        }
      }

      function failure( errorCode, errorString ) {
        alert( error );
      }

      function sendDetectRequest() {
        var img = document.querySelector( "#img_snapshot" );
        // Check if a snapshot has been taken
        if( img.naturalWidth == 0 ||  img.naturalHeight == 0 )
          return;
        options.img = FACE.util.dataURItoBlob( img.src );
        FACE.sendFaceRequest( options );
      }

      function startCapture() {
        FACE.webcam.startPlaying( "webcam_preview" );
        setInterval( function()
        {
          FACE.webcam.takePicture( "webcam_preview", "img_snapshot" );
          sendDetectRequest();
        },
        1100 );
      }

      // Trigger the start
      $( document ).ready( function() {
        if( options.app_key == '' ) {
          alert( 'Please specify your keys in the source' );
        } else {
          startCapture();
        }
      });
    </script>
  </body>
</html>