人脸库操作接口
人脸库概述
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列表 |
![]()
