REST API :: faces.recognize
Attempts to detect and recognize one or more user IDs' faces, in one or more photos. For each detected face, the face.com engine will return the most likely user IDs, or empty result for unrecognized faces. In addition, each tag includes a threshold score - any score below this number is considered a low-probability hit.
You can also save the recognized faces by calling tags.save with the returned temporary tag id (tid), along with the relevant user ID. Saving tags is also the way to train the platform how users look like, for later calls to faces.recognize.
The first step in recognition is face detection, which is applied automatically for each photo sent for recognition. Therefor these calls generally use the same tag output with the addition of recognized user IDs (see faces.detect for more details and usage notes).
In addition, when passing specific uids, (not special list as "friends" and "all"), we will return a list of uids that have no train set, and there for cannot be recognized, under "no_training_set" list.
Photos can also be uploaded directly in the API request. A requests that uploads a photo must be formed as a MIME multi-part message sent using POST data. Each argument, including the raw image data, should be specified as a separate chunk of form data. (An example below)
For more information on training and using the face recognition engine, check out Recognition How-To.
rate limiting (info):
This API is rate limited. Each passed photo or photo URL is added to your usage.
url:
http://api.face.com/faces/recognize.format
parameters:
in
| Required | Name | Description |
|---|---|---|
| Required | api_key | your face.com API Key |
| api_secret | your face.com API Secret | |
| uids | a comma separated list of user IDs to search for in the photos passed in the request | |
| urls | a comma separated list of JPG photos | |
| Optional | [no name] | The raw image data for the photo (when instead of url, an image is uploaded) |
| namespace | a default user namespace to be used for all users specified in the short-hand syntax (just the user ID, without the '@namespace') | |
| detector | Set the face detector work mode: Normal (default) or Aggressive. Aggressive mode may find a bit more faces, and is also slower. Usage of this detector counts as two Normal detections | |
| attributes | Can be all, none or a list of specific comma-separated attributes (see list of available attributes on the return values page. Unless specified, it returns the default 3 attributes of gender, glasses and smiling. The face attribute, marking whether there's a face present is always returned. | |
| format | ‘json’ (default) or ‘xml’ | |
| callback | javascript method to wrap a json-formatted response (for JSONP support, ignored if format=xml) | |
| callback_url | asynchronously invoke the method, and POST the response to the specified url. Suitable for calling lengthy operations. Reponse 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. | |
| user_auth | signed-in facebook or twitter user credentials. Required only when specifying UIDsin these namespaces. Use name:value pairs, separated by comma:
|
example:
http://api.face.com/faces/recognize.json?api_key=4b4b4c6d54c37&api_secret=&urls=http://farm3.static.flickr.com/2527/3942842476_33341616f2_b.jpg&uids=friends@facebook.com&user_auth=fb_user:571756321,fb_session:
post example: (post to http://api.face.com/faces/recognize.json)
Content-Type: multipart/form-data; boundary=nonRelevantString Content-Length: 104687 -----------------------------nonRelevantString Content-Disposition: form-data; name="api_key" 4b4b4c6d54c37 -----------------------------nonRelevantString Content-Disposition: form-data; name="api_secret" sfhs8fj948fj29 -----------------------------nonRelevantString Content-Disposition: form-data; name="uids" friends@facebook.com -----------------------------nonRelevantString Content-Disposition: form-data; name="fb_user" 571756321 -----------------------------nonRelevantString Content-Disposition: form-data; name="fb_session" 571756321XXXX -----------------------------nonRelevantString Content-Disposition: form-data; filename="image.jpg" Content-Type: image/jpeg <<Raw Image Data Here>> -----------------------------nonRelevantString--
response sample (json):
View complete list of response fields
{
no_training_set: [
"345252654@facebook.com",
"3123414633634@facebook.com"
]
photos: [
{
url: "http://farm3.static.flickr.com/2527/3942842476_33341616f2_b.jpg",
pid: "F@2f9d1c8f44d03e82367d7d8737556342_4b4b4c6d54c37",
width: 1024,
height: 680,
tags: [
{
tid: "TEMP_F@2f9d1c8f44d03e82367d7d8737556342_4b4b4c6d54c37_44.53_42.06_2",
threshold: 60,
uids: [
{
uid: "571756321@facebook.com",
confidence: 97
},
{
uid: "812697177@facebook.com",
confidence: 23
},
{
uid: "749410444@facebook.com",
confidence: 21
},
...
],
label: "",
confirmed: false,
manual: false,
width: 6.84,
height: 10.29,
center: {
x: 44.53,
y: 42.06
},
eye_left: {
x: 43.38,
y: 40.84
},
eye_right: {
x: 45.77,
y: 40.97
},
mouth_left: {
x: 43.42,
y: 44.74
},
mouth_center: {
x: 44.74,
y: 45.23
},
mouth_right: {
x: 45.78,
y: 44.7
},
nose: {
x: 45.15,
y: 43.42
},
yaw: 42.48,
roll: 2.07,
pitch: -3.71,
attributes: {
gender: {
value: "male",
confidence: 34
},
glasses: {
value: "false",
confidence: 95
},
smiling: {
value: "true",
confidence: 61
}
}
}
]
}
],
status: "success",
usage: {
used: 1,
remaining: 199,
limit: 200,
reset_time_text: "Wed, 03 Mar 2010 13:46:40 +0000",
reset_time: "1267624000"
}
}