Read the full API documentation

SkyBiometry uses completely different computer vision algorithms for face detection and recognition than face.com. Therefore results may differ. We have made extensions to the API that provide additional value. For example, we return dark_glasses attribute in addition to glasses to differentiate dark glasses from clear ones. Determination of some face attributes is not implemented yet. If you need them desperately, please, let us know and we will do our best to implement them as the first additions to algorithms already in use.

api authentication

client authentication

Every call to the API is required to be authorized, which basically means that you must sign up and obtain API access keys before accessing the service. Once that is done, you are ready to go coding.

SkyBiometry provides two ways for the client to authenticate himself:

  • api_key and api_secret – by choosing this method every call to API must include api_key and api_secret. By using this fields we can map API call to the API user.
  • api_key and domain authentication – there are some situations when disclosing api_secret is not an option (like using java script client code or flash). Instead of disclosing api_secret, API user can choose domain authentication method. During the call there is no need to specify api_secret, instead user will be authenticated by calling domain, which will be compared to specified in user profile settings.

Back To Top

api client libraries

libraries

Available client libraries:

NuGet
NuGet package can be used to add precompiled SkyBiometry client library through NuGet package manager in VisualStudio 2010 and higher.
Client library can be used in .NET Framework 4.0 and higher, Silverlight 4 and higher, Windows Phone 7.5 and higher and .NET for Windows Store apps.
C#
C# client library source code (version 1.1.10, last updated on 27 September 2013), can be used to directly add SkyBiometry client code to your application. Client library sources can be used in .NET Framework 4.0 and higher, Silverlight 4 and higher, Windows Phone 7.5 and higher and .NET for Windows Store apps.
Note that you have to install Json.NET package to the solution.
Python
Python client library source code was originally created by Tomaž Muraus and is now adapted to use SkyBiometry Face Detection and Recognition API. It is hosted on GitHub so every developer can clone and improve it.
Ruby
Ruby client gem source code was originally created by Roc Yu and is now adapted to use SkyBiometry Face Detection and Recognition API. It is also hosted on GitHub so every developer can clone and improve it.
Mashape
The cloud API hub Mashape generated client libraries for Java, PHP, Python, Ruby, and Objective-C. You will need to have accounts both at Mashape and SkyBiometry to use them.
PHP
PHP client library source code was originally created by face.com developers and is now adapted to use SkyBiometry Face Detection and Recognition API. It is also hosted on GitHub so every developer can clone and improve it.
PHP
JavaScript client library source code was originally created by face.com developers and is now adapted to use SkyBiometry Face Detection and Recognition API. It is also hosted on GitHub so every developer can clone and improve it.
PHP
iPhone client library source code was originally created by Sergio (sergiomtzlosa) and is now adapted to use SkyBiometry Face Detection and Recognition API. It is also hosted on GitHub so every developer can clone and improve it.
PHP
Java client library source code was originally created by Marlon Hendred and is now adapted to use SkyBiometry Face Detection and Recognition API. It is also hosted on GitHub so every developer can clone and improve it.

More client libraries will be available for download soon. Until then, you can use face.com client libraries, only change API access endpoint tohttp://api.skybiometry.com/fc/.

Back To Top

api overview

examples

 

http://api.skybiometry.com/fc/faces/detect.json?api_key=aa754b54b37&api_secret=4b3a4c6d4c&urls=http://tinyurl.com/673cksr
http://api.skybiometry.com/fc/faces/detect.json?api_key=aa754b54b37&api_secret=4b3a4c6d4c&callback=processResponce&urls=http://tinyurl.com/673cksr
http://api.skybiometry.com/fc/account/limits.xml?api_key=aa754b54b37&api_secret=4b3a4c6d4c
https://api.skybiometry.com/fc/account/namespaces.xml?api_key=aa754b54b37&api_secret=4b3a4c6d4c

Back To Top

API method

API method
Face Detection and Recognition API method name. Currently supported methods include: faces/detect, faces/recognize, faces/train, faces/status, tags/get, tags/add, tags/save, tags/remove, account/authenticate, account/limits and account/users.
response format
json (default) or xml
api_key and api_secret
these keys are generated automatically when creating application in user zone. There is a way not to specify api_secret by using domain authentication, which can be useful in some scenarios when application creator do not want the secret key to be known to end user (who could abuse the limits assigned to account).
other parameters
other parameters include common parameters that could be used when calling all methods and method parameters that should be specified when calling only specified method.
common parameters:

  • callback – JavaScript method to wrap a JSON-formatted response (for JSONP support, ignored if response format=xml)
  • callback_url – asynchronously invoke specified API method, and POST the response to the specified callback url. Suitable for calling lengthy operations. Response is POSTed to the callback_url as json/xml in a field called ‘data’. If response is not required no-reply constant may be used.

Back To Top

REST interface

Our API uses REST interface. In general, it means that API methods are called over the internet, using standard HTTP methods like GET and POST to api.skybiometry.com/fc/. This means that there are no restriction to choosing programming language for development, as long as it supports HTTP communication. We have also prepared some client-side communication implementations for widely spread language, they can be found here.

Depending on the HTTP request parameters, server can generate response in either JSON or XML. We also support JSONP callbacks to simplify application development in JavaScript and callbacks for asynchronous invoking of lengthy operations (more information below).

Common method invocation call looks like this:

http://api.skybiometry.com/fc/{API method}.{response format}?api_key=…&api_secret=…&{other parameters}

In cases where you want to have more security for calling our API, it is also available through HTTPS. Change http to https in method invocation call to access API through HTTPS.

Back To Top

overview

This section describes how to use SkyBiometry Face Detection and Recognition REST API.

Here at SkyBiometry we think that documentation is very important, however we would like to make it as simple as possible. There is nothing more interesting than to start coding straight away and go to documentation only if something happened unexpectedly.

 

Back To Top

api reference

account/users

Returns user list that were registered in the specified data namespaces. Users are added to namespaces by calling tags/save method.

Method entry point:

http://api.skybiometry.com/fc/account/users

Supported HTTP methods
GET, POST.
Required parameters

example:

http://api.skybiometry.com/fc/account/users.json?api_key=aa754b54b37&api_secret=4b3a4c6d4c

response:
{
"status" : "success",
"users" : {
"docs": [
"mark@docs",
"britney@docs"
] }
}

Back To Top

account/namespaces

Returns all valid data namespaces for application authorized by the specified api_key.

Method entry point:

http://api.skybiometry.com/fc/account/namespaces

Supported HTTP methods
GET, POST.
Required parameters

example:

http://api.skybiometry.com/fc/account/namespaces.json?api_key=aa754b54b37&api_secret=4b3a4c6d4c

response:
{
"status" : "success",
"namespaces" : [
{
"name" : "docs",
"size" : 2,
"share_mode" : "Private",
"owner" : true
}
] }

Back To Top

account/limits

Returns limits/quota usage information for calling application/account.

Method entry point:

http://api.skybiometry.com/fc/account/limits

Supported HTTP methods
GET, POST.
Required parameters

example:

http://api.skybiometry.com/fc/account/limits.json?api_key=aa754b54b37&api_secret=4b3a4c6d4c

response:
{
"status" : "success",
"usage" : {
"used" : 0,
"remaining" : 100,
"limit" : 100,
"reset_time_text" : "Mon, 24 September 2012 12:28:52 +0000",
"reset_time" : 1348489732,
"namespace_used" : 2,
"namespace_limit" : 2
}
}

Back To Top

account/authenticate

Returns authentication status. Method can be used to test connection and/or authentication to the API access point. It is not required to call this method before calling any other API methods.

Method entry point:

http://api.skybiometry.com/fc/account/authenticate

Supported HTTP methods
GET, POST.
Required parameters

example:

http://api.skybiometry.com/fc/account/authenticate.json?api_key=aa754b54b37&api_secret=4b3a4c6d4c

response:
{
"status" : "success",
"authenticated" : true
}

Back To Top

tags/remove

Removes a previously saved tag using tags/save.

Note: when removing tag that was trained to data namespace using faces/train, you must call faces/train again to persist changes made by removing specified tag.

Method entry point:

http://api.skybiometry.com/fc/tags/remove

Supported HTTP methods
GET, POST.
Required parameters
Optional parameters
  • password – tags.remove can be password protected if you want to make tags.remove a administrative operation. You can specify password in account settings.

example:

http://api.skybiometry.com/fc/tags/remove.json?api_key=aa754b54b37&api_secret=4b3a4c6d4c&tids=b1dcbe53_59ec9bb2ad15f

response:
{
"status" : "success",
"removed_tags" : [
{
"removed_tid" : "b1dcbe53_59ec9bb2ad15f",
"tid" : "b1dcbe53_59ec9bb2ad15f"
}
],
"message" : "Tag removed"
}

Back To Top

tags/save

Saves a specified face tag to permanent storage. Once the face tag has been saved, you can call faces/train method, which will use the saved tag information to create face template for specified user id and will add it to specified data namespace. When completed you can start recognizing the specified user id (using faces/recognize method).

Method entry point:

http://api.skybiometry.com/fc/tags/save

Supported HTTP methods
GET, POST.
Required parameters
Optional parameters
  • label – display name of the user being tagged (e.g. First and Last name). Note that this information is saved and can later be retrieved per tag, not per user.
  • password – tags.save can be password protected if you want to make tags.save a administrative operation. You can specify password in account settings.

example:

http://api.skybiometry.com/fc/tags/save.json?api_key=aa754b54b37&api_secret=4b3a4c6d4c&uid=mark@docs&tids=TEMP_F@0c95576847e9cd7123f1e304b1dcbe53_59ec9bb2ad15f_56.53_40.83_0_1

response:
{
"status" : "success",
"saved_tags" : [
{
"detected_tid" : "TEMP_F@0c95576847e9cd7123f1e304b1dcbe53_59ec9bb2ad15f_56.53_40.83_0_1",
"tid" : "b1dcbe53_59ec9bb2ad15f"
}
],
"message" : "Tag saved with uid: mark@docs, label: "
}

Back To Top

tags/add

Tags/add method allows to add face tags manually.

Note: tags added manually can not be used to enroll/train user to data namespace, this is the only difference between the automatic tags (obtained through faces/detect method) and manual.

Method entry point:

http://api.skybiometry.com/fc/tags/add

Supported HTTP methods
GET, POST.
Required parameters
  • standard API parameters
  • url – url to the image to add the tag to (accepted image formats: PNG, JPEG, BMP, JPEG2000).
  • x – horizontal center position of the tag, as a percentage from 0 to 100, from the left of the photo.
  • y – vertical center position of the tag, as a percentage from 0 to 100, from the left of the photo.
  • width – width of the tag, as a percentage from 0 to 100.
  • height – height of the tag, as a percentage from 0 to 100.
  • uid – id of the user being tagged.
Optional parameters
  • label – display name of the user being tagged (e.g. First and Last name). Note that this information is saved and can later be retrieved per tag, not per user.
  • password – tags.add can be password protected if you want to make tags.add a administrative operation. You can specify password in account settings.

example:

http://api.skybiometry.com/fc/tags/add.json?api_key=aa754b54b37&api_secret=4b3a4c6d4c&url=http://tinyurl.com/673cksr&x=10&y=15&width=30&height=28&uid=mark@docs

response:
{
"status" : "success"
}

Back To Top

tags/get

Tags/get method allows to get already saved tags to data namespace. By specifying different parameters and criteria you can influence the returned tags.

Method entry point:

http://api.skybiometry.com/fc/tags/get

Supported HTTP methods
GET, POST.
Required parameters
  • standard API parameters
  • uids – a comma separated list of user ids to get tags for.
  • pids – a comma separated list of photo ids to get tags for (photo ids are returned for faces/detect and faces/recognize).
  • urls – a comma separated list of images to get tags for (accepted image formats: PNG, JPEG, BMP, JPEG2000).
Optional parameters
  • limit – maximum tags to return (default: 5).
  • together – when multiple uids are provided, return only tags for photos where all uids appear together in the photo(s) (default: false).
  • order – specifies the order of returned tags (recent – for latest tags, random – random selected tags) (default: “recent”).
  • namespace – default data namespace to be used for all specified uids without data namespace specified.
  • filter – ability to specify facial attributes for filtering the returned tags.

Note: at least one of the required parameters should be specified. You can also upload an image instead of specifying image urls.

Note: in case where you want to POST images instead of specifying urls, request to the method must be formed as a MIME multi-part message sent using POST data. Each argument should be specified as a separate chunk of form data.

example:

http://api.skybiometry.com/fc/tags/get.json?api_key=aa754b54b37&api_secret=4b3a4c6d4c&uids=mary@docs

response:
{
"photos" : [
{
"url" : "http://tinyurl.com/673cksa",
"pid" : "F@053a763a06d9d578430b9f2d06c686bb_f0bf798c4c4e8",
"width" : 1024,
"height" : 767,
"tags" : [
{
"tid" : "c24ac564_f0bf798c4c4e8",
"recognizable" : true,
"uids" : [
{
"uid" : "mary@docs",
"confidence" : 100
}
],
"threshold" : 50,
"label" : "",
"confirmed" : true,
"manual" : false,
"width" :27.73,
"height" : 37.03,
"center" : { "x" : 64.75, "y" : 48.24 },
"eye_left" : { "x" : 66.5, "y" : 39.24 },
"eye_right" : { "x" : 53.12, "y" : 34.55 },
"yaw" : 45,
"roll" : 15,
"pitch" : 0,
"attributes" : {
"face" : { "value" : "true", "confidence" : 71 }
}
}
] }
],
"status" : "success",
"usage" : {
"used" : 1,
"remaining" : 99,
"limit" : 100,
"reset_time_text" : "Fri, 22 September 2012 12:57:19 +0000",
"reset_time" : 1348232239
}
}

Back To Top

faces/status

Method can be used to get training status for specified users.

Method entry point:

http://api.skybiometry.com/fc/faces/status

Supported HTTP methods
GET, POST.
Required parameters
Optional parameters
  • namespace – default data namespace to be used for all specified uids without data namespace specified.

example:

http://api.skybiometry.com/fc/faces/status.json?api_key=aa754b54b37&api_secret=4b3a4c6d4c&uids=mark@docs

response:
{
"status" : "success",
"user_statuses": [
{
"uid": "mark@docs",
"training_set_size" : 2,
"last_trained" : 1348662115,
"training_in_progress" : false
}
] }

Back To Top

faces/train

Method is used to train specified users. Method uses tags previously saved using tags/save methods and creates face template for the specified user ids.

Once the face tags were trained, specified user id can be recognized using faces/recognize method calls.

Note: currently call to faces/train is a blocking call, which means that the call will return when all the requested tags will be processed. You can asynchronously query the status of the training procedure by calling faces/status method.

Method entry point:

http://api.skybiometry.com/fc/faces/train

Supported HTTP methods
GET, POST.
Required parameters
Optional parameters
  • namespace – default data namespace to be used for all specified uids without data namespace specified.

Note: method result includes specified user id training statuses:

  • no_training_set – user ids, for which there is not enough data to create face templates.
  • created – user ids, for which new face templates were created.
  • updated – user ids, for which face templates were changed/updated.
  • unchanged – user ids, for which no changes have been made.
  • in_progress – user ids, for which changes are being made (maybe by another training call).

example:

http://api.skybiometry.com/fc/faces/train.json?api_key=aa754b54b37&api_secret=4b3a4c6d4c&uids=mark@docs

response:

{
"status" : "success",
"created" : [
{
"uid" : "mark@docs",
"training_set_size" : 2,
"last_trained" : 1348662115,
"training_in_progress" : false
}
],
"usage" : {
"used" : 1,
"remaining" : 99,
"limit" : 100,
"reset_time_text" : "Fri, 22 September 2012 12:57:19 +0000",
"reset_time" : 1348232239
}
}

Back To Top

faces/group

Method can be used to detect, group and optionally recognize one or more user faces in one or more photos. faces/group method tries to match all the faces that were found in the images specified by urls or through POST one to other, then assigns a group ID for all detected faces that appear to be of the same person. If user ids are specified when calling this methods, method also attempts to assign the most likely user id for each detected face/group of faces. Returned result are similar to faces/recognize method results.

Api call usage is limited. Each passed image (either URL or through POST) is added to your allowed usage.

Note: returned tags can be used to train new users (using tags/save), without the need of additional call to faces/detect).

Method entry point:

http://api.skybiometry.com/fc/faces/group

Supported HTTP methods
GET, POST.
Required parameters
  • uids – a comma separated list of user ids to search for.
  • urls – a comma separated list of images (accepted image formats: PNG, JPEG, BMP, JPEG2000).
Optional parameters
  • namespace – default data namespace to be used for all specified uids without data namespace specified.
  • detector – face detection quality attribute. Normal (default) – fast face and attribute detection, aggressive – more accurate and slower face and attribute detection.
  • attributes – specifies which attributes will be returned with the results. Accepted values: all, none or a comma separated list of supported attributes.
  • threshold – specifies threshold used for tags comparison (minimal confidence value) and splitting faces to groups as a percentage from 0 to 100. Default value is 70.
  • limit – specifies maximum number of matches that will be returned with the results. If not specified value of 100 will be used.
  • return_similarities – specifies whether for each returned tag similarity with all other tags scores will be returned with the results. Zero scores will be skipped.
  • detect_all_feature_points – specifies that all possible feature points are detected if set to true.

Note: in case where you want to POST images instead of specifying urls, request to the method must be formed as a MIME multi-part message sent using POST data. Each argument should be specified as a separate chunk of form data.

Note: in order to minimize query size and in cases you want to use all trained user ids in the database, you can use ‘all@namespace’ keyword as uidsparameter value.

example:

http://api.skybiometry.com/fc/faces/group.json?api_key=aa754b54b37&api_secret=4b3a4c6d4c&urls=http://tinyurl.com/673cksa,http://tinyurl.com/673cksr

response:

{
"groups" : [
{
"tids" : [
"c24ac564_f0bf798c4c4e8",
"TEMP_F@0335b683720f6fcd33b9f432caaf611e_8173f0cbb51b5_46.12_42.06_0_1"
] }
],
"photos" : [
{
"url" : "http://tinyurl.com/673cksr",
"pid" : "F@053a763a06d9d578430b9f2d06c686bb_f0bf798c4c4e8",
"width" : 1024,
"height" : 767,
"tags" : [
{
"tid" : "c24ac564_f0bf798c4c4e8",
"recognizable" : true,
"uids" : [
{
"uid" : "mary@pavelsm",
"confidence" : 98
}
],
"threshold" : 50,
"label" : "",
"confirmed" : true,
"manual" : false,
"width" : 27.73,
"height" : 37.03,
"center" : { "x" : 64.75, "y" : 48.24 },
"eye_left" : { "x" : 66.5, "y" : 39.24 },
"eye_right" : { "x" : 53.12, "y" : 34.55 },
"yaw" : 45,
"roll" : 15,
"pitch" : 0,
"attributes" : {
"face" : { "value" : "true", "confidence" : 71 }
},
"similarities" : [
{
"tid" : "TEMP_F@0335b683720f6fcd33b9f432caaf611e_8173f0cbb51b5_46.12_42.06_0_1",
"similarity" : 90
}
] }
] },
{
"url" : "http://tinyurl.com/673cksa",
"pid" : "F@0335b683720f6fcd33b9f4326a4fd717_8173f0cbb51b5",
"width" : 800,
"height" : 1001,
"tags" : [
{
"tid" : "TEMP_F@0335b683720f6fcd33b9f432caaf611e_8173f0cbb51b5_46.12_42.06_0_1",
"recognizable" : true,
"uids" : [],
"label" : "",
"confirmed" : false,
"manual" : false,
"width" : 25.62,
"height" : 20.48,
"center" : { "x" :46.12, "y" : 42.06 },
"eye_left" : {"x" : 46.25, "y" : 36.96 },
"eye_right" : { "x" : 33.5, "y" : 36.76},
"yaw" : 45,
"roll" : 1,
"pitch" : 0,
"attributes" : {
"face" : { "value" : "true", "confidence" : 72 }
},
"similarities" : [
{
"tid" : "c24ac564_f0bf798c4c4e8",
"similarity" : 90
}
] }
] }
],
"status" : "success",
"usage" : {
"used" : 2,
"remaining" : 98,
"limit" : 100,
"reset_time_text" : "Thu, 27 September 2012 08:54:38 +0000",
"reset_time":1348736078
}
}

Back To Top

faces/recognize

Method is used for recognizing trained users in one or more photos. For each detected face, method will return user ids that match specified face or empty result set if no matches found. Each tag also includes a threshold score, if matching score is below this threshold – matched user id can be treated as unlikely match.

Api call usage is limited. Each passed image (either URL or through POST) is added to your allowed usage.

Note: as a side effect, faces/recognize also does face detection and therefore returns similar results as faces/detect. This means that returned tags can be used to train new users (using tags/save), without the need of additional call to faces/detect).

Method entry point:

http://api.skybiometry.com/fc/faces/recognize

Supported HTTP methods
GET, POST.
Required parameters
  • standard API parameters
  • uids – a comma separated list of user ids to search for.
  • urls – a comma separated list of images (accepted image formats: PNG, JPEG, BMP, JPEG2000).
Optional parameters
  • namespace – default data namespace to be used for all specified uids without data namespace specified.
  • detector – face detection quality attribute. Normal (default) – fast face and attribute detection, aggressive – more accurate and slower face and attribute detection.
  • attributes – specifies which attributes will be returned with the results. Accepted values: all, none or a comma separated list of supported attributes.
  • limit – specifies maximum number of matches that will be returned with the results. If not specified value of 100 will be used.
  • detect_all_feature_points – specifies that all possible feature points are detected if set to true.

Note: in case where you want to POST images instead of specifying urls, request to the method must be formed as a MIME multi-part message sent using POST data. Each argument should be specified as a separate chunk of form data.

Note: if specified user ids include user ids which were not yet trained or do not have any training set assigned, they are returned in no_training_set array.

Note: in order to minimize query size and in cases you want to use all trained user ids in the database, you can use ‘all@namespace’ keyword as uidsparameter value.

example:

http://api.skybiometry.com/fc/faces/recognize.json?api_key=aa754b54b37&api_secret=4b3a4c6d4c&urls=http://tinyurl.com/673cksa&uids=mary@docs

response:
{
"photos" : [
{
"url" : "http://tinyurl.com/673cksa",
"pid" : "F@053a763a06d9d578430b9f2d06c686bb_f0bf798c4c4e8",
"width" : 1024,
"height" : 767,
"tags" : [
{
"tid" : "c24ac564_f0bf798c4c4e8",
"recognizable" : true,
"uids" : [
{
"uid" : "mary@docs",
"confidence" : 98
}
],
"threshold" : 50,
"label" : "",
"confirmed" : true,
"manual" : false,
"width" :27.73,
"height" : 37.03,
"center" : { "x" : 64.75, "y" : 48.24 },
"eye_left" : { "x" : 66.5, "y" : 39.24 },
"eye_right" : { "x" : 53.12, "y" : 34.55 },
"yaw" : 45,
"roll" : 15,
"pitch" : 0,
"attributes" : {
"face" : { "value" : "true", "confidence" : 71 }
}
}
] }
],
"status" : "success",
"usage" : {
"used" : 1,
"remaining" : 99,
"limit" : 100,
"reset_time_text" : "Fri, 22 September 2012 12:57:19 +0000",
"reset_time" : 1348232239
}

Back To Top

faces/detect

Returns tags for detected faces in one or more photos, with geometric information of the tag, eyes, nose and mouth, as well as additional attributes such as gender.

API call usage is limited. Each passed image (either URL or through POST) is added to your allowed usage.

Method entry point:

http://api.skybiometry.com/fc/faces/detect

Supported HTTP methods
GET, POST.
Required parameters
  • standard API parameters
  • urls – a comma separated list of images (accepted image formats: PNG, JPEG, BMP, JPEG2000).
Optional parameters
  • detector – face detection quality attribute. Normal (default) – fast face and attribute detection, aggressive – more accurate and slower face and attribute detection.
  • attributes – specifies which attributes will be returned with the results. Accepted values: all, none or a comma separated list of supported attributes.
  • detect_all_feature_points – specifies that all possible feature points are detected if set to true.

Note: in case where you want to POST images instead of specifying urls, request to the method must be formed as a MIME multi-part message sent using POST data. Each argument should be specified as a separate chunk of form data.

Note: in case when you want to enroll specified person to the data namespace, selected tags must be first saved using tags/save method. All unsaved temporary tags are disposed regularly and can be used no longer than a day.

Note: API automatically rescales images to maximum width/height of 1024 pixels. Higher sized images will be automatically resized.

Note: returned response includes face tags found in the specified images. As images are internally rescaled, all coordinates are provided in percents to support any image scale (i.e. x coordinate is returned as percent of the width and y coordinate – as percent of the height with origin being image left-top corner).

Note: face/detect is the first step in adding user id for recognition. Please see tags/save for more information.

example:

http://api.skybiometry.com/fc/faces/detect.json?api_key=aa754b54b37&api_secret=4b3a4c6d4c&urls=http://tinyurl.com/673cksr&attributes=all

response:

{
"photos" : [
{
"url" : "http://tinyurl.com/673cksr",
"pid" : "F@0c95576847e9cd7123f1e304476b59ae_59ec9bb2ad15f",
"width" : 375,
"height" : 409,
"tags" : [
{
"tid" : "TEMP_F@0c95576847e9cd7123f1e304b1dcbe53_59ec9bb2ad15f_56.53_40.83_0_1",
"recognizable" : true,
"confirmed" : false,
"manual" : false,
"width" : 30.67,
"height" : 28.12,
"center" : { "x" : 56.53, "y" : 40.83},
"eye_left" : { "x" : 66.93, "y" : 33.99},
"eye_right" : { "x" : 51.73, "y" : 33.99},
"yaw" : -16,
"roll" : 0,
"pitch" : 0,
"attributes" : {
"face" : { "value" : "true", "confidence" : 82 },
"gender" : { "value" : "female", "confidence" : 80 },
"glasses":{"value" : "true", "confidence" : 100},
"dark_glasses":{"value" : "true", "confidence" : 72},
"smiling":{"value" : "false", "confidence" : 35}
}
}
] }
],
"status" : "success",
"usage" : {
"used" : 1,
"remaining" : 99,
"limit" : 100,
"reset_time_text" : "Fri, 21 September 2012 12:57:19 +0000",
"reset_time" : 1348232239
}
}

Back To Top

api results

if something goes wrong

In case any method of the API fails, then the response object contains status field with a value of “failure” along with error_code and error_message fields from the following table:

Error code Error message
20 IMG_DECODE_ERROR
21 IMG_RESIZE_ERROR
30 DOWNLOAD_ERROR
31 DOWNLOAD_ERROR_FILE_NOT_FOUND
32 DOWNLOAD_ERROR_SERVER_TIMEOUT
33 DOWNLOAD_ERROR_FILE_TOO_LARGE
34 DOWNLOAD_ERROR_MALFORMED_URL
35 DOWNLOAD_ERROR_UNKNOWN_HOST
36 DOWNLOAD_ERROR_CONNECTION_REFUSED
104 INTERNAL_ERROR
105 SERVICE_TEMPORARILY_UNAVAILABLE
107 UNKNOWN_ERROR
201 API_KEY_DOES_NOT_EXIST
202 API_KEY_USAGE_PASSED_QUOTA
203 API_KEY_CONCURRENT_USAGE_PASSED_QUOTA
204 API_KEY_NOT_AUTHENTICATED
205 API_PASSWORD_NOT_CORRECT
206 MAX_NUMBERS_OF_UIDS_TRAINED_IN_NAMESPACE_EXCEEDED
207 TOO_MANY_ERRORS
301 TAG_NOT_FOUND
303 FILTER_SYNTAX_ERROR
304 AUTHORIZATION_ERROR
306 TAG_ALREADY_EXIST
307 ACTION_NOT_PERMITTED
401 UNKNWOWN_REST_METHOD
402 MISSING_ARGUMENTS
403 MISSING_USER_NAMESPACE
404 UNAUTHORIZED_USER_NAMESPACE
405 UNAUTHORIZED_UID
406 INVALID_ARGUMENTS_VALUE
407 ARGUMENT_LIST_TOO_LONG
408 UNAUTHORIZED_CALLBACK_URL_DOMAIN
409 UID_TOO_LONG
410 SYNCHRONOUS_REQUEST_TOO_BIG

Note: in case method succeeds, status field is returned as “success” and error_code/error_message fields are omitted.

Note: in case method succeeds partially, i.e. when a request has multiple photos in the response, and has one or more failures mixed with successful responses (e.g. wrong URLs in for some of the photos specified) then the status field will contain value of “partial”.

Note: operation_id can be used to identify a particular request when contacting our support.

Back To Top

supported facial attributes

Each attribute in attributes field in the response have two subfields: value (string) and confidence (integer)

Currently supported facial attributes along with possible values can be found in the following table:

Requested attribute Response attribute Values
face true
gender gender male, female
glasses glasses true, false
glasses dark_glasses true, false
smiling smiling true, false
lips lips sealed, parted
eyes eyes open, closed
age age_est [estimated age in years]
mood mood happy, sad, angry, surprised, disgusted, scared, neutral
mood neutral_mood, anger, disgust, fear, happiness, sadness, surprise true, false

Note: in case attribute value cannot be determined it is not returned. If value is determined it is returned along with confidence value as a percentage from 0 to 100

Note: face attribute is the default and is always returned regardless of the specified attributes. dark_glasses attribute is returned additionally whether glassesis requested to differentiate between dark and clear glasses. mood attribute is returned along with 7 more attributes: confidences for each one of the basic emotions plus neutral_mood confidence.

Back To Top

result objects

The result of the API call is a JSON or XML object containing the requested information. The following table summarizes response object fields:

result object

Name Type Value
groups array List of one or more group of faces found in photos, when using faces/group.
group object The group of faces found in photos.
photos array List of all the photo objects that were included in the request, one photo per URL or image stream specified.
photo object The object describing an image included in the request.
tags array List of zero or more face tag objects found in the photo.
tag object The face object found in a photo.
uids array List of possible matches for the face tag (faces/recognize only). Only user ids that were specified during the faces/recognize call (either explicitly or through a list) will be returned. Refer to the threshold for a recommendation of which confidence scores are high/low for this call. When tags are saved, the confidence score is always 100.
uid object A possible match for the face tag
points array List of detected facial feature points. Available only if detect_all_feature_points=true is specified in the request.
point object Detected facial feature point.
similarities array List of similarities of this face tag with other face tags in request (faces/group only).
similarity object A similarity score of two faces tags.
user_statuses array List of training statuses of the users (faces/status only).
user_status object The training status of the user.
namespaces array List of namespaces (account/namespaces only).
namespacedata object The object describing namespace.
saved_tags array List of saved tags (tags/save only).
saved_tag object The object describing saved tag.
removed_tags array List of removed tags (tags/remove only).
removed_tag object The object describing removed tag.
usage object The usage of the API. All rate limited methods and account/limits return this object.

Yaw (rotation about Y axis), roll (rotation about Z axis) and pitch (rotation about X axis) angles are provided in degrees in range from -90 to 90. They are Tait-Bryan angles in right-hand 3D Euclidian space in image coordinate system (i.e. X axis is horizontal and points towards the right edge of the image, Y axis is vertical and points towards the bottom edge of the image and Z axis is perpendicular to the image and points away from the viewer). The rotation is reported as it would be performed about geometrical center of the head in the following order: roll (with positive direction being clockwise, towards the left shoulder of the subject), pitch (with positive direction being down) and yaw (with positive direction being to the left, towards the right shoulder of the subject). Remember that subjects are mirrored in the photo, i.e. subject’s left eye and left body parts are at the right and vice versa.

Back To Top

api usage limits

subscription limits

Some of the methods of the API (like faces/detect, faces/group and faces/recognize) are rate limited. All of the created workspace(s)/application(s) share the same limits assigned to current user account. User has the ability to select one of the subscriptions available which better suits the needs of the application being created. Among available subscriptions is a FREE subscription, which is assigned with a limit of 100 face detection/recognition method calls an hour,monthly usage is limited to 5000 face detection/recognition method calls. Login to see your current usage and usage limits.

In case you feel that none of the available subscriptions satisfies your needs, please contact us and tell us more about your application and what kind of usage/limits you would like to have.

Although only above mentioned methods are rate limited, please do not abuse other methods too. In case system detects over extensive usage of API, it will add the abusing user IP to user black list and user will be blocked from calling any API methods.

Back To Top

api workflow

workflow

Generally API is used for two types of tasks: face detection and face recognition. Doing face detection is pretty easy and straight forward – you just call faces/detect API method with passing image you want to find faces in and get the results. On the other hand, doing face recognition is composed of several steps that should be done before doing any actual face recognition. In other words, face recognition is composed of several steps: face enrollment/trainingand face matching/recognition.

Face enrollment/training – during this step system creates a face template from specified face (face tag) in image and adds created template to data namespace. Data namespace is a place were all of your face templates are stored, so in other words – it is a face template database (every user is allowed to create 2 data namespaces, which can be used by different user’s applications).

Face recognition – during this step system tries to find a match for specified faces in user defined data namespace.

Face enrollment steps (in order of calling):

  1. faces/detect – detects faces in specified images, returns face tags (every tag has unique tag id – tid).
  2. tags/save – saves specified face tags (by tid) with user specified user id(eg. mark@docs, where docs – data namespace name).
  3. faces/train – checks changes for specified user ids (eg. new tags were added using tags/save or removed using tags/remove) and either creates/updates/removes face template for specified user id from data namespace.

Face tags are also returned by faces/recognize and faces/group methods. In case face tag was already saved – saved tid is returned, if it is new tag – temporary tid (starting with TEMP_) is returned. You can use returned tags to add enroll new users, thus skipping a call to faces/detect.

faces/train is potentially a long operation. You can check status of face training being done by calling faces/status method.

Once the enrollment is complete, specified user can be now recognized using faces/recognize method.

Back To Top