人脸M：N搜索

更新时间：2025-08-21

业务能力

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

错误码

接口流控及鉴权错误码

错误码	错误信息	描述	处理建议
2	Service temporarily unavailable	服务暂不可用	服务暂不可用，请再次请求，如果持续出现此类错误，请在控制台提交工单联系技术支持团队
4	Open api request limit reached	集群超限额	集群超限额，请再次请求，如果持续出现此类错误，请在控制台提交工单联系技术支持团队
6	no permission to access data	没有接口权限	请确认您调用的接口已经被赋权常见问题是有V3版本权限，调用的是v2版本接口；需要企业认证的，开通企业认证后一个小时左右即可使用。
17	Open api daily request limit reached	每天流量超限额	免费测试资源使用完毕，每天请求量超限额，已支持计费的接口，您可以在控制台人脸识别选择购买相关接口的次数包或开通按量后付费；邀测和未支持计费的接口，您可以在控制台提交工单申请提升限额
18	Open api qps request limit reached	QPS超限额	可直接自助购买更多QPS、联系商务接口人、或者提交工单
19	Open api total request limit reached	请求总量超限额	免费测试资源使用完毕，每天请求量超限额，已支持计费的接口，您可以在控制台人脸识别选择购买相关接口的次数包或开通按量后付费；邀测和未支持计费的接口，您可以在控制台提交工单申请提升限额
100	Invalid parameter	无效的access_token参数	token拉取失败，可以参考“Access Token获取”重新获取
110	Access token invalid or no longer valid	Access Token失效	token有效期为30天，注意需要定期更换，也可以每次请求都拉取新token
111	Access token expired	Access token过期	token有效期为30天，注意需要定期更换，也可以每次请求都拉取新token

人脸M:N搜索错误码

错误码	错误信息	描述	处理建议
222200	request body should be json format	1：请求体不是有效的JSON对象 2：请求体中字段参数值数据类型与接口文档要求不符	参考API文档说明，修改请求参数
222005	param[group_id_list] format error	参数格式错误	参考API文档说明，修改请求参数
222013	param[image] format error	参数格式错误	参考API文档说明，修改请求参数
222015	param[image_type] format error	参数格式错误	参考API文档说明，修改请求参数
222018	param[user_id] format error	参数格式错误	参考API文档说明，修改请求参数
222019	param[quality_control] format error	参数格式错误	参考API文档说明，修改请求参数
222020	param[liveness_control] format error	参数格式错误	参考API文档说明，修改请求参数
222021	param[max_user_num] format error	参数格式错误	参考API文档说明，修改请求参数
222030	param[match_threshold] format error	参数格式错误	参考API文档说明，修改请求参数
222039	param[face_sort_type] format error]	参数格式错误	参考API文档说明，修改请求参数
222201	param[scene_type] format error	请求参数scene_type 格式错误	请检查请求参数
222202	pic not has face	图片中没有人脸	检查图片质量，确保存在人脸
222203	image check fail	图片无法解析人脸	检查图片质量
222204	image download fail	从图片的url下载图片失败	确认图片 URL 公网可访问（没有白名单限制）
222205	network not availablel	服务端请求失败	请重试请求，若尝试多次无效，请提交工单咨询
222206	rtse service return fail	服务端请求失败	请重试请求，若尝试多次无效，请提交工单咨询
222207	match user is not found	未找到匹配的用户	请确认人脸库中是否存在此用户
222209	face token not exist	face token不存在	请确认您操作的人脸已创建成功。若face_token未注册到人脸库则有效期只有1小时若注册到人脸库的face_token永久有效
222301	get face fail	获取人脸失败备注：image_type为FACE_TOKEN模式时才会出现	请重试请求，如果持续出现此类错误，请提交工单
222304	image size is too large	图片尺寸太大	请确保图片尺寸不超过 6000 x 6000
223113	face is covered	人脸有被遮挡	提示用户请勿遮挡面部
223114	face is fuzzy	人脸模糊	提示用户请勿在拍摄人脸照时晃动手机
223115	face light is not good	人脸光照不好	提示用户到光线适宜的地方拍摄
223116	incomplete face	人脸不完整	提示用户将完整人脸移入框内
223120	liveness check fail	图片人脸活体检测未通过	此图人脸活体检测结果为非活体
223121	left eye is occlusion	质量检测未通过，左眼遮挡程度过高	提示用户请勿遮挡左眼
223122	right eye is occlusion	质量检测未通过，右眼遮挡程度过高	提示用户请勿遮挡右眼
223123	left cheek is occlusion	质量检测未通过，左脸遮挡程度过高	提示用户请勿遮挡左脸颊
223124	right cheek is occlusion	质量检测未通过，右脸遮挡程度过高	提示用户请勿遮挡右脸颊
223125	chin contour is occlusion	质量检测未通过，下巴遮挡程度过高	提示用户请勿遮挡下巴
223126	nose is occlusion	质量检测未通过，鼻子遮挡程度过高	提示用户请勿遮挡鼻子
223127	mouth is occlusion	质量检测未通过，嘴巴遮挡程度过高	提示用户请勿遮挡嘴巴
223129	face not forward	人脸未面向正前方（人脸角度超出限制）	请使用面向正前方的人脸图片
222915	system busy	后端服务连接失败	请重试请求，若尝试多次无效，请提交工单咨询
223202	scene_type does not match	识别时请求的scene_type与group设置的scene_type不匹配	请检查请求参数

人脸1：N搜索

人脸库管理系列接口