人脸M：N搜索

更新时间：2025-04-25

业务能力

本文档为人脸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）：高于此数值，则可判断为是合成图攻击。

人脸1：N搜索

人脸库管理系列接口