人脸M：N搜索
业务能力
本文档为人脸M:N搜索API的使用说明文档。如果您业务上的图片主要由普通摄像头/抓拍机设备采集的大角度俯拍照片为主，建议您使用场景化搜索服务，查看文档详情
- 人脸M：N搜索：也称为M：N识别，待识别图片中含有多个人脸时，在指定人脸库集合中，找到与待识别图片中的多个人脸分别最相似的人脸。
- 注意：需要完成人脸M：N搜索，需配合人脸库管理系列API一同使用，首先构建一个人脸库，用于存放所有待比对的人脸特征，具体文档可参考人脸库管理相关接口文档说明.
M：N识别的原理，相当于从待比对的多人脸图片中，先分别找出所有人脸，然后将这些人脸信息分别在人脸库中进行1：N搜索，最后将所有搜索结果汇总在一起进行返回。
若人脸库超过1年未使用（无入库、搜索等操作），平台将对相关人脸库资源进行释放，以确保用户信息安全。
在线调试
您可以在 示例代码中心 中调试该接口，可进行签名验证、查看在线调用的请求内容和返回结果、示例代码的自动生成。
请求说明
注意事项：
- 请求体格式化：Content-Type为
application/json，通过json格式化请求体。 - Base64编码：请求的图片需经过
Base64编码，图片的base64编码指将图片数据编码成一串字符串，使用该字符串代替图像地址。您可以首先得到图片的二进制，然后用Base64格式编码即可。需要注意的是，图片的base64编码是不包含图片头的，如data:image/jpg;base64,。 - 图片格式：现支持PNG、JPG、JPEG、BMP，不支持GIF图片。
请求示例
HTTP方法：POST
请求URL： https://aip.baidubce.com/rest/2.0/face/v3/multi-search
URL参数：
| 参数 | 值 |
|---|---|
| access_token | 通过API Key和Secret Key获取的access_token,参考“Access Token获取” |
Header如下：
| 参数 | 值 |
|---|---|
| Content-Type | application/json |
Body中放置请求参数，参数详情如下：
请求参数
| 参数 | 必选 | 类型 | 说明 |
|---|---|---|---|
| image | 是 | string | 图片信息(数据大小应小于10M 分辨率应小于1920*1080) |
| image_type | 是 | string | 图片类型 BASE64:（推荐）图片的base64值; FACE_TOKEN: face_token 人脸标识 |
| group_id_list | 是 | string | 从指定的group中进行查找 用逗号分隔，上限10个 |
| max_face_num | 否 | int | 最多处理人脸的数目 默认值为1(仅检测图片中面积最大的那个人脸) 最大值10 |
| match_threshold | 否 | int | 匹配阈值（设置阈值后，score低于此阈值的用户信息将不会返回） 最大100 最小0 默认80 此阈值设置得越高，检索速度将会越快，推荐使用默认阈值 80 |
| quality_control | 否 | string | 质量控制(质量不符合要求的人脸不会出现在返回结果中) NONE: 不进行控制 LOW:较低的质量要求 NORMAL: 一般的质量要求 HIGH: 较高的质量要求 默认NONE |
| liveness_control | 否 | string | 活体控制(活体分数不符合要求的人脸不会出现在返回结果中) NONE: 不进行控制 LOW:较低的活体要求(高通过率 低攻击拒绝率) NORMAL: 一般的活体要求(平衡的攻击拒绝率, 通过率) HIGH: 较高的活体要求(高攻击拒绝率 低通过率) 默认NONE |
| spoofing_control | 否 | string | 合成图控制 NONE: 不进行控制 LOW:较低的合成图阈值数值，由于合成图判定逻辑为大于阈值视为合成图攻击，该项代表低通过率、高攻击拒绝率 NORMAL: 一般的合成图阈值数值，由于合成图判定逻辑为大于阈值视为合成图攻击，该项代表平衡的攻击拒绝率, 通过率 HIGH: 较高的合成图阈值数值，由于合成图判定逻辑为大于阈值视为合成图攻击，该项代表高通过率、低攻击拒绝率) 默认为NONE |
| max_user_num | 否 | unit32 | 识别返回的最大用户数，默认为1，最大20个 |
请求示例
{
"image": "/9j/4AAQSkZJRgABAQAAAQABAAD/2wBDAAgGBgcGBQgHBwcJCQgKD...",
"image_type": "BASE64",
"group_id_list": "group1",
"max_face_num" : 5,
"quality_control": "LOW",
"liveness_control": "NORMAL"
}返回说明
返回参数
| 字段 | 必选 | 类型 | 说明 |
|---|---|---|---|
| log_id | 是 | uint64 | 请求标识码，随机数，唯一 |
| face_num | 是 | int | 图片中的人脸数量 |
| face_list | 是 | array | 人脸信息列表 |
| +face_token | 是 | string | 人脸图片的唯一标识（有效期60min）。此token由用于搜索的人脸图片生成，非搜索到的人脸face_token |
| +location | 是 | array | 人脸在图片中的位置 |
| ++left | 是 | double | 人脸区域离左边界的距离 |
| ++top | 是 | double | 人脸区域离上边界的距离 |
| ++width | 是 | double | 人脸区域的宽度 |
| ++height | 是 | double | 人脸区域的高度 |
| ++rotation | 是 | int64 | 人脸框相对于竖直方向的顺时针旋转角，[-180,180] |
| +user_list | 是 | array | 匹配的用户信息列表 |
| ++group_id | 是 | string | 用户所属的group_id |
| ++user_id | 是 | string | 用户的user_id |
| ++user_info | 是 | string | 注册用户时携带的user_info |
| ++score | 是 | float | 用户的匹配得分 80分以上可以判断为同一人，此分值对应万分之一误识率 |
返回示例
{
"error_code": 0,
"error_msg": "SUCCESS",
"log_id": 240483475,
"timestamp": 1535533440,
"cached": 0,
"result": {
"face_num": 2,
"face_list": [
{
"face_token": "6fe19a6ee0c4233db9b5bba4dc2b9233",
"location": {
"left": 31.95568085,
"top": 120.3764267,
"width": 87,
"height": 85,
"rotation": -5
},
"user_list": [
{
"group_id": "group1",
"user_id": "5abd24fd062e49bfa906b257ec40d284",
"user_info": "userinfo1",
"score": 69.85684967041
},
{
"group_id": "group1",
"user_id": "2abf89cffb31473a9948268fde9e1c3f",
"user_info": "userinfo2",
"score": 66.586112976074
}
]
},
{
"face_token": "fde61e9c074f48cf2bbb319e42634f41",
"location": {
"left": 219.4467773,
"top": 104.7486954,
"width": 81,
"height": 77,
"rotation": 3
},
"user_list": [
{
"group_id": "group1",
"user_id": "088717532b094c3990755e91250adf7d",
"user_info": "userinfo",
"score": 65.154159545898
}
]
}
]
}
}- 质量控制参数说明
不同的控制度下所对应的质量控制阈值，如果检测出来的质量信息某一项不符合控制阈值的要求，则会返回错误信息。
遮挡情况的阈值
| 控制度 | left_eye | right_eye | nose | mouth | left_cheek | right_cheek | chin_contour |
|---|---|---|---|---|---|---|---|
| LOW | 0.8 | 0.8 | 0.8 | 0.8 | 0.8 | 0.8 | 0.8 |
| NORMAL | 0.6 | 0.6 | 0.6 | 0.6 | 0.6 | 0.6 | 0.6 |
| HIGH | 0.2 | 0.2 | 0.2 | 0.2 | 0.2 | 0.2 | 0.2 |
模糊度、完整度的阈值
| 控制度 | illumination | blurdegree | completeness |
|---|---|---|---|
| LOW | 20 | 0.8 | 0 |
| NORMAL | 40 | 0.6 | 0 |
| HIGH | 100 | 0.2 | 1 |
活体控制参数说明
不同的控制度下所对应的活体控制阈值，如果检测出来的活体分数小于控制阈值，则会返回错误信息。
| 控制度 | 阈值 | 说明 |
|---|---|---|
| LOW | 0.05 | 活体误拒率：万分之一；拒绝率：97.75% |
| NORMAL | 0.3 | 活体误拒率：千分之一；拒绝率：98.82% |
| HIGH | 0.9 | 活体误拒率：百分之一；拒绝率：99.77% |
1、误拒率: 把真人识别为假人的概率. 阈值越高，安全性越高, 要求也就越高, 对应的误识率就越高
2、通过率=1-误拒率
关于以上数值的概念介绍：
拒绝率（TRR）：如99%，代表100次作弊假体攻击，会有99次被拒绝。 误拒率（FRR）：如0.5%，指1000次真人请求，会有5次因为活体分数低于阈值被错误拒绝。 通过率（TAR）：如99%，指100次真人请求，会有99次因为活体分数高于阈值而通过。 阈值（Threshold）：高于此数值，则可判断为活体。
合成图控制参数说明
不同的控制度下所对应的合成图检测（PS、人脸融合等）阈值，如果检测出来的分数大于控制阈值，则会返回错误信息。
| 控制度 | 阈值 | 误拒率（FRR） | 通过率 | 攻击拒绝率（TRR）） |
|---|---|---|---|---|
| LOW | 0.00023 | 5% | 95% | 94.93% |
| NORMAL（推荐） | 0.00048 | 1% | 99% | 89.71% |
| HIGH | 0.00109 | 0.1% | 99.9% | 84.57% |
1、误拒率：把正常图片识别为合成图片的概率。阈值越低，安全性越高，要求也就越高，对应的误识率就越高。 2、通过率=1-误拒率
关于以上数值的概念介绍：
阈值（Threshold）：高于此数值，则可判断为是合成图攻击。