* In order to comply with GDPR regulations, the ethnicity values are set to zero by default. You can retrieve the ethnicity estimations by explicitly setting the ethnicity request field to true.
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
* In order to comply with GDPR regulations, the ethnicity values are set to zero by default. You can retrieve the ethnicity estimations by explicitly setting the ethnicity request field to true.
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.
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.
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. |
ethnicity | A boolean value indicating wether ethnicity estimations should be returned or not. This field is optional. If not set, false is the default. Possible values can be: 1, 0, true, false. |
Either img or url has to be present in the POST request.
A F.A.C.E. response is an HTTP response containing a JSON format string representing the result of the image analysis.
{
"$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:
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. |
1001 | 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. |
You can find a package containing Javascript examples here. This gives you a good understanding on how the F.A.C.E. API works.
<?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();
?>
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
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 codeHere 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>
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>
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>
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>