Documentation

Overview

SkyBiometry introduces cloud-based Face Detection and Recognition API. At the core of the product is one of the worlds best algorithms for the detection and recognition of faces that is successfully used in many commercial products around the globe.

We think face.com team did a great job at creating a REST-like API for face detection, face attributes determination and face recognition. We decided to help the developers who invested time and money in creating applications which use this API. This is intended to be a drop-in replacement for your applications. Just check out our quick start guide, follow easy and straightforward instructions and start enjoying new cloud face detection and recognition API provider.

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.

Quick start guide

Follow these simple steps and you will start developing new applications or adding face detection and/or recognition to existing applications in no time:

  1. Explore our face detection and recognition capabilities on our API demo.
  2. Sign up or sign in to SkyBiometry.
  3. Create workspace/application(s) and choose authentication method for API access.
  4. Create data namespace(s), this is where your tagged faces will be stored.
  5. If you have been using face.com before, that is it – change service endpoint (to http://api.skybiometry.com/fc/), update API authentication keys in your application, create namespaces and you are ready to go. Otherwise continue with the next step – don’t worry, you are almost done.
  6. Start developing your application with the language of your choice. It is very simple to use the API in almost any programming language, as it is REST based. However, take a look at our API client libraries to give you a great boost in developing your application.
  7. If that is not enough, you can always explore our API reference.
  8. Start coding, don’t forget to tell us about your newly finished apps on our user voice page!

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

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

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

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

API usage 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.

API results

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

NameTypeValue
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.
uid string A matching user id for the group. Only works if the call provides a list of user ids, and an user id is matched with this group.
gid string The group id.
tids string A list of one or more tag ids. If the gid and uid fields are absent this means this is the ungrouped group. Those are all the faces that had no matching face, or faces that cannot be group at the moment (such as profile posed faces).
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.
url string Photo URL as specified in the request or temporary URL for image stream.
pid string Photo id, can be used as reference instead of URL for follow-up calls to methods that support it.
width integer Photo width in pixels.
height integer Photo height in pixels.
tagsarrayList of zero or more face tag objects found in the photo.
tagobjectThe face object found in a photo.
tidstringThe tag id. Tag ids are temporary until used in tags/save calls to associate the tag with a specific user id, at which point they become persistent.
recognizablebooleanValue indicating whether this tag that can be recognized or can be used for training set.
threshold integer The recommended confidence threshold from 0-100% to use when deciding which recognition results to display (faces/recognize only). The threshold changes based on the quality of faces found, as well as the size of the user ids list specified when calling faces/recognize.
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.
uidobjectA possible match for the face tag
uidstringThe user id match for the face tag.
confidenceintegerThe score from 0-100% interval.
gidstringThe group id.
labelstringOptional text label describing the tag. Must have been previously specified through a tags/add or tags/save call.
confirmed boolean Specifies whether a tag has been confirmed or is in a temporary state. Tags are confirmed through calls to tags/add or tags/save. Unconfirmed tags are also referred to as temporary, which means that they are not persisted anywhere. All confirmed tags have the confidence score of 100.
manualbooleanValue indicating whether the tag was added through the tags/add call which supports manual addition of otherwise undetected faces.
tagger_idstringThe tagging user id.
widthfloatFace tag width as 0-100% of photo width.
heightfloatFace tag height as 0-100% of photo height.
centerobjectCenter of face tag point. See point.
eye_leftobjectLeft eye point. See point.
eye_rightobjectRight eye point. See point.
mouth_leftobjectLeft edge of mouth point. See point.
mouth_rightobjectRight edge of mouth point. See point.
mouth_centerobjectMouth center point. See point.
noseobjectNose tip point. See point.
ear_leftobjectLeft ear point. See point.
ear_rightobjectRight ear point. See point.
chinobjectChin point. See point.
yawfloatYaw (facing sideways) angle value as -90 to 90.
rollfloatRoll (face rotation) angle value as -90 to 90.
pitchfloatPitch (up or down) angle value as -90 to 90.
attributesobjectList of determined facial attributes. See attributes.
pointsarrayList of detected facial feature points. Available only if detect_all_feature_points=true is specified in the request.
pointobjectDetected facial feature point.
xfloatThe X coordinate as 0-100% of photo width.
yfloatThe Y coordinate as 0-100% of photo height.
confidenceintegerThe confidence level of the point from 0-100% interval.
id integer The identifier of the point. Has the following format: 0xTTNN where TT is a point type (01 is MPEG-4, 02 is anthropometric and 03 is FG-NET) and NN is a point number linked to a specific point on the face.
similaritiesarrayList of similarities of this face tag with other face tags in request (faces/group only).
similarityobjectA similarity score of two faces tags.
tidstringThe tag id of the face matched with tag.
similarityintegerThe score from 0-100% interval.
error_codeintegerError code, specified only when an error occurs. See errors.
error_messagestringError message, specified only when an error occurs. See errors.
user_statusesarrayList of training statuses of the users (faces/status only).
user_statusobjectThe training status of the user.
uidstringThe user id that was trained.
training_set_sizeintegerThe number of photos used to train this model.
last_trainedintegerThe last UTC time value when this user id was trained.
training_in_progressbooleanValue indicating whether another train is running to the user id at the moment.
no_training_setarrayList of users that were not trained (faces/train only). See user_status.
createdarrayList of created users (faces/train only). See user_status.
updatedarrayList of updated users (faces/train only). See user_status.
unchangedarrayList of unchanged users (faces/train only). See user_status.
authenticatedbooleanValue specifying whether API usage is authenticated (account/authenticate only).
usersstring/string array mapList of namespaces along with list of users in each namespace (account/users only).
namespacesarrayList of namespaces (account/namespaces only).
namespacedataobjectThe object describing namespace.
namestringThe name of the namespace.
sizeintegerNumber of users in the namespace.
share_modestringShare mode of the namespace. Valid values are "Public", "Private" and "Public Read-Only".
ownerbooleanValue specifying whether the namespace in owned by the API user.
saved_tagsarrayList of saved tags (tags/save only).
saved_tagobjectThe object describing saved tag.
detected_tidstringDetected tag id.
tidstringTag id.
removed_tagsarrayList of removed tags (tags/remove only).
removed_tagobjectThe object describing removed tag.
removed_tidstringRemoved tag id.
tidstringTag id.
messagestringMessage from tag operation.
callback_urlstringThe callback URL specified in request.
statusstringStatus of the request. Valid values are "success", "partial" and "failure". See errors.
error_codeintegerError code, specified only when an error occurs. See errors.
error_messagestringError message, specified only when an error occurs. See errors.
usageobjectThe usage of the API. All rate limited methods and account/limits return this object.
usedintegerAmount of photos that were processed since last rate-limit reset time (1 hour, 1 day or 1 month depending on what limits are configured in the account).
remainingintegerAmount of photos remaining in current time window.
limitintegerThe total photos limit permitted in the current time window.
reset_timeintegerGMT Unix-timestamp of next limit reset time.
reset_time_textstringGMT Unix timestamp of next limit reset time (in text).
namespace_usedintegerAmount of trained user tags in the namespace(s).
namespace_remainingintegerAmount of remaining space for trained user tags in the namespace(s).
namespace_limitintegerThe maximum amount of trained user tags that can be stored in the namespace(s).
operation_idstringThe identifier of the operation that can be used when contacting our support.
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.

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 attributeResponse attributeValues
facetrue
gendergendermale, female
glassesglassestrue, false
glassesdark_glassestrue, false
smilingsmilingtrue, false
lipslipssealed, parted
eyeseyesopen, closed
ageage_est[estimated age in years]
moodmoodhappy, sad, angry, surprised, disgusted, scared, neutral
moodneutral_mood, anger, disgust, fear, happiness, sadness, surprisetrue, 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 glasses is 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.

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

API 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/training and 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.

API client 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 to http://api.skybiometry.com/fc/.

API reference

Select API method from the list below, if you want to see more information:

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
	}
}
			

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 uids parameter 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
	}
			

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 uids parameter 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
	}
}
			

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
	}
}
			

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
		}
	]
}
			

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
	}
}
			

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"
}
			

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

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"
}
			

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
}
			

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
	}
}
			

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
			}
		]
}
			

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"
		]
	}
}