/recognition/identify

描述

对于一个待查询的Face列表(或者对于给定的Image中所有的Face),在一个Group中查询最相似的Person。

注意,当Group中的信息被修改之后(增加了Person, Face等),为了保证结果与最新数据一致,Group应当被重新train. 见/train/identify 。否则调用此API时将使用最后一次train时的数据。

参数

  参数名 参数说明
必须 api_key App的Face++ API Key
  api_secret APP的Face++ API Secret
  group_id 或 group_name 识别候选人组成的Group
可选 url 或 img 待识别图片的URL 或者 通过POST方法上传的二进制数据
  mode 检测模式可以是normal(默认) 或者 oneface 。在oneface模式中,检测器仅找出图片中最大的一张脸。仅当给出了url或img时,本选项有效。
  key_face_id 开发者也可以指定一个face_id的列表来表明对这些face进行识别。可以设置此参数key_face_id为一个逗号隔开的face_id列表。
  async 如果置为true,该API将会以异步方式被调用;也就是立即返回一个session id,稍后可通过/info/get_session查询结果。默认值为false。

返回值说明

字段 类型 说明
candidate array 识别结果。candidate包含不超过3个人,包含相应person信息与相应的置信度
session_id string 相应请求的session标识符,可用于结果查询
url string 请求中图片的url
img_id string Face++系统中的图片标识符,用于标识用户请求中的图片
face_id string 被检测出的每一张人脸都在Face++系统中的标识符
face array 人脸的列表
width float 0~100之间的实数,表示检出的脸的宽度在图片中百分比
height float 0~100之间的实数,表示检出的脸的高度在图片中百分比
center object 检出的人脸框的中心点坐标, x & y 坐标分别表示在图片中的宽度和高度的百分比 (0~100之间的实数)
eye_left object 相应人脸的左眼坐标,x & y 坐标分别表示在图片中的宽度和高度的百分比 (0~100之间的实数)
eye_right object 相应人脸的右眼坐标,x & y 坐标分别表示在图片中的宽度和高度的百分比 (0~100之间的实数)
mouth_left object 相应人脸的左侧嘴角坐标,x & y 坐标分别表示在图片中的宽度和高度的百分比 (0~100之间的实数)
mouth_right object 相应人脸的右侧嘴角坐标,x & y 坐标分别表示在图片中的宽度和高度的百分比 (0~100之间的实数)
nose object 相应人脸的鼻尖坐标,x & y 坐标分别表示在图片中的宽度和高度的百分比 (0~100之间的实数)

调用示例

https://apicn.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 示例

{
    "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"
}

错误列表

错误代码 HTTP 状态代码 错误信息
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