/recognition/identify

Description

Find the most similar persons within a group for each query face in a list (or in an image).
The group should be re-trained when ever modified (see /train/identify ), otherwise some persons may fail to appear in the result.

Parameter

Name Description
Required api_key Your registered API Key
api_secret Your registered API Secret
group_id or group_name The group of candidate persons for recognition
Optional url or img Url of the image containing the faces to be identifyd, or the binary data of the image uploaded via POST
mode The detector mode, one of normal(default) or oneface. In oneface mode, only the largest face in the image would be found. This option is only used if url or img is given.
key_face_id User can also specify a list of faces to be identifyd rather than given an image by specifiy parameter key_face_id (a comma-separated list specifying the ids of faces to be identifyd)
async If set to true, the API would be invoked asynchronously (i.e. a session id would be returned immediately, which could be later used to retrieve the result via /info/get_session). Defaults to false.

Return Values

Field Type Description
candidate array The recognition results. The candidate list contains no more than 3 Person, with the information of the Person and correspoding confidences.
session_id string Unique id of a session
url string Image url as specified in the request
img_id string Unique id of an image on Face++ platform
face_id string Unique id of a detected Face on Face++ platform
img_width integer Image width in pixels
img_height integer Image height in pixels
faces array A list of detected faces, each element is a description of Face
width float The width of detected face (as 0-100% of image width)
height float The height of detected face (as 0-100% of image width)
center object x & y coordinates of the center point of the detected face rectangle, as 0-100% of photo width and height
nose object x & y coordinates of nose, as 0-100% of photo width and height
eye_left object x & y coordinates of left eye, as 0-100% of photo width and height
eye_right object x & y coordinates of right eye, as 0-100% of photo width and height
mouth_left object x & y coordinates of left edge of mouth, as 0-100% of photo width and height
mouth_right object x & y coordinates of right edge of mouth, as 0-100% of photo width and height

Parameter

https://apius.faceplusplus.com/v2/recognition/identify?url=http%3A%2F%2Ffaceplusplus.com%2Fstatic%2Fimg%2Fdemo%2F1.jpg&api_secret=YOUR_API_SECRET&api_key=YOUR_API_KEY&group_name=DemoGroup

JSON Response

{
    "face": [
    {
        "candidate": [
        {
            "confidence": 94.299985,
            "person_id": "c1e580c0665f6ed11d510fe4d194b37a",
            "person_name": "1",
			"tag":""
        },
        {
            "confidence": 43.930084,
            "person_id": "f5898c65a44771103166c77a8ebdfa37",
            "person_name": "2",
			"tag":""
        },
        {
            "confidence": 29.234959,
            "person_id": "30b512232c5444779ce0bf5310a44e73",
            "person_name": "3",
			"tag":""
        }
        ],
        "face_id": "8400814bbd13953db0376e459f54acff",
        "position": {
            "center": {
                "x": 46.965699,
                "y": 18.666667
            },
            "eye_left": {
                "x": 41.424802,
                "y": 16.5
            },
            "eye_right": {
                "x": 49.868074,
                "y": 15.833333
            },
            "height": 11.0,
            "mouth_left": {
                "x": 42.216359,
                "y": 21.666667
            },
            "mouth_right": {
                "x": 51.71504,
                "y": 21.333333
            },
            "nose": {
            	"x": 49.863172, 
            	"y": 39.325091
            },
            "width": 17.414248
        }
    }
    ],
    "session_id": "baef0ddb31e6af235a29b9c636a2884d-1765bbe4-1957-4257-b2a8-f2b2cfc4bef5"
}

Error Code List

Error Code HTTP Status Code Error Message
1001 500 INTERNAL_ERROR
1003 403 AUTHORIZATION_ERROR
1003 403 INSUFFICIENT_PRIVILEGE_OR_QUOTA_LIMIT_EXCEEDED
1004 400 MISSING_ARGUMENTS
1005 400 INVALID_ARGUMENTS
1006 403 ILLEGAL_USE_OF_DEMO_KEY
1202 502 SERVER_TOO_BUSY
1301 431 IMAGE_ERROR_UNSUPPORTED_FORMAT
1302 432 IMAGE_ERROR_FAILED_TO_DOWNLOAD
1303 433 IMAGE_ERROR_FILE_TOO_LARGE
1304 434 IMAGE_ERROR
1401 441 OBJECT_UNTRAINED
Google+