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 classifications 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. Classification 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:

Explore our face detection and recognition capabilities on our API demo.
Sign up or sign in to SkyBiometry.
Create workspace/application(s) and choose authentication method for API access.
Create data namespace(s), this is where your tagged faces will be stored.
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.
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.
If that is not enough, you can always explore our API reference.
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 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):

faces/detect – detects faces in specified images, returns face tags (every tag has unique tag id - tid).
tags/save – saves specified face tags (by tid) with user specified user id(eg. mark@docs, where docs - data namespace name).
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 package can be used to add precompiled SkyBiometry client library through NuGet package manager in VisualStudio 2010 and 2012. 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# client library source code (version 1.1.6, last updated on 14 May 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 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 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.
: 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 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.
: 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.
: 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.
: 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

if something goes wrong

In case any method of the API fails, an API error object is returned:

{
	"error_code" : 401,
	"status" : "failure",
	"error_message" : "UNKNOWN_REST_METHOD",
	"operation_id" : "46f3e40fd64943d8bf4f9ba874816d5d"
}

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

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

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 (currently supported attributes are gender, glasses and smiling, with more to be added in the future). 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.

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

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.

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 (currently supported attributes are gender, glasses and smiling, with more to be added in the future). 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.
limit – specifies maximum number of matches that will be returned with the results. If not specified value of 100 will be used.

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 (currently supported attributes are gender, glasses and smiling, with more to be added in the future). 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.
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.

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

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:

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

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:

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

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:

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

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:

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

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

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

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

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

example:

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

response:

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