人脸搜索

人脸搜索依赖人脸库，在使用前请先创建对应的人脸库；

人脸搜索支持单人脸搜索和多人脸搜索：

• 单人脸搜索：输入单人脸图片，返回与输入人脸最相似的用户信息，最多返回50个，如果输入图片中包括多个人，只检测图片中面积最大的那个人脸；
• 多人脸搜索：输入包括多个人脸的图片，返回每个人脸(最多支持10个用户的搜索)最相似的用户信息，最多返回20个；

人脸搜索需要指定匹配阈值，范围0~100，设置阈值后，score低于此阈值的用户信息将不会返回，此阈值设置的越高，检索速度会越快，根据场景推荐设置阈值60~80；

单人脸搜索

输入单人脸图片，返回与输入人脸最相似的用户信息；

请求Url

POST /v1/human/face/search HTTP/1.1

Request参数

参数	可选	类型	说明
image_base64	必选	String	图片base64编码，iamge_base64和image_url二选一即可，优先使用image_base64
image_url	必选	String	图片url，只有当image_base64为空时才会使用image_url下载图片再base64编码，增加下载时延
group_id_list	必选	String	人脸库group_id列表，逗号分隔，上限10个
user_id	可选	String	指定用户ID，只会在该user_id的人脸中搜索
match_threshold	必选	Integer	人脸搜索需要指定匹配阈值，范围0~100，默认值80，设置阈值后，score低于此阈值的用户信息将不会返回
quality_control	可选	String	图片质量控制，默认NONE，若图片质量不满足要求，则返回结果中会提示质量检测失败
liveness_control	可选	String	活体检测控制，默认NONE，若活体检测结果不满足要求，则返回结果中会提示活体检测失败
max_user_num	可选	Integer	返回相似用户的个数，默认值1，返回最相似的用户，最多返回50个

Response参数

参数	类型	说明
code	Integer	0：请求成功，非0：请求失败
message	String	请求成功message为空，请求失败为失败提示信息
data	Object	搜索结果
+face_token	String	输入人脸的face_token
+user_list	List	搜索结果用户列表
++group_id	String	用户对应的人脸库group_id
++user_id	String	用户id
++user_info	String	用户信息
++score	String	匹配相似度

多人脸搜索

输入包括多个人脸的图片，返回每个人脸最相似的用户信息；

请求Url

POST /v1/human/face/msearch HTTP/1.1

Request参数

参数	可选	类型	说明
image_base64	必选	String	图片base64编码，iamge_base64和image_url二选一即可，优先使用image_base64
image_url	必选	String	图片url，只有当image_base64为空时才会使用image_url下载图片再base64编码，增加下载时延
group_id_list	必选	String	人脸库group_id列表，逗号分隔，上限10个
max_face_num	可选	Integer	最多处理的人脸数目，默认值10，最大值10，设置1功能等同于单人脸搜索
match_threshold	必选	Integer	人脸搜索需要指定匹配阈值，范围0~100，默认值80，设置阈值后，score低于此阈值的用户信息将不会返回
max_user_num	可选	Integer	返回相似用户的个数，默认值1，返回最相似的用户，最多返回20个

Response参数

参数	类型	说明
code	Integer	0：请求成功，非0：请求失败
message	String	请求成功message为空，请求失败为失败提示信息
data	Object	搜索结果
+items	List	输入图片中每个人脸的搜索结果
++face_token	String	人脸的face_token
++user_list	List	搜索结果用户列表
+++group_id	String	用户对应的人脸库group_id
+++user_id	String	用户id
+++user_info	String	用户信息
+++score	String	匹配相似度
+item_count	Integer	人脸数量

质量控制

图片质量控制：

可选值	说明
NONE	不进行控制
LOW	较低的质量要求
NORMAL	一般的质量要求
HIGH	较高的质量要求

遮挡情况的阈值：

控制度	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

活体控制

活体检测控制:

可选值	说明
NONE	不进行控制
LOW	较低的活体要求(高通过率, 低攻击拒绝率)
NORMAL	一般的活体要求(平衡的攻击拒绝率, 通过率)
HIGH	较高的活体要求(高攻击拒绝率, 低通过率)