/detection/detect

描述

检测给定图片(Image)中的所有人脸(Face)的位置和相应的面部属性

  • 目前面部属性包括性别(gender), 年龄(age), 种族(race), 微笑程度(smiling), 眼镜(glass)和姿势(pose)
若结果的face_id没有被加入任何faceset/person之中,则在72小时之后过期被自动清除。

参数

 参数名参数说明
必须 api_key App的Face++ API Key
  api_secret APP的Face++ API Secret
  url 或 img[POST] 待检测图片的URL 或者 通过POST方法上传的二进制数据,原始图片大小需要小于1M
可选 mode 检测模式可以是normal(默认) 或者 oneface 。在oneface模式中,检测器仅找出图片中最大的一张脸。
  attribute 可以是none或者由逗号分割的属性列表。默认为gender, age, race, smiling。目前支持的属性包括:gender, age, race, smiling, glass, pose
  tag 可以为图片中检测出的每一张Face指定一个不包含^@,&=*'"等非法字符且不超过255字节的字符串作为tag,tag信息可以通过 /info/get_face 查询
  async 如果置为true,该API将会以异步方式被调用;也就是立即返回一个session id,稍后可通过/info/get_session查询结果。默认值为false。

返回值说明

字段类型说明
session_id string 相应请求的session标识符,可用于结果查询
url string 请求中图片的url
img_id string Face++系统中的图片标识符,用于标识用户请求中的图片
face_id string 被检测出的每一张人脸都在Face++系统中的标识符
img_width integer 请求图片的宽度
img_height integer 请求图片的高度
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之间的实数)
attribute object 包含一系列人脸的属性分析结果
gender object 包含性别分析结果,value的值为Male/Female, confidence表示置信度
age object 包含年龄分析结果,value的值为一个非负整数表示估计的年龄, range表示估计年龄的正负区间
race object 包含人种分析结果,value的值为Asian/White/Black, confidence表示置信度
smiling object

包含微笑程度分析结果,value的值为0-100的实数,越大表示微笑程度越高

glass object

包含眼镜佩戴分析结果,value的值为None/Dark/Normal, confidence表示置信度

pose object

包含脸部姿势分析结果,包括pitch_angle, roll_angle, yaw_angle,分别对应抬头,旋转(平面旋转),摇头。单位为角度。

调用示例

http://apicn.faceplusplus.com/v2/detection/detect?api_key=YOUR_API_KEY&api_secret=YOUR_API_SECRET&url=http%3A%2F%2Ffaceplusplus.com%2Fstatic%2Fimg%2Fdemo%2F1.jpg&attribute=glass,pose,gender,age,race,smiling

JSON 示例

{
    "face": [
        {
            "attribute": {
                "age": {
                    "range": 5, 
                    "value": 23
                }, 
                "gender": {
                    "confidence": 99.9999, 
                    "value": "Female"
                }, 
                "glass": {
                    "confidence": 99.945, 
                    "value": "None"
                }, 
                "pose": {
                    "pitch_angle": {
                        "value": 17
                    }, 
                    "roll_angle": {
                        "value": 0.735735
                    }, 
                    "yaw_angle": {
                        "value": -2
                    }
                }, 
                "race": {
                    "confidence": 99.6121, 
                    "value": "Asian"
                }, 
                "smiling": {
                    "value": 4.86501
                }
            }, 
            "face_id": "17233b4b1b51ac91e391e5afe130eb78", 
            "position": {
                "center": {
                    "x": 49.4, 
                    "y": 37.6
                }, 
                "eye_left": {
                    "x": 43.3692, 
                    "y": 30.8192
                }, 
                "eye_right": {
                    "x": 56.5606, 
                    "y": 30.9886
                }, 
                "height": 26.8, 
                "mouth_left": {
                    "x": 46.1326, 
                    "y": 44.9468
                }, 
                "mouth_right": {
                    "x": 54.2592, 
                    "y": 44.6282
                }, 
                "nose": {
                    "x": 49.9404, 
                    "y": 38.8484
                }, 
                "width": 26.8
            }, 
            "tag": ""
        }
    ], 
    "img_height": 500, 
    "img_id": "22fd9efc64c87e00224c33dd8718eec7", 
    "img_width": 500, 
    "session_id": "38047ad0f0b34c7e8c6efb6ba39ed355", 
    "url": "http://www.faceplusplus.com.cn/wp-content/themes/faceplusplus/assets/img/demo/1.jpg?v=4"
}

错误列表

错误代码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
1502 452 BAD_TAG