REST API :: faces.group
Attempts to detect, group, and optionally recognize one or more user IDs' faces, in one or more photos. This method is particularly useful for supporting 'bulk tagging' in albums, as demonstrated in our Photo Tagger application for Facebook. Grouping works by attempting to match all the faces found in the URLs list one to the other, and assign a group ID for all detected faces that appear to be of the same person.
When user IDs are specified, the this method adds recognition functionality on top of grouping, and the face.com engine will also attempt to assign the most likely user ID for each detected face (or group of 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.
See faces.recognize for explanation and tips for performing recognition.
The response contains two parts: groups and photos. Each group contains the tids that belong to the group, a gid which is the index of the group, and a uid in case the group has recognition. The photos contains the photo details and the tags. The tids in the groups refer to those tags, and can be match according to the tid. More details in Return Values.
If the gid=null and the uid=null, it means that this is the ungrouped group. This is the group where are all the faces that had no matching face, or faces that cannot be group at the moment (such as profile posed faces).
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)
Note: Although this accepts a single URL as input as well, it will only group faces when multiple URLs or Photos are provided. If the same face is found multiple times in the same photo, it will not be grouped together.
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/group.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/group.json?api_key=4b4b4c6d54c37&api_secret= &urls=http://farm4.static.flickr.com/3200/2423492381_624f2e91eb_z.jpg,http://farm4.static.flickr.com/3354/3311347105_8a97ab02b0_z.jpg&detector=Aggressive
post example: (post to http://api.face.com/faces/group.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" aaaaaaaaaaaaaa -----------------------------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
<pre>{
groups: [
{
uid: null,
gid: 1,
tids: [
"TEMP_F@049ba86597359f7640d4e82e0004b973_4b4b4c6d54c37_40.21_40.16_2",
"TEMP_F@4de7d3186eba732058f832df4d5ea365_4b4b4c6d54c37_63.52_48.13_2"
]
},
{
uid: null,
gid: null,
tids: [
"TEMP_F@049ba86597359f7640d4e82e0004b973_4b4b4c6d54c37_91.46_37.66_2"
]
}
],
photos: [
{
url: "http://farm4.static.flickr.com/3200/2423492381_624f2e91eb_z.jpg",
pid: "F@049ba86597359f7640d4e82e0004b973_4b4b4c6d54c37",
width: 480,
height: 640,
tags: [
{
tid: "TEMP_F@049ba86597359f7640d4e82e0004b973_4b4b4c6d54c37_40.21_40.16_2",
threshold: null,
uids: [ ],
gid: 1,
label: "",
confirmed: false,
manual: false,
tagger_id: null,
width: 19.17,
height: 14.38,
center: {
x: 40.21,
y: 40.16
},
eye_left: {
x: 35.91,
y: 36.98
},
eye_right: {
x: 43.92,
y: 36.52
},
mouth_left: {
x: 37,
y: 43.33
},
mouth_center: {
x: 40.38,
y: 43.57
},
mouth_right: {
x: 44.58,
y: 42.86
},
nose: {
x: 39.61,
y: 40.21
},
ear_left: null,
ear_right: null,
chin: null,
yaw: -7.54,
roll: -4.31,
pitch: 5.69,
attributes: {
face: {
value: "true",
confidence: 96
},
gender: {
value: "male",
confidence: 94
},
glasses: {
value: "false",
confidence: 54
},
smiling: {
value: "true",
confidence: 49
}
}
},
{
tid: "TEMP_F@049ba86597359f7640d4e82e0004b973_4b4b4c6d54c37_91.46_37.66_2",
threshold: null,
uids: [ ],
gid: null,
label: "",
confirmed: false,
manual: false,
tagger_id: null,
width: 5,
height: 3.75,
center: {
x: 91.46,
y: 37.66
},
eye_left: {
x: 91.44,
y: 36.64
},
eye_right: {
x: 93.06,
y: 37.39
},
mouth_left: {
x: 90.32,
y: 38.19
},
mouth_center: {
x: 90.86,
y: 38.45
},
mouth_right: {
x: 91.36,
y: 38.69
},
nose: {
x: 91.84,
y: 38.13
},
ear_left: null,
ear_right: null,
chin: null,
yaw: 39.98,
roll: 31.76,
pitch: 0.74,
attributes: {
face: {
value: "true",
confidence: 80
},
gender: {
value: "male",
confidence: 67
},
glasses: {
value: "false",
confidence: 97
},
smiling: {
value: "false",
confidence: 65
}
}
}
]
},
{
url: "http://farm4.static.flickr.com/3354/3311347105_8a97ab02b0_z.jpg",
pid: "F@4de7d3186eba732058f832df4d5ea365_4b4b4c6d54c37",
width: 640,
height: 427,
tags: [
{
tid: "TEMP_F@4de7d3186eba732058f832df4d5ea365_4b4b4c6d54c37_63.52_48.13_2",
threshold: null,
uids: [ ],
gid: 1,
label: "",
confirmed: false,
manual: false,
tagger_id: null,
width: 24.53,
height: 36.77,
center: {
x: 63.52,
y: 48.13
},
eye_left: {
x: 57.87,
y: 40.75
},
eye_right: {
x: 67.01,
y: 38.13
},
mouth_left: {
x: 61.01,
y: 56.56
},
mouth_center: {
x: 64.64,
y: 56.6
},
mouth_right: {
x: 68.69,
y: 54.67
},
nose: {
x: 61.16,
y: 49.89
},
ear_left: null,
ear_right: null,
chin: null,
yaw: -35.58,
roll: -10.81,
pitch: 0.94,
attributes: {
face: {
value: "true",
confidence: 95
},
gender: {
value: "male",
confidence: 93
},
glasses: {
value: "false",
confidence: 98
},
smiling: {
value: "true",
confidence: 51
}
}
}
]
}
],
status: "success"
}</pre>