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
| Name | Type | Value |
|---|---|---|
| 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. |
| tags | array | List of zero or more face tag objects found in the photo. |
| tag | object | The face object found in a photo. |
| tid | string | The 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. |
| recognizable | boolean | Value 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. |
| uid | object | A possible match for the face tag |
| uid | string | The user id match for the face tag. |
| confidence | integer | The score from 0-100% interval. |
| gid | string | The group id. |
| label | string | Optional text label describing the tag. Must have been previously specified through a tags/add ortags/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. |
| manual | boolean | Value indicating whether the tag was added through the tags/add call which supports manual addition of otherwise undetected faces. |
| tagger_id | string | The tagging user id. |
| width | float | Face tag width as 0-100% of photo width. |
| height | float | Face tag height as 0-100% of photo height. |
| center | object | Center of face tag point. See point. |
| eye_left | object | Left eye point. See point. |
| eye_right | object | Right eye point. See point. |
| mouth_left | object | Left edge of mouth point. See point. |
| mouth_right | object | Right edge of mouth point. See point. |
| mouth_center | object | Mouth center point. See point. |
| nose | object | Nose tip point. See point. |
| ear_left | object | Left ear point. See point. |
| ear_right | object | Right ear point. See point. |
| chin | object | Chin point. See point. |
| yaw | float | Yaw (facing sideways) angle value as -90 to 90. |
| roll | float | Roll (face rotation) angle value as -90 to 90. |
| pitch | float | Pitch (up or down) angle value as -90 to 90. |
| attributes | object | List of determined facial attributes. See attributes. |
| points | array | List of detected facial feature points. Available only if detect_all_feature_points=true is specified in the request. |
| point | object | Detected facial feature point. |
| x | float | The X coordinate as 0-100% of photo width. |
| y | float | The Y coordinate as 0-100% of photo height. |
| confidence | integer | The 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. |
| similarities | array | List of similarities of this face tag with other face tags in request (faces/group only). |
| similarity | object | A similarity score of two faces tags. |
| tid | string | The tag id of the face matched with tag. |
| similarity | integer | The score from 0-100% interval. |
| error_code | integer | Error code, specified only when an error occurs. See errors. |
| error_message | string | Error message, specified only when an error occurs. See errors. |
| user_statuses | array | List of training statuses of the users (faces/status only). |
| user_status | object | The training status of the user. |
| uid | string | The user id that was trained. |
| training_set_size | integer | The number of photos used to train this model. |
| last_trained | integer | The last UTC time value when this user id was trained. |
| training_in_progress | boolean | Value indicating whether another train is running to the user id at the moment. |
| no_training_set | array | List of users that were not trained (faces/train only). See user_status. |
| created | array | List of created users (faces/train only). See user_status. |
| updated | array | List of updated users (faces/train only). See user_status. |
| unchanged | array | List of unchanged users (faces/train only). See user_status. |
| authenticated | boolean | Value specifying whether API usage is authenticated (account/authenticate only). |
| users | string/string array map | List of namespaces along with list of users in each namespace (account/users only). |
| namespaces | array | List of namespaces (account/namespaces only). |
| namespacedata | object | The object describing namespace. |
| name | string | The name of the namespace. |
| size | integer | Number of users in the namespace. |
| share_mode | string | Share mode of the namespace. Valid values are “Public”, “Private” and “Public Read-Only”. |
| owner | boolean | Value specifying whether the namespace in owned by the API user. |
| saved_tags | array | List of saved tags (tags/save only). |
| saved_tag | object | The object describing saved tag. |
| detected_tid | string | Detected tag id. |
| tid | string | Tag id. |
| removed_tags | array | List of removed tags (tags/remove only). |
| removed_tag | object | The object describing removed tag. |
| removed_tid | string | Removed tag id. |
| tid | string | Tag id. |
| message | string | Message from tag operation. |
| callback_url | string | The callback URL specified in request. |
| status | string | Status of the request. Valid values are “success”, “partial” and “failure”. See errors. |
| error_code | integer | Error code, specified only when an error occurs. See errors. |
| error_message | string | Error message, specified only when an error occurs. See errors. |
| usage | object | The usage of the API. All rate limited methods and account/limits return this object. |
| used | integer | Amount 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). |
| remaining | integer | Amount of photos remaining in current time window. |
| limit | integer | The total photos limit permitted in the current time window. |
| reset_time | integer | GMT Unix-timestamp of next limit reset time. |
| reset_time_text | string | GMT Unix timestamp of next limit reset time (in text). |
| namespace_used | integer | Amount of trained user tags in the namespace(s). |
| namespace_remaining | integer | Amount of remaining space for trained user tags in the namespace(s). |
| namespace_limit | integer | The maximum amount of trained user tags that can be stored in the namespace(s). |
| operation_id | string | The 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.
