首页 > 文档中心

人脸检测与分析

接口能力

接口名称接口描述API地址
人脸检测与分析识别上传图像上面的人脸信息https://api.ai.qq.com/fcgi-bin/face/face_detectface

更多更强大的接口能力正在开发中,并逐步开放,敬请期待!

协议须知

调用方集成人脸检测与分析API时,请遵循以下规则。

规则描述
传输方式HTTPS
请求方法POST
字符编码统一采用UTF-8编码
响应格式统一采用JSON格式
接口鉴权签名机制

人脸检测与分析接口

1. 接口描述

检测给定图片(Image)中的所有人脸(Face)的位置和相应的面部属性。位置包括(x, y, w, h),面部属性包括性别(gender), 年龄(age), 表情(expression), 魅力(beauty), 眼镜(glass)和姿态(pitch,roll,yaw)。

2. 请求参数

参数名称是否必选数据类型数据约束示例数据描述
app_idint正整数1000001应用标识(AppId)
time_stampint正整数1493468759请求时间戳(秒级)
nonce_strstring非空且长度上限32字节fa577ce340859f9fe随机字符串
signstring非空且长度固定32字节B250148B284956EC5218D4B0503E7F8A签名信息
imagestring原始图片的base64编码数据(原图大小上限1MB,支持JPG、PNG、BMP格式)...待识别图片
modeint整数0/1检测模式,0-正常,1-大脸模式(默认1)

3. 响应参数

参数名称是否必选数据类型描述
retint返回码; 0表示成功,非0表示出错
msgstring返回信息;ret非0时表示出错时错误原因
dataobject返回数据;ret为0时有意义
+ image_widthint请求图片的宽度
+ image_heightint请求图片的高度
+ face_listarray被检测出的人脸列表
+ + face_idstring人脸(Face)ID
+ + xint人脸框左上角x
+ + yint人脸框左上角y
+ + widthint人脸框宽度
+ + heightint人脸框高度
+ + genderint性别 [0~100](越接近0越倾向为女性,越接近100越倾向为男性)
+ + ageint年龄 [0~100]
+ + expressionint微笑[0~100] (0-没有笑容,50-微笑,100-大笑)
+ + beautyint魅力 [0~100]
+ + glassint是否有眼镜 [0, 1]
+ + pitchint上下偏移[-30,30]
+ + yawint左右偏移[-30,30]
+ + rollint平面旋转[-180,180]
+ + face_shapeobject人脸配准坐标

face_shape 说明

字段类型说明
face_profilearray描述脸型轮廓的21点(每点为一个对象{x, y})
left_eyearray描述左眼轮廓的8点(每点为一个对象{x, y})
right_eyearray描述右眼轮廓的8点(每点为一个对象{x, y})
left_eyebrowarray描述左眉轮廓的8点(每点为一个对象{x, y})
right_eyebrowarray描述右眉轮廓的8点(每点为一个对象{x, y})
moutharray描述嘴巴轮廓的22点(每点为一个对象{x, y})
nosearray描述鼻子轮廓的13点(每点为一个对象{x, y})

4. 参考示例

假设示例请求数据如下。

参数名称参数数据描述
app_id1000001仅供参考
image
实时计算base64
mode0仅供参考
time_stamp
实时计算
nonce_str
实时计算
sign
实时计算

假设应用密钥为:a95eceb1ac8c24ee28b70f7dbba912bf,示例图片文件存储路径为:/path/to/image

下面使用PHP实现该HTTP API调用,其中getReqSigndoHttpPost可以从接口鉴权获取。

// 图片base64编码
$path   = '/path/to/image';
$data   = file_get_contents($path);
$base64 = base64_encode($data);

// 设置请求数据
$appkey = 'a95eceb1ac8c24ee28b70f7dbba912bf';
$params = array(
    'app_id'     => '1000001',
    'image'      => $base64,
    'mode'       => '0',
    'time_stamp' => strval(time()),
    'nonce_str'  => strval(rand()),
    'sign'       => '',
);
$params['sign'] = getReqSign($params, $appkey);

// 执行API调用
$url = 'https://api.ai.qq.com/fcgi-bin/face/face_detectface';
$response = doHttpPost($url, $params);
echo $response;

上述echo $response的输出结果即API的响应结果(注意使用UTF-8编码):

{
    "ret": 0,
    "msg": "ok",
    "data": {
        "image_width": 590,
        "image_height": 352,
        "face_list": [
            {
                "face_id": "2214385550143548003",
                "x": 374,
                "y": 179,
                "width": 70,
                "height": 70,
                "gender": 22,
                "age": 26,
                "expression": 58,
                "beauty": 100,
                "glass": 0,
                "pitch": 18,
                "yaw": 4294967283,
                "roll": 13,
                "face_shape": {
                    "face_profile": [
                        {
                            "x": 380,
                            "y": 207
                        },
                        {
                            "x": 381,
                            "y": 214
                        },
                        {
                            "x": 383,
                            "y": 220
                        },
                        {
                            "x": 386,
                            "y": 226
                        },
                        {
                            "x": 390,
                            "y": 232
                        },
                        {
                            "x": 394,
                            "y": 237
                        },
                        {
                            "x": 398,
                            "y": 242
                        },
                        {
                            "x": 403,
                            "y": 247
                        },
                        {
                            "x": 408,
                            "y": 252
                        },
                        {
                            "x": 413,
                            "y": 256
                        },
                        {
                            "x": 419,
                            "y": 257
                        },
                        {
                            "x": 427,
                            "y": 255
                        },
                        {
                            "x": 433,
                            "y": 250
                        },
                        {
                            "x": 438,
                            "y": 244
                        },
                        {
                            "x": 442,
                            "y": 238
                        },
                        {
                            "x": 446,
                            "y": 231
                        },
                        {
                            "x": 448,
                            "y": 223
                        },
                        {
                            "x": 449,
                            "y": 215
                        },
                        {
                            "x": 448,
                            "y": 207
                        },
                        {
                            "x": 447,
                            "y": 200
                        },
                        {
                            "x": 446,
                            "y": 193
                        }
                    ],
                    "left_eye": [
                        {
                            "x": 387,
                            "y": 206
                        },
                        {
                            "x": 389,
                            "y": 207
                        },
                        {
                            "x": 392,
                            "y": 207
                        },
                        {
                            "x": 395,
                            "y": 206
                        },
                        {
                            "x": 398,
                            "y": 205
                        },
                        {
                            "x": 395,
                            "y": 203
                        },
                        {
                            "x": 392,
                            "y": 203
                        },
                        {
                            "x": 389,
                            "y": 204
                        }
                    ],
                    "right_eye": [
                        {
                            "x": 426,
                            "y": 198
                        },
                        {
                            "x": 424,
                            "y": 199
                        },
                        {
                            "x": 421,
                            "y": 201
                        },
                        {
                            "x": 418,
                            "y": 201
                        },
                        {
                            "x": 415,
                            "y": 201
                        },
                        {
                            "x": 417,
                            "y": 198
                        },
                        {
                            "x": 420,
                            "y": 197
                        },
                        {
                            "x": 423,
                            "y": 197
                        }
                    ],
                    "left_eyebrow": [
                        {
                            "x": 380,
                            "y": 199
                        },
                        {
                            "x": 384,
                            "y": 198
                        },
                        {
                            "x": 388,
                            "y": 198
                        },
                        {
                            "x": 392,
                            "y": 199
                        },
                        {
                            "x": 396,
                            "y": 198
                        },
                        {
                            "x": 393,
                            "y": 196
                        },
                        {
                            "x": 388,
                            "y": 196
                        },
                        {
                            "x": 383,
                            "y": 196
                        }
                    ],
                    "right_eyebrow": [
                        {
                            "x": 430,
                            "y": 188
                        },
                        {
                            "x": 425,
                            "y": 190
                        },
                        {
                            "x": 419,
                            "y": 192
                        },
                        {
                            "x": 414,
                            "y": 194
                        },
                        {
                            "x": 409,
                            "y": 196
                        },
                        {
                            "x": 412,
                            "y": 191
                        },
                        {
                            "x": 418,
                            "y": 188
                        },
                        {
                            "x": 424,
                            "y": 187
                        }
                    ],
                    "mouth": [
                        {
                            "x": 402,
                            "y": 235
                        },
                        {
                            "x": 405,
                            "y": 239
                        },
                        {
                            "x": 409,
                            "y": 242
                        },
                        {
                            "x": 414,
                            "y": 242
                        },
                        {
                            "x": 419,
                            "y": 240
                        },
                        {
                            "x": 423,
                            "y": 237
                        },
                        {
                            "x": 426,
                            "y": 232
                        },
                        {
                            "x": 421,
                            "y": 232
                        },
                        {
                            "x": 415,
                            "y": 232
                        },
                        {
                            "x": 411,
                            "y": 233
                        },
                        {
                            "x": 409,
                            "y": 233
                        },
                        {
                            "x": 405,
                            "y": 234
                        },
                        {
                            "x": 405,
                            "y": 237
                        },
                        {
                            "x": 409,
                            "y": 238
                        },
                        {
                            "x": 413,
                            "y": 238
                        },
                        {
                            "x": 418,
                            "y": 237
                        },
                        {
                            "x": 422,
                            "y": 235
                        },
                        {
                            "x": 422,
                            "y": 233
                        },
                        {
                            "x": 417,
                            "y": 234
                        },
                        {
                            "x": 412,
                            "y": 235
                        },
                        {
                            "x": 409,
                            "y": 235
                        },
                        {
                            "x": 405,
                            "y": 235
                        }
                    ],
                    "nose": [
                        {
                            "x": 406,
                            "y": 224
                        },
                        {
                            "x": 405,
                            "y": 204
                        },
                        {
                            "x": 404,
                            "y": 210
                        },
                        {
                            "x": 403,
                            "y": 215
                        },
                        {
                            "x": 401,
                            "y": 220
                        },
                        {
                            "x": 400,
                            "y": 225
                        },
                        {
                            "x": 404,
                            "y": 228
                        },
                        {
                            "x": 409,
                            "y": 228
                        },
                        {
                            "x": 414,
                            "y": 226
                        },
                        {
                            "x": 419,
                            "y": 221
                        },
                        {
                            "x": 415,
                            "y": 217
                        },
                        {
                            "x": 411,
                            "y": 213
                        },
                        {
                            "x": 408,
                            "y": 209
                        }
                    ]
                }
            },
            {
                "face_id": "2214385551553882723",
                "x": 268,
                "y": 61,
                "width": 60,
                "height": 60,
                "gender": 99,
                "age": 27,
                "expression": 0,
                "beauty": 79,
                "glass": 0,
                "pitch": 3,
                "yaw": 0,
                "roll": 4294967295,
                "face_shape": {
                    "face_profile": [
                        {
                            "x": 380,
                            "y": 207
                        },
                        {
                            "x": 381,
                            "y": 214
                        },
                        {
                            "x": 383,
                            "y": 220
                        },
                        {
                            "x": 386,
                            "y": 226
                        },
                        {
                            "x": 390,
                            "y": 232
                        },
                        {
                            "x": 394,
                            "y": 237
                        },
                        {
                            "x": 398,
                            "y": 242
                        },
                        {
                            "x": 403,
                            "y": 247
                        },
                        {
                            "x": 408,
                            "y": 252
                        },
                        {
                            "x": 413,
                            "y": 256
                        },
                        {
                            "x": 419,
                            "y": 257
                        },
                        {
                            "x": 427,
                            "y": 255
                        },
                        {
                            "x": 433,
                            "y": 250
                        },
                        {
                            "x": 438,
                            "y": 244
                        },
                        {
                            "x": 442,
                            "y": 238
                        },
                        {
                            "x": 446,
                            "y": 231
                        },
                        {
                            "x": 448,
                            "y": 223
                        },
                        {
                            "x": 449,
                            "y": 215
                        },
                        {
                            "x": 448,
                            "y": 207
                        },
                        {
                            "x": 447,
                            "y": 200
                        },
                        {
                            "x": 446,
                            "y": 193
                        },
                        {
                            "x": 271,
                            "y": 77
                        },
                        {
                            "x": 270,
                            "y": 83
                        },
                        {
                            "x": 270,
                            "y": 90
                        },
                        {
                            "x": 271,
                            "y": 96
                        },
                        {
                            "x": 272,
                            "y": 103
                        },
                        {
                            "x": 273,
                            "y": 109
                        },
                        {
                            "x": 276,
                            "y": 115
                        },
                        {
                            "x": 280,
                            "y": 120
                        },
                        {
                            "x": 285,
                            "y": 124
                        },
                        {
                            "x": 290,
                            "y": 127
                        },
                        {
                            "x": 297,
                            "y": 128
                        },
                        {
                            "x": 303,
                            "y": 127
                        },
                        {
                            "x": 310,
                            "y": 125
                        },
                        {
                            "x": 315,
                            "y": 121
                        },
                        {
                            "x": 320,
                            "y": 117
                        },
                        {
                            "x": 323,
                            "y": 111
                        },
                        {
                            "x": 325,
                            "y": 105
                        },
                        {
                            "x": 327,
                            "y": 98
                        },
                        {
                            "x": 328,
                            "y": 92
                        },
                        {
                            "x": 328,
                            "y": 85
                        },
                        {
                            "x": 328,
                            "y": 79
                        }
                    ],
                    "left_eye": [
                        {
                            "x": 387,
                            "y": 206
                        },
                        {
                            "x": 389,
                            "y": 207
                        },
                        {
                            "x": 392,
                            "y": 207
                        },
                        {
                            "x": 395,
                            "y": 206
                        },
                        {
                            "x": 398,
                            "y": 205
                        },
                        {
                            "x": 395,
                            "y": 203
                        },
                        {
                            "x": 392,
                            "y": 203
                        },
                        {
                            "x": 389,
                            "y": 204
                        },
                        {
                            "x": 280,
                            "y": 78
                        },
                        {
                            "x": 282,
                            "y": 79
                        },
                        {
                            "x": 285,
                            "y": 79
                        },
                        {
                            "x": 288,
                            "y": 79
                        },
                        {
                            "x": 290,
                            "y": 79
                        },
                        {
                            "x": 288,
                            "y": 76
                        },
                        {
                            "x": 285,
                            "y": 76
                        },
                        {
                            "x": 282,
                            "y": 76
                        }
                    ],
                    "right_eye": [
                        {
                            "x": 426,
                            "y": 198
                        },
                        {
                            "x": 424,
                            "y": 199
                        },
                        {
                            "x": 421,
                            "y": 201
                        },
                        {
                            "x": 418,
                            "y": 201
                        },
                        {
                            "x": 415,
                            "y": 201
                        },
                        {
                            "x": 417,
                            "y": 198
                        },
                        {
                            "x": 420,
                            "y": 197
                        },
                        {
                            "x": 423,
                            "y": 197
                        },
                        {
                            "x": 317,
                            "y": 79
                        },
                        {
                            "x": 315,
                            "y": 80
                        },
                        {
                            "x": 312,
                            "y": 80
                        },
                        {
                            "x": 309,
                            "y": 79
                        },
                        {
                            "x": 307,
                            "y": 79
                        },
                        {
                            "x": 309,
                            "y": 77
                        },
                        {
                            "x": 312,
                            "y": 76
                        },
                        {
                            "x": 315,
                            "y": 77
                        }
                    ],
                    "left_eyebrow": [
                        {
                            "x": 380,
                            "y": 199
                        },
                        {
                            "x": 384,
                            "y": 198
                        },
                        {
                            "x": 388,
                            "y": 198
                        },
                        {
                            "x": 392,
                            "y": 199
                        },
                        {
                            "x": 396,
                            "y": 198
                        },
                        {
                            "x": 393,
                            "y": 196
                        },
                        {
                            "x": 388,
                            "y": 196
                        },
                        {
                            "x": 383,
                            "y": 196
                        },
                        {
                            "x": 275,
                            "y": 70
                        },
                        {
                            "x": 280,
                            "y": 70
                        },
                        {
                            "x": 285,
                            "y": 71
                        },
                        {
                            "x": 289,
                            "y": 72
                        },
                        {
                            "x": 294,
                            "y": 73
                        },
                        {
                            "x": 290,
                            "y": 69
                        },
                        {
                            "x": 285,
                            "y": 67
                        },
                        {
                            "x": 279,
                            "y": 67
                        }
                    ],
                    "right_eyebrow": [
                        {
                            "x": 430,
                            "y": 188
                        },
                        {
                            "x": 425,
                            "y": 190
                        },
                        {
                            "x": 419,
                            "y": 192
                        },
                        {
                            "x": 414,
                            "y": 194
                        },
                        {
                            "x": 409,
                            "y": 196
                        },
                        {
                            "x": 412,
                            "y": 191
                        },
                        {
                            "x": 418,
                            "y": 188
                        },
                        {
                            "x": 424,
                            "y": 187
                        },
                        {
                            "x": 323,
                            "y": 73
                        },
                        {
                            "x": 318,
                            "y": 72
                        },
                        {
                            "x": 313,
                            "y": 72
                        },
                        {
                            "x": 308,
                            "y": 73
                        },
                        {
                            "x": 303,
                            "y": 73
                        },
                        {
                            "x": 308,
                            "y": 70
                        },
                        {
                            "x": 313,
                            "y": 68
                        },
                        {
                            "x": 319,
                            "y": 68
                        }
                    ],
                    "mouth": [
                        {
                            "x": 402,
                            "y": 235
                        },
                        {
                            "x": 405,
                            "y": 239
                        },
                        {
                            "x": 409,
                            "y": 242
                        },
                        {
                            "x": 414,
                            "y": 242
                        },
                        {
                            "x": 419,
                            "y": 240
                        },
                        {
                            "x": 423,
                            "y": 237
                        },
                        {
                            "x": 426,
                            "y": 232
                        },
                        {
                            "x": 421,
                            "y": 232
                        },
                        {
                            "x": 415,
                            "y": 232
                        },
                        {
                            "x": 411,
                            "y": 233
                        },
                        {
                            "x": 409,
                            "y": 233
                        },
                        {
                            "x": 405,
                            "y": 234
                        },
                        {
                            "x": 405,
                            "y": 237
                        },
                        {
                            "x": 409,
                            "y": 238
                        },
                        {
                            "x": 413,
                            "y": 238
                        },
                        {
                            "x": 418,
                            "y": 237
                        },
                        {
                            "x": 422,
                            "y": 235
                        },
                        {
                            "x": 422,
                            "y": 233
                        },
                        {
                            "x": 417,
                            "y": 234
                        },
                        {
                            "x": 412,
                            "y": 235
                        },
                        {
                            "x": 409,
                            "y": 235
                        },
                        {
                            "x": 405,
                            "y": 235
                        },
                        {
                            "x": 287,
                            "y": 107
                        },
                        {
                            "x": 290,
                            "y": 110
                        },
                        {
                            "x": 293,
                            "y": 111
                        },
                        {
                            "x": 297,
                            "y": 112
                        },
                        {
                            "x": 301,
                            "y": 112
                        },
                        {
                            "x": 305,
                            "y": 111
                        },
                        {
                            "x": 308,
                            "y": 109
                        },
                        {
                            "x": 304,
                            "y": 107
                        },
                        {
                            "x": 300,
                            "y": 105
                        },
                        {
                            "x": 297,
                            "y": 106
                        },
                        {
                            "x": 294,
                            "y": 105
                        },
                        {
                            "x": 291,
                            "y": 106
                        },
                        {
                            "x": 290,
                            "y": 108
                        },
                        {
                            "x": 294,
                            "y": 108
                        },
                        {
                            "x": 297,
                            "y": 109
                        },
                        {
                            "x": 301,
                            "y": 109
                        },
                        {
                            "x": 304,
                            "y": 109
                        },
                        {
                            "x": 304,
                            "y": 108
                        },
                        {
                            "x": 301,
                            "y": 108
                        },
                        {
                            "x": 297,
                            "y": 108
                        },
                        {
                            "x": 294,
                            "y": 108
                        },
                        {
                            "x": 290,
                            "y": 107
                        }
                    ],
                    "nose": [
                        {
                            "x": 406,
                            "y": 224
                        },
                        {
                            "x": 405,
                            "y": 204
                        },
                        {
                            "x": 404,
                            "y": 210
                        },
                        {
                            "x": 403,
                            "y": 215
                        },
                        {
                            "x": 401,
                            "y": 220
                        },
                        {
                            "x": 400,
                            "y": 225
                        },
                        {
                            "x": 404,
                            "y": 228
                        },
                        {
                            "x": 409,
                            "y": 228
                        },
                        {
                            "x": 414,
                            "y": 226
                        },
                        {
                            "x": 419,
                            "y": 221
                        },
                        {
                            "x": 415,
                            "y": 217
                        },
                        {
                            "x": 411,
                            "y": 213
                        },
                        {
                            "x": 408,
                            "y": 209
                        },
                        {
                            "x": 298,
                            "y": 93
                        },
                        {
                            "x": 298,
                            "y": 79
                        },
                        {
                            "x": 296,
                            "y": 83
                        },
                        {
                            "x": 294,
                            "y": 87
                        },
                        {
                            "x": 292,
                            "y": 91
                        },
                        {
                            "x": 289,
                            "y": 95
                        },
                        {
                            "x": 294,
                            "y": 98
                        },
                        {
                            "x": 298,
                            "y": 99
                        },
                        {
                            "x": 302,
                            "y": 98
                        },
                        {
                            "x": 306,
                            "y": 96
                        },
                        {
                            "x": 304,
                            "y": 91
                        },
                        {
                            "x": 302,
                            "y": 87
                        },
                        {
                            "x": 300,
                            "y": 83
                        }
                    ]
                }
            }
        ]
    }
}