Menu

Getting Started

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:

  • Age
  • Gender
  • Mood
  • Facial Expressions
  • Face Position
  • Face Rotation
  • Eye Position
  • Ethnicity
  • Traking Points
  • Clothing Colors

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

Documentation

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 request 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:


Parameter Description
app_key The application key is a 32 characters string that bounds the request to the app of the user in the server. This string allows the request to be authenticated.
img The image to analyze. When this field is set, the content type of the request has to be multipart/form-data. The supported file formats are jpeg and png.
url A URL pointing to an image. When this field is set, the img field must not be present in the request. The F.A.C.E. servers will download the remote resource and perform face analysis, however, if the remote server does not provide the content type, the content type is not correct (image/*) or the download takes more than 5 seconds, the download is aborted.

Either img or url has to be present in the POST request.

Error codes

When error_code is not 0, an error occurrent in the request. Generally the description field indicated the reason for such error. Here you have the list of error codes and their meaning:

Code Description
0 Successfull request. people array might be empty. In this case no face has been detected.
1000 This indicates a server malfunctioning. Please report this errors to support@sightcorp.com.
1100 Authentication error. The license key is invalid.
1200 Request error. The request is malformed: not a POST request, missing image, ecc...
1300 Remote image error. There's an issue downloading the remote image pointed by the url parameter: remote server does not reply, content type not specified, ecc...
1400 Out of credits error. Monthly credits are finished.
1401 Rate limit error. Rate limit has been exceeded. Depending on your subscription, you cannot consume more than a certain amount of credits per second.

Usage Examples

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( 'http://api-face.sightcorp.com/api/detect/',
              data  = { 'app_key' : '<your application key>' },
              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 }
  }
  ]
}
                                

Tutorial

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>