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.

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.

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.

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

Method entry point:

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

Supported HTTP methods

GET, POST.

Required parameters

• standard API parameters
• namespaces – a comma separated list of one or more data namespaces.

example:

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

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

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

Method entry point:

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

Supported HTTP methods

GET, POST.

Required parameters

• standard API parameters

example:

https://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
}
] }

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

Method entry point:

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

Supported HTTP methods

GET, POST.

Required parameters

• standard API parameters

example:

https://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
}
}

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:

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

Supported HTTP methods

GET, POST.

Required parameters

• standard API parameters

example:

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

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

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:

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

Supported HTTP methods

GET, POST.

Required parameters

• standard API parameters
• tids – one or more tag ids to remove. Tag id is a reference field in the response of faces/detect, faces/recognize and tags/get methods.

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:

https://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"
}

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:

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

Supported HTTP methods

GET, POST.

Required parameters

• standard API parameters
• uid – id of the user being tagged (e.g. mark@docs, where mark – is the name of your choice and docs is the name of created data namespace).
• tids – one or more tag ids to associate with the specified uid. Tag id is a reference field in the response of faces/detect and faces/recognize methods.

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:

https://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: "
}

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:

https://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:

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

response:
{
"status" : "success"
}

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:

https://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:

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

response:
{
"photos" : [
{
"url" : "https://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
}
}

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

Method entry point:

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

Supported HTTP methods

GET, POST.

Required parameters

• standard API parameters
• uids – a comma separated list of user ids to get training information for.

Optional parameters

• namespace – default data namespace to be used for all specified uids without data namespace specified.

example:

https://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
}
] }

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:

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

Supported HTTP methods

GET, POST.

Required parameters

• standard API parameters
• uids – a comma separated list of user ids to begin training for.

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:

https://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
}
}

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:

https://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:

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

response:

{
"groups" : [
{
"tids" : [
"c24ac564_f0bf798c4c4e8",
"TEMP_F@0335b683720f6fcd33b9f432caaf611e_8173f0cbb51b5_46.12_42.06_0_1"
] }
],
"photos" : [
{
"url" : "https://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
}
}


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:

https://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.
• matching_threshold – specifies threshold used for faces comparison (minimal confidence value).  This threshold separates identical from different templates. Matching threshold is linked to false acceptance rate (FAR, different templates erroneously accepted as of the same) of matching algorithm. The higher is threshold, the lower is FAR and higher FRR (false rejection rate, same templates erroneously accepted as different) and vice a versa. Any matching threshold from 0 to 100 can be set.

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:

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

response:
{
"photos" : [
{
"url" : "https://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
}


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:

https://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:

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

response:

{
"photos" : [
{
"url" : "https://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
}
}

result 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.