人脸库概述

EVS人脸库基于边缘构建，层级关系为：group(库) -> user(人) -> face(脸)；

人脸库用group_id唯一标识，一个人脸库包含多个用户(user_id)，一个用户支持上传多张人脸(face_token)；

• 每个EVS用户在每个边缘节点可以创建任意多个人脸库group；
• 每个人脸库下，可以添加任意多个用户user(为了保证查询速度，单个group中的user上限建议为80万)；
• 每个用户user能注册多张人脸face(为了保证查询速度，一个用户建议最多上传20张人脸)；

为了保证人脸识别效果，添加人脸时请控制注册人脸的质量，在调用人脸注册接口时使用质量控制和活体控制参数保证图片的质量以及注册进入人脸库的人脸是活体；

人脸库接口列表：

接口	描述
添加人脸	人脸库中的特定用户添加一张人脸
删除人脸	删除人脸库中用户的特定一张人脸
更新人脸	更新人脸库中特定用户的全部人脸
人脸列表查询	查询人脸库中特定用户的所有人脸
复制用户	从人脸库中的某个用户复制到另一个人脸库中
删除用户	从人脸库中删除特定用户
查询单个用户	查询某个人脸库的单个用户信息
查询用户列表	查询某个人脸库中包含的所有用户列表
创建人脸库	创建一个人脸库
删除人脸库	删除一个人脸库
人脸库列表查询	分页查询人脸库列表

添加人脸

请求Url

POST /v1/human/face/add 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	必选	String	人脸库标识group_id，最多48个字符，支持[A-Za-z0-9_]
user_id	必选	String	用户标识user_id，最多48个字符，支持[A-Za-z0-9_]
user_info	可选	String	用户信息，最多256个字符
quality_control	可选	String	图片质量控制，默认NONE，若图片质量不满足要求，则返回结果中会提示质量检测失败
liveness_control	可选	String	活体检测控制，默认NONE，若活体检测结果不满足要求，则返回结果中会提示活体检测失败
action_type	可选	String	操作方式，可选值：APPEND、REPLACE，默认APPEND

其中action_type参数说明如下：

action_type	说明
APPEND	当用户user_id在人脸库中已经存在时，对此user_id重复注册时，新注册的图片默认会追加到该user_id下
REPLACE	当对此用户user_id重复注册时，则会用新图替换库中该user_id下所有图片

图片质量控制：

可选值	说明
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	较高的活体要求(高攻击拒绝率, 低通过率)

Response参数

参数	类型	说明
code	Integer	0：请求成功，非0：请求失败
message	String	请求成功message为空，请求失败为失败提示信息
data	Object	添加人脸信息
+face_token	String	人脸唯一标识face_token
+location	Object	人脸位置信息
++left	Integer	位置相对左边框的坐标
++top	Integer	位置相对上边框的坐标
++width	Integer	人脸宽度
++height	Integer	人脸高度
++rotation	Integer	人脸角度

删除人脸

请求Url

POST /v1/human/face/delete HTTP/1.1

Request参数

参数	可选	类型	说明
group_id	必选	String	人脸库标识group_id，最多48个字符，支持[A-Za-z0-9_]
user_id	必选	String	用户标识user_id，最多48个字符，支持[A-Za-z0-9_]
face_token	必选	String	人脸唯一标识face_token

Response参数

参数	类型	说明
code	Integer	0：请求成功，非0：请求失败
message	String	请求成功message为空，请求失败为失败提示信息

更新人脸

请求Url

POST /v1/human/face/update 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	必选	String	人脸库标识group_id，最多48个字符，支持[A-Za-z0-9_]
user_id	必选	String	用户标识user_id，最多48个字符，支持[A-Za-z0-9_]
user_info	可选	String	用户信息，最多256个字符
quality_control	可选	String	图片质量控制，默认NONE，若图片质量不满足要求，则返回结果中会提示质量检测失败
liveness_control	可选	String	活体检测控制，默认NONE，若活体检测结果不满足要求，则返回结果中会提示活体检测失败
action_type	可选	String	操作方式，可选值：UPDATE、REPLACE，默认UPDATE

其中action_type参数说明如下：

action_type	说明
UPDATE	使用新图片替换人脸库中该用户user_id下所有图片, 若user_id不存在则会报错
REPLACE	当user_id不存在时, 则会注册这个user_id的用户

Response参数

参数	类型	说明
code	Integer	0：请求成功，非0：请求失败
message	String	请求成功message为空，请求失败为失败提示信息
data	Object	添加人脸信息
+face_token	String	人脸唯一标识face_token
+location	Object	人脸位置信息
++left	Integer	位置相对左边框的坐标
++top	Integer	位置相对上边框的坐标
++width	Integer	人脸宽度
++height	Integer	人脸高度
++rotation	Integer	人脸角度

人脸列表查询

请求Url

POST /v1/human/face/list HTTP/1.1

Request参数

参数	可选	类型	说明
group_id	必选	String	人脸库标识group_id，最多48个字符，支持[A-Za-z0-9_]
user_id	必选	String	用户标识user_id，最多48个字符，支持[A-Za-z0-9_]

Response参数

参数	类型	说明
code	Integer	0：请求成功，非0：请求失败
message	String	请求成功message为空，请求失败为失败提示信息
data	List	人脸信息列表
+face_token	String	人脸唯一标识face_token
+ctime	String	人脸添加时间字符串yyyy-MM-dd HH:mm:ss

复制用户

请求Url

POST /v1/human/face/user/copy HTTP/1.1

Request参数

参数	可选	类型	说明
user_id	必选	String	用户标识user_id，最多48个字符，支持[A-Za-z0-9_]
src_group_id	必选	String	源人脸库标识group_id，最多48个字符，支持[A-Za-z0-9_]
dst_group_id	必选	String	目标人脸库标识group_id，最多48个字符，支持[A-Za-z0-9_]

Response参数

参数	类型	说明
code	Integer	0：请求成功，非0：请求失败
message	String	请求成功message为空，请求失败为失败提示信息

删除用户

请求Url

POST /v1/human/face/user/delete HTTP/1.1

Request参数

参数	可选	类型	说明
group_id	必选	String	人脸库标识group_id，最多48个字符，支持[A-Za-z0-9_]
user_id	必选	String	用户标识user_id，最多48个字符，支持[A-Za-z0-9_]

Response参数

参数	类型	说明
code	Integer	0：请求成功，非0：请求失败
message	String	请求成功message为空，请求失败为失败提示信息

查询单个用户

请求Url

POST /v1/human/face/user/query HTTP/1.1

Request参数

参数	可选	类型	说明
group_id	必选	String	人脸库标识group_id，最多48个字符，支持[A-Za-z0-9_]
user_id	必选	String	用户标识user_id，最多48个字符，支持[A-Za-z0-9_]

Response参数

参数	类型	说明
code	Integer	0：请求成功，非0：请求失败
message	String	请求成功message为空，请求失败为失败提示信息
data	List	用户信息列表
+group_id	String	用户所在人脸库group_id
+user_info	String	用户信息

用户列表查询

请求Url

POST /v1/human/face/user/list HTTP/1.1

Request参数

参数	可选	类型	说明
group_id	必选	String	人脸库标识group_id，最多48个字符，支持[A-Za-z0-9_]

Response参数

参数	类型	说明
code	Integer	0：请求成功，非0：请求失败
message	String	请求成功message为空，请求失败为失败提示信息
data	List	用户user_id列表

创建人脸库

请求Url

POST /v1/human/face/group/add HTTP/1.1

Request参数

参数	可选	类型	说明
group_id	必选	String	人脸库标识，最多48个字符，支持[A-Za-z0-9_]

Response参数

参数	类型	说明
code	Integer	0：请求成功，非0：请求失败
message	String	请求成功message为空，请求失败为失败提示信息

删除人脸库

请求Url

POST /v1/human/face/group/delete HTTP/1.1

Request参数

参数	可选	类型	说明
group_id	必选	String	人脸库标识，最多48个字符，支持[A-Za-z0-9_]

Response参数

参数	类型	说明
code	Integer	0：请求成功，非0：请求失败
message	String	请求成功message为空，请求失败为失败提示信息

人脸库列表查询

请求Url

POST /v1/human/face/group/list HTTP/1.1

Request参数

参数	可选	类型	说明
start	可选	Integer	第几页，从0开始，默认查询第一页
length	可选	Integer	每页返回多少条，默认1000

Response参数

参数	类型	说明
code	Integer	0：请求成功，非0：请求失败
message	String	请求成功message为空，请求失败为失败提示信息
data	List	人脸库group_id列表