(摘自百度云 https://cloud.baidu.com/doc/FACE/Face-Java-SDK.html#.E8.BF.94.E5.9B.9E.E8.AF.B4.E6.98.8E-11)
人脸检测
接口描述
检测请求图片中的人脸,返回人脸位置、72个关键点坐标、及人脸相关属性信息。
检测响应速度,与图片中人脸数量相关,人脸数量较多时响应时间会有些许延长。
典型应用场景:如人脸属性分析,基于人脸关键点的加工分析,人脸营销活动等。
五官位置会标记具体坐标;72个关键点坐标也包含具体坐标,但不包含对应位置的详细位置描述。
请求说明
图片接受类型支持本地图片路径字符串,图片文件二进制数组。
举例,要对一张图片进行人脸识别,具体的人脸信息在返回的result字段中:
public void faceRecognize(AipFace client) {
// 参数为本地图片路径
String imagePath = "picture.jpg";
JSONObject response = client.detect(imagePath);
System.out.println(response.toString());
// 参数为本地图片文件二进制数组
byte[] file = readImageFile(imagePath); // readImageFile函数仅为示例
JSONObject response = client.detect(file);
System.out.println(response.toString());
}
复制
传入图片时还想增加一些自定义参数配置:
public void faceRecognize(AipFace client) {
// 自定义参数定义
HashMap<String, String> options = new HashMap<String, String>();
options.put("max_face_num", "1");
options.put("face_fields", "expression");
// 参数为本地图片路径
String imagePath = "face.jpg";
JSONObject response = client.detect(imagePath, options);
System.out.println(response.toString());
// 参数为本地图片文件二进制数组
byte[] file = readImageFile(imagePath);
JSONObject response = client.detect(file, options);
System.out.println(response.toString());
}
复制
人脸检测 请求参数详情
参数 | 类型 | 描述 | 是否必须 |
---|---|---|---|
face_fields | Boolean | 包括age、beauty、expression、faceshape、gender、glasses、landmark、race、qualities信息,逗号分隔,默认只返回人脸框、概率和旋转角度。 | 否 |
max_face_num | unit32 | 最多处理人脸数目,默认值1 | 是 |
image | String | 图像数据,支持本地图像文件路径,图像文件二进制数组 | 是 |
返回说明
参数 | 类型 | 是否一定输出 | 描述 |
---|---|---|---|
log_id | uint64 | 是 | 日志id |
result_num | Int | 是 | 人脸数目 |
result | object[] | 是 | 人脸属性对象的集合 |
+age | double | 否 | 年龄。face_fields包含age时返回 |
+beauty | double | 否 | 美丑打分,范围0-1,越大表示越美。face_fields包含beauty时返回 |
+location | object | 是 | 人脸在图片中的位置 |
++left | Int | 是 | 人脸区域离左边界的距离 |
++top | Int | 是 | 人脸区域离上边界的距离 |
++width | Int | 是 | 人脸区域的宽度 |
++height | Int | 是 | 人脸区域的高度 |
+face_probability | double | 是 | 人脸置信度,范围0-1 |
+rotation_angle | int32 | 是 | 人脸框相对于竖直方向的顺时针旋转角,[-180,180] |
+yaw | double | 是 | 三维旋转之左右旋转角[-90(左), 90(右)] |
+pitch | double | 是 | 三维旋转之俯仰角度[-90(上), 90(下)] |
+roll | double | 是 | 平面内旋转角[-180(逆时针), 180(顺时针)] |
+expression | Int | 否 | 表情,0,不笑;1,微笑;2,大笑。face_fields包含expression时返回 |
+expression_probability | double | 否 | 表情置信度,范围0~1。face_fields包含expression时返回 |
+faceshape | object[] | 否 | 脸型置信度。face_fields包含faceshape时返回 |
++type | String | 是 | 脸型:square/triangle/oval/heart/round |
++probability | double | 是 | 置信度:0~1 |
+gender | String | 否 | male、female。face_fields包含gender时返回 |
+gender_probability | double | 否 | 性别置信度,范围0~1。face_fields包含gender时返回 |
+glasses | Int | 否 | 是否带眼镜,0-无眼镜,1-普通眼镜,2-墨镜。face_fields包含glasses时返回 |
+glasses_probability | double | 否 | 眼镜置信度,范围0~1。face_fields包含glasses时返回 |
+landmark | object[] | 否 | 4个关键点位置,左眼中心、右眼中心、鼻尖、嘴中心。face_fields包含landmark时返回 |
++x | Int | 否 | x坐标 |
++y | Int | 否 | y坐标 |
+landmark72 | object[] | 否 | 72个特征点位置,示例图 。face_fields包含landmark时返回 |
++x | Int | 否 | x坐标 |
++y | Int | 否 | y坐标 |
+race | String | 否 | yellow、white、black、arabs。face_fields包含race时返回 |
+race_probability | double | 否 | 人种置信度,范围0~1。face_fields包含race时返回 |
+qualities | object | 否 | 人脸质量信息。face_fields包含qualities时返回 |
++occlusion | object | 是 | 人脸各部分遮挡的概率, [0, 1] (待上线) |
+++left_eye | double | 是 | 左眼 |
+++right_eye | double | 是 | 右眼 |
+++nose | double | 是 | 鼻子 |
+++mouth | double | 是 | 嘴 |
+++left_cheek | double | 是 | 左脸颊 |
+++right_cheek | double | 是 | 右脸颊 |
+++chin | double | 是 | 下巴 |
++type | object | 是 | 真实人脸/卡通人脸置信度 |
+++human | double | 是 | 真实人脸置信度,[0, 1] |
+++cartoon | double | 是 | 卡通人脸置信度,[0, 1] |
人脸比对
接口描述
该请求用于比对多张图片中的人脸相似度并返回两两比对的得分,可用于判断两张脸是否是同一人的可能性大小。
典型应用场景:如人证合一验证,用户认证等,可与您现有的人脸库进行比对验证。
说明:支持对比对的两张图片做在线活体检测
请求说明
接受的参数为一系列本地图片路径的数组,或图片二进制数据的数组。
举例,要对两张图片进行人脸比对,具体的人脸信息在返回的result字段中:
public void faceRecognize(AipFace client) {
// 参数为本地图片路径
String imagePath1 = "test1.jpg";
String imagePath2 = "test2.jpg";
ArrayList<String> pathArray = new ArrayList<String>();
pathArray.add(imagePath1);
pathArray.add(imagePath2);
JSONObject response = client.match(pathArray, new HashMap<String, String>());
System.out.println(response.toString());
}
复制
人脸比对请求参数:
所有图片经base64编码后的图片数据总和不超过10M。以下可选参数以HashMap形式放在接口最后的options参数中。
参数 | 是否必选 | 类型 | 说明 |
---|---|---|---|
ext_fields | 否 | string | 返回质量信息,取值固定: 目前支持qualities(质量检测)。(对所有图片都会做改处理) |
image_liveness | 否 | string | 返回的活体信息,“faceliveness,faceliveness” 表示对比对的两张图片都做活体检测;“,faceliveness” 表示对第一张图片不做活体检测、第二张图做活体检测;“faceliveness,” 表示对第一张图片做活体检测、第二张图不做活体检测 |
返回说明
字段 | 是否必选 | 类型 | 说明 |
---|---|---|---|
log_id | 是 | uint64 | 请求唯一标识码,随机数 |
result_num | 是 | uint32 | 返回结果数目,即:result数组中元素个数 |
result | 是 | array(object) | 结果数据,index和请求图片index对应。数组元素为每张图片的匹配得分数组,top n。 得分[0,100.0] |
+index_i | 是 | uint32 | 比对图片1的index |
+index_j | 是 | uint32 | 比对图片2的index |
+score | 是 | double | 比对得分 |
ext_info | 否 | array(dict) | 对应参数中的ext_fields |
+qualities | 否 | string | 质量相关的信息,无特殊需求可以不使用 |
+faceliveness | 否 | string | 活体分数“0,0.9999”(表示第一个图不做活体检测、第二个图片活体分数为0.9999) |
返回样例:
//请求为四张图片,第三张解析失败
{
"log_id": 73473737,
"result_num":3,
"result": [
{
"index_i": 0,
"index_j": 1,
"score": 44.3
},
{
"index_i": 0,
"index_j": 3,
"score": 89.2
},
{
"index_i": 1,
"index_j": 3,
"score": 10.4
}
……
]
}
复制
人脸识别
接口描述
用于计算指定组内用户,与上传图像中人脸的相似度。识别前提为您已经创建了一个人脸库。
典型应用场景:如人脸闸机,考勤签到,安防监控等。
说明:人脸识别返回值不直接判断是否是同一人,只返回用户信息及相似度分值。
说明:推荐可判断为同一人的相似度分值为80,您也可以根据业务需求选择更合适的阈值。
请求说明
举例,要计算一张图片与指定组group1, group2内各用户相似度:
public void identifyUser(AipFace client) {
String path = "test1.jpg";
HashMap<String, Object> options = new HashMap<String, Object>(1);
options.put("user_top_num", 1);
JSONObject res = client.identifyUser(Arrays.asList("group1", "group2"), path, options);
System.out.println(res.toString(2));
}
复制
人脸识别请求参数详情:
参数 | 是否必选 | 类型 | 说明 |
---|---|---|---|
group_id | 是 | string | 用户组id(由数字、字母、下划线组成)列表,每个groupid长度限制48 |
imgPath/imgData | 是 | string | imgPath对应图片本地路径,imgData对应图片二进制数据,要求图片base64编码后大小不超过10M |
ext_fields | 否 | string | 特殊返回信息,多个用逗号分隔,取值固定: 目前支持 faceliveness(活体检测) |
user_top_num | 否 | uint32 | 返回用户top数,默认为1,最多返回5个 |
返回说明
字段 | 是否必选 | 类型 | 说明 |
---|---|---|---|
log_id | 是 | uint64 | 请求唯一标识码,随机数 |
result_num | 是 | uint32 | 返回结果数目,即:result数组中元素个数 |
ext_info | 否 | array | 对应参数中的ext_fields |
+faceliveness | 否 | string | 活体分数,如0.49999 |
result | 是 | array(object) | 结果数组 |
+group_id | 是 | string | 对应的这个用户的group_id |
+uid | 是 | string | 匹配到的用户id |
+user_info | 是 | string | 注册时的用户信息 |
+scores | 是 | array(double) | 结果数组,数组元素为匹配得分,top n。得分[0,100.0] |
返回样例:
{
"log_id": 73473737,
"result_num":1,
"result": [
{
"group_id" : "test1",
"uid": "u333333",
"user_info": "Test User",
"scores": [
99.3,
83.4
]
}
]
}
复制
人脸认证
接口描述
用于识别上传的图片是否为指定用户,即查找前需要先确定要查找的用户在人脸库中的id。
典型应用场景:如人脸登录,人脸签到等
说明:人脸认证与人脸识别的差别在于:人脸识别需要指定一个待查找的人脸库中的组;而人脸认证需要指定具体的用户id即可,不需要指定具体的人脸库中的组;实际应用中,人脸认证需要用户或系统先输入id,这增加了验证安全度,但也增加了复杂度,具体使用哪个接口需要视您的业务场景判断。
说明:请求参数中,新增在线活体检测
请求说明
举例,要认证一张图片在指定group中是否为uid1的用户:
public void verifyUser(AipFace client) {
String path = "test1.jpg";
HashMap<String, Object> options = new HashMap<String, Object>(1);
options.put("top_num", 5);
JSONObject res = client.verifyUser("uid1", Arrays.asList("group1", "group2"), path, options);
System.out.println(res.toString(2));
}
复制
人脸认证请求参数详情:
可选参数均以HashMap形式放在接口最后的options参数中。
参数 | 是否必选 | 类型 | 说明 |
---|---|---|---|
uid | 是 | string | 用户id(由数字、字母、下划线组成),长度限制128B |
imgPath/imgData | 是 | string | imgPath对应图片本地路径,imgData对应图片二进制数据,要求图片base64编码后大小不超过10M |
group_id | 是 | string | 用户组id(由数字、字母、下划线组成)列表,每个groupid长度限制48 |
top_num | 否 | uint32 | 返回匹配得分top数,默认为1 |
ext_fields | 否 | string | 特殊返回信息,多个用逗号分隔,取值固定: 目前支持 faceliveness(活体检测) |
返回说明
字段 | 是否必选 | 类型 | 说明 |
---|---|---|---|
log_id | 是 | uint64 | 请求唯一标识码,随机数 |
result_num | 是 | uint32 | 返回结果数目,即:result数组中元素个数 |
result | 是 | array(double) | 结果数组,数组元素为匹配得分,top n。 得分范围[0,100.0]。推荐得分超过80可认为认证成功 |
ext_info | 否 | array | 对应参数中的ext_fields |
+faceliveness | 否 | string | 活体分数,如0.49999 |
返回样例:
{
"results": [
93.86580657959,
92.237548828125
],
"result_num": 2,
"log_id": 1629483134
}
复制
人脸注册
接口描述
用于从人脸库中新增用户,可以设定多个用户所在组,及组内用户的人脸图片,
典型应用场景:构建您的人脸库,如会员人脸注册,已有用户补全人脸信息等。
人脸库、用户组、用户、用户下的人脸层级关系如下所示:
|- 人脸库
|- 用户组一
|- 用户01
|- 人脸
|- 用户02
|- 人脸
|- 人脸
....
....
|- 用户组二
|- 用户组三
|- 用户组四
....
复制
说明:关于人脸库的设置限制
- 每个开发者账号只能创建一个人脸库;
- 每个人脸库下,用户组(group)数量没有限制;
- 每个用户组(group)下,可添加最多300000张人脸,如每个uid注册一张人脸,则最多300000个用户uid;
- 每个用户(uid)所能注册的最大人脸数量没有限制;
说明:人脸注册完毕后,生效时间最长为35s,之后便可以进行识别或认证操作。
说明:注册的人脸,建议为用户正面人脸。
说明:uid在库中已经存在时,对此uid重复注册时,新注册的图片默认会追加到该uid下,如果手动选择
action_type:replace
,则会用新图替换库中该uid下所有图片。
请求说明
举例,要注册一个新用户,用户id为uid1,加入组id为group1和group2, 注册成功后服务端会返回操作的logid:
public void facesetAddUser(AipFace client) {
// 参数为本地图片路径
String path = "picture1.jpg";
HashMap<String, String> options = new HashMap<String, String>();
JSONObject res = client.addUser("uid1", "test_user_info", Arrays.asList("group1", "group2"), path, options);
System.out.println(res.toString(2));
}
复制
人脸注册请求参数详情:
可选参数均以HashMap形式放在接口最后的options参数中。
| 参数 | 是否必选 | 类型 | 说明 |
| ----------- | ---- | ------ | ---------------------------------------- |
| uid | 是 | string | 用户id(由数字、字母、下划线组成),长度限制128B |
| user_info | 是 | string | 用户资料,长度限制256B |
| imgPath/imgData| 是 | string | imgPath对应图片本地路径,imgData对应图片二进制数据,要求图片base64编码后大小不超过10M |
| group_id | 是 | string | 用户组id(由数字、字母、下划线组成)列表,每个groupid长度限制48 |
| action_type | 否 | string | 参数包含append、replace。如果为“replace”,则每次注册时进行替换replace(新增或更新)操作,默认为append操作 |
返回说明
字段 | 是否必选 | 类型 | 说明 |
---|---|---|---|
log_id | 是 | uint64 | 请求标识码,随机数,唯一 |
返回样例:
// 注册成功
{
"log_id": 73473737,
}
// 注册发生错误
{
"error_code": 216616,
"log_id": 674786177,
"error_msg": "image exist"
}
复制
人脸更新
接口描述
用于对人脸库中指定用户,更新其下的人脸图像。
说明:针对一个uid执行更新操作,新上传的人脸图像将覆盖此uid原有所有图像。
说明:执行更新操作,如果该uid不存在时,会返回错误。如果添加了action_type:replace,则不会报错,并自动注册该uid,操作结果等同注册新用户。
请求说明
举例,要更新一个用户,用户id为uid1, 更新成功后服务端会返回操作的logid:
public void facesetUpdateUser(AipFace client) {
// 参数为本地图片路径
String path = "picture1.jpg";
HashMap<String, String> options = new HashMap<String, String>();
JSONObject res = client.updateUser("uid1", "user_info_memo", "group1", path, options);
System.out.println(res.toString(2));
}
复制
人脸更新请求参数详情:
参数 | 是否必选 | 类型 | 说明 | |
---|---|---|---|---|
uid | 是 | string | 用户id(由数字、字母、下划线组成),长度限制128B | |
imgPath/imgData | 是 | string | imgPath对应图片本地路径,imgData对应图片二进制数据,要求图片base64编码后大小不超过10M | |
group_id | 是 | string | 用户组id(由数字、字母、下划线组成),长度限制48 | |
user_info | 是 | string | 新的user_info信息 | "memo" |
action_type | 否 | string | 如果为replace时,则uid不存在时,不报错,会自动注册。 不存在该参数时,如果uid不存在会提示错误 | replace |
返回说明
字段 | 是否必选 | 类型 | 说明 |
---|---|---|---|
log_id | 是 | uint64 | 请求标识码,随机数,唯一 |
返回样例:
// 更新成功
{
"log_id": 73473737,
}
// 更新发生错误
{
"error_code": 216612,
"log_id": 1137508902,
"error_msg": "user not exist"
}
复制
人脸删除
接口描述
用于从人脸库中删除一个用户。
人脸删除注意事项:
- 删除的内容,包括用户所有图像和身份信息;
- 如果一个uid存在于多个用户组内且没有指定group_id,将会同时将从各个组中把用户删除
- 如果指定了group_id,则只删除此group下的uid相关信息
请求说明
举例,要删除一个用户,用户id为uid1, 删除成功后服务端会返回操作的logid:
public void facesetDeleteUser(AipFace client) {
// 只从指定组中删除用户
JSONObject res = client.deleteUser("uid1", Arrays.asList("group1"));
System.out.println(res.toString(2));
// 从人脸库中彻底删除用户
JSONObject res = client.deleteUser("uid1");
System.out.println(res.toString(2));
}
复制
人脸删除请求参数:
参数 | 是否必选 | 类型 | 说明 |
---|---|---|---|
uid | 是 | string | 用户id(由数字、字母、下划线组成),长度限制128B |
group_id | 否 | string | 选择指定group_id则只删除group列表下的uid内容,如果不指定则删除group下对应uid的信息 |
返回说明
字段 | 是否必选 | 类型 | 说明 |
---|---|---|---|
log_id | 是 | uint64 | 请求标识码,随机数,唯一 |
返回样例:
// 更新成功
{
"log_id": 73473737,
}
// 更新发生错误
{
"error_code": 216612,
"log_id": 1137508902,
"error_msg": "user not exist"
}
复制
用户信息查询
接口描述
用于查询人脸库中某用户的详细信息。
请求说明
举例,要查询指定用户的信息:
public void getUser(AipFace client) {
// 查询一个用户在所有组内的信息
JSONObject res = client.getUser("uid1");
System.out.println(res.toString(2));
// 查询一个用户在指定组内的信息
JSONObject res = client.getUser("uid1", Arrays.asList("group1"));
System.out.println(res.toString(2));
}
复制
用户信息查询请求参数:
参数 | 是否必选 | 类型 | 说明 |
---|---|---|---|
uid | 是 | string | 用户id(由数字、字母、下划线组成),长度限制128B |
group_id | 否 | string | 选择指定group_id则只查找group列表下的uid内容,如果不指定则查找所有group下对应uid的信息 |
返回说明
字段 | 是否必选 | 类型 | 说明 |
---|---|---|---|
log_id | 是 | uint64 | 请求标识码,随机数,唯一 |
result | 是 | array(double) | 结果数组 |
+uid | 是 | string | 匹配到的用户id |
+user_info | 是 | string | 注册时的用户信息 |
+groups | 是 | array(string) | 用户所属组列表 |
返回样例:
{
"result": {
"uid": "testuser2",
"user_info": "registed user info ...",
"groups": [
"grp1",
"grp2",
"grp3"
]
},
"log_id": 2979357502
}
复制
组列表查询
接口描述
用于查询用户组的列表。
请求说明
举例:
public void getGroupList(AipFace client) {
HashMap<String, Object> options = new HashMap<String, Object>(2);
options.put("start", 0);
options.put("num", 10);
JSONObject res = client.getGroupList(options);
System.out.println(res.toString(2));
}
复制
组列表查询请求参数详情:
参数 | 是否必选 | 类型 | 说明 |
---|---|---|---|
start | 否 | uint32 | 默认值0,起始序号 |
end | 否 | uint32 | 返回数量,默认值100,最大值1000 |
返回说明
字段 | 是否必选 | 类型 | 说明 |
---|---|---|---|
log_id | 是 | uint64 | 请求标识码,随机数,唯一 |
result_num | 是 | uint32 | 返回个数 |
result | 是 | array(string) | group_id列表 |
返回样例:
{
"result_num": 2,
"result": [
"grp1",
"grp2"
],
"log_id": 3314921889
}
复制
组内用户列表查询
接口描述
用于查询指定用户组中的用户列表。
请求说明
举例:
public void getGroupUsers(AipFace client) {
HashMap<String, Object> options = new HashMap<String, Object>(2);
options.put("start", 0);
options.put("num", 10);
JSONObject res = client.getGroupUsers("group1", options);
System.out.println(res.toString(2));
}
复制
组内用户列表查询请求参数详情:
参数 | 是否必选 | 类型 | 说明 |
---|---|---|---|
group_id | 是 | string | 用户组id |
start | 否 | uint32 | 默认值0,起始序号 |
end | 否 | uint32 | 返回数量,默认值100,最大值1000 |
返回说明
字段 | 是否必选 | 类型 | 说明 |
---|---|---|---|
log_id | 是 | uint64 | 请求标识码,随机数,唯一 |
result_num | 是 | uint32 | 返回个数 |
result | 是 | array(object) | user列表 |
+uid | 是 | string | 用户id |
+user_info | 是 | string | 用户信息 |
返回样例:
{
"log_id": 3314921889,
"result_num": 2,
"result": [
{
"uid": "uid1",
"user_info": "user info 1"
},
{
"uid": "uid2",
"user_info": "user info 2"
}
]
}
复制
组内添加用户
接口描述
用于将已经存在于人脸库中的用户添加到一个新的组。
说明:并不是向一个指定组内添加用户,而是直接从其它组复制用户信息
请求说明
举例:
public void addGroupUser(AipFace client) {
JSONObject res = client.addGroupUser("srcgroup", Arrays.asList("dstGroup1", "dstGroup2"), "uid1");
System.out.println(res.toString(2));
}
复制
组内添加用户请求参数详情:
参数 | 是否必选 | 类型 | 说明 |
---|---|---|---|
src_group_id | 是 | string | 从指定group里复制信息 |
group_id | 是 | string | 需要添加信息的组id列表 |
uid | 是 | string | 用户id |
返回说明
字段 | 是否必选 | 类型 | 说明 |
---|---|---|---|
log_id | 是 | uint64 | 请求标识码,随机数,唯一 |
返回样例:
// 正确返回值
{
"log_id": 3314921889,
}
// 发生错误时返回值
{
"error_code": 216100,
"log_id": 3111284097,
"error_msg": "already add"
}
复制
组内删除用户
接口描述
用于将用户从某个组中删除,但不会删除用户在其它组的信息。
说明:当用户仅属于单个分组时,本接口将返回错误,请使用人脸删除接口
请求说明
举例:
public void deleteGroupUser(AipFace client) {
JSONObject res = client.deleteGroupUser(Arrays.asList("group1", "group2"), "uid1");
System.out.println(res.toString(2));
}
复制
组内删除用户请求参数详情:
参数 | 是否必选 | 类型 | 说明 |
---|---|---|---|
group_id | 是 | string | 用户组id列表 |
uid | 是 | string | 用户id |
返回说明
字段 | 是否必选 | 类型 | 说明 |
---|---|---|---|
log_id | 是 | uint64 | 请求标识码,随机数,唯一 |
返回样例:
// 正确返回值
{
"log_id": 3314921889,
}
// 发生错误时返回值
{
"error_code": 216619,
"log_id": 815967402,
"error_msg": "user must be in one group at least"
}