PHP语言
简介
Hi,您好,欢迎使用百度人脸识别服务。
本文档主要针对PHP开发者,描述百度人脸识别接口服务的相关技术内容。如果您对文档内容有任何疑问,可以通过以下几种方式联系我们:
- 在百度云控制台内提交工单,咨询问题类型请选择人工智能服务;
- 如有疑问,进入AI社区交流:http://ai.baidu.com/forum/topic/list/165
接口能力
接口名称 | 接口能力简要描述 |
---|---|
人脸检测 | 检测人脸并定位,返回五官关键点,及人脸各属性值 |
人脸比对 | 返回两两比对的人脸相似值 |
人脸查找 | 在一个人脸集合中找到找到相似的人脸,由一系列接口组成,包括人脸识别、人脸认证、人脸库管理相关接口(人脸注册、人脸更新、人脸删除、用户信息查询、组列表查询、组内用户列表查询、组间复制用户、组内删除用户) |
版本更新记录
上线日期 | 版本号 | 更新内容 |
---|---|---|
2018.4.9 | 2.2.2 | 新增身份验证,在线活体检测接口 |
2018.01.12 | 2.1.0 | 新增M:N多人脸识别 |
2017.12.22 | 2.0.0 | SDK代码重构 |
2017.5.11 | 1.0.0 | 人脸识别服务上线 |
快速入门
安装人脸识别 PHP SDK
人脸识别 PHP SDK目录结构
├── AipFace.php //人脸识别
└── lib
├── AipHttpClient.php //内部http请求类
├── AipBCEUtil.php //内部工具类
└── AipBase //Aip基类
支持PHP版本:5.3+
使用PHP SDK开发骤如下:
1.在官方网站下载php SDK压缩包。
2.将下载的aip-php-sdk-version.zip
解压后,复制AipFace.php以及lib/*到工程文件夹中。
3.引入AipFace.php
新建AipFace
AipFace是人脸识别的PHP SDK客户端,为使用人脸识别的开发人员提供了一系列的交互方法。
参考如下代码新建一个AipFace:
require_once 'AipFace.php';
// 你的 APPID AK SK
const APP_ID = '你的 App ID';
const API_KEY = '你的 Api Key';
const SECRET_KEY = '你的 Secret Key';
$client = new AipFace(APP_ID, API_KEY, SECRET_KEY);
在上面代码中,常量APP_ID
在百度云控制台中创建,常量API_KEY
与SECRET_KEY
是在创建完毕应用后,系统分配给用户的,均为字符串,用于标识用户,为访问做签名验证,可在AI服务控制台中的应用列表中查看。
注意:如您以前是百度云的老用户,其中API_KEY
对应百度云的“Access Key ID”,SECRET_KEY
对应百度云的“Access Key Secret”。
配置AipFace
如果用户需要配置AipFace的网络请求参数(一般不需要配置),可以在构造AipFace之后调用接口设置参数,目前只支持以下参数:
接口 | 说明 |
---|---|
setConnectionTimeoutInMillis | 建立连接的超时时间(单位:毫秒) |
setSocketTimeoutInMillis | 通过打开的连接传输数据的超时时间(单位:毫秒) |
接口说明
人脸检测
检测请求图片中的人脸,返回人脸位置、72个关键点坐标、及人脸相关属性信息。
检测响应速度,与图片中人脸数量相关,人脸数量较多时响应时间会有些许延长。
典型应用场景:如人脸属性分析,基于人脸关键点的加工分析,人脸营销活动等。
五官位置会标记具体坐标;72个关键点坐标也包含具体坐标,但不包含对应位置的详细位置描述。
$image = file_get_contents('example.jpg');
// 调用人脸检测
$client->detect($image);
// 如果有可选参数
$options = array();
$options["max_face_num"] = 2;
$options["face_fields"] = "age";
// 带参数调用人脸检测
$client->detect($image, $options);
人脸检测 请求参数详情
参数名称 | 是否必选 | 类型 | 默认值 | 说明 |
---|---|---|---|---|
image | 是 | string | 图像数据,base64编码,要求base64编码后大小不超过4M,最短边至少15px,最长边最大4096px,支持jpg/png/bmp格式 | |
max_face_num | 否 | string | 1 | 最多处理人脸数目,默认值1 |
face_fields | 否 | string | 包括age,beauty,expression,faceshape,gender,glasses,landmark,qualities信息,逗号分隔,默认只返回人脸框、概率和旋转角度 |
人脸检测 返回数据参数详情
参数 | 类型 | 必选 | 说明 |
---|---|---|---|
log_id | uint64 | 是 | 日志id |
result_num | uint32 | 是 | 人脸数目 |
result | object[] | 是 | 人脸属性对象的集合 |
+age | double | 否 | 年龄。face_fields包含age时返回 |
+beauty | double | 否 | 美丑打分,范围0-100,越大表示越美。face_fields包含beauty时返回 |
+location | object | 是 | 人脸在图片中的位置 |
++left | uint32 | 是 | 人脸区域离左边界的距离 |
++top | uint32 | 是 | 人脸区域离上边界的距离 |
++width | uint32 | 是 | 人脸区域的宽度 |
++height | uint32 | 是 | 人脸区域的高度 |
+face_probability | double | 是 | 人脸置信度,范围0-1 |
+rotation_angle | int32 | 是 | 人脸框相对于竖直方向的顺时针旋转角,[-180,180] |
+yaw | double | 是 | 三维旋转之左右旋转角[-90(左), 90(右)] |
+pitch | double | 是 | 三维旋转之俯仰角度[-90(上), 90(下)] |
+roll | double | 是 | 平面内旋转角[-180(逆时针), 180(顺时针)] |
+expression | uint32 | 否 | 表情,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 | uint32 | 否 | 是否带眼镜,0-无眼镜,1-普通眼镜,2-墨镜。face_fields包含glasses时返回 |
+glasses_probability | double | 否 | 眼镜置信度,范围0~1。face_fields包含glasses时返回 |
+landmark | object[] | 否 | 4个关键点位置,左眼中心、右眼中心、鼻尖、嘴中心。face_fields包含landmark时返回 |
++x | uint32 | 否 | x坐标 |
++y | uint32 | 否 | y坐标 |
+landmark72 | object[] | 否 | 72个特征点位置,示例图 。face_fields包含landmark时返回 |
++x | uint32 | 否 | x坐标 |
++y | uint32 | 否 | y坐标 |
+qualities | object | 否 | 人脸质量信息。face_fields包含qualities时返回 |
++occlusion | object | 是 | 人脸各部分遮挡的概率,[0, 1],0表示完整,1表示不完整 |
+++left_eye | double | 是 | 左眼 |
+++right_eye | double | 是 | 右眼 |
+++nose | double | 是 | 鼻子 |
+++mouth | double | 是 | 嘴 |
+++left_cheek | double | 是 | 左脸颊 |
+++right_cheek | double | 是 | 右脸颊 |
+++chin | double | 是 | 下巴 |
++blur | double | 是 | 人脸模糊程度,[0, 1]。0表示清晰,1表示模糊 |
++illumination | - | 是 | 取值范围在[0,255],表示脸部区域的光照程度 |
++completeness | - | 是 | 人脸完整度,[0, 1]。0表示完整,1表示不完整 |
++type | object | 是 | 真实人脸/卡通人脸置信度 |
+++human | - | 是 | 真实人脸置信度,[0, 1] |
+++cartoon | - | 是 | 卡通人脸置信度,[0, 1] |
人脸检测 返回示例
{
"result_num": 1,
"result": [
{
"location": {
"left": 117,
"top": 131,
"width": 172,
"height": 170
},
"face_probability": 1,
"rotation_angle": 2,
"yaw": -0.34859421849251,
"pitch": 2.3033397197723,
"roll": 1.9135693311691,
"landmark": [
{
"x": 161.74819946289,
"y": 163.30244445801
},
...
],
"landmark72": [
{
"x": 115.86531066895,
"y": 170.0546875
},
...
],
"age": 29.298097610474,
"beauty": 55.128883361816,
"expression": 1,
"expression_probablity": 0.5543018579483,
"gender": "male",
"gender_probability": 0.99979132413864,
"glasses": 0,
"glasses_probability": 0.99999964237213,
"qualities": {
"occlusion": {
"left_eye": 0,
"right_eye": 0,
"nose": 0,
"mouth": 0,
"left_cheek": 0.0064102564938366,
"right_cheek": 0.0057411273010075,
"chin": 0
},
"blur": 1.1886881756684e-10,
"illumination": 141,
"completeness": 1,
"type": {
"human": 0.99935841560364,
"cartoon": 0.00064159056637436
}
}
}
],
"log_id": 2493878179101621
}
质量判断
可通过人脸检测接口,基于以下字段和对应阈值,进行质量检测的判断,以保证人脸质量符合后续业务操作要求。
指标 | 字段与解释 | 推荐数值界限 |
---|---|---|
遮挡范围 | occlusion(0~1),0为无遮挡,1是完全遮挡 含有多个具体子字段,表示脸部多个部位 通常用作判断头发、墨镜、口罩等遮挡 |
left_eye : 0.6, #左眼被遮挡的阈值 right_eye : 0.6, #右眼被遮挡的阈值 nose : 0.7, #鼻子被遮挡的阈值 mouth : 0.7, #嘴巴被遮挡的阈值 left_check : 0.8, #左脸颊被遮挡的阈值 right_check : 0.8, #右脸颊被遮挡的阈值 chin_contour : 0.6, #下巴被遮挡阈值 |
模糊度范围 | Blur(0~1),0是最清晰,1是最模糊 | 小于0.7 |
光照范围 | illumination(0~255) 脸部光照的灰度值,0表示光照不好 以及对应客户端SDK中,YUV的Y分量 |
大于40 |
姿态角度 | Pitch:三维旋转之俯仰角度[-90(上), 90(下)] Roll:平面内旋转角[-180(逆时针), 180(顺时针)] Yaw:三维旋转之左右旋转角[-90(左), 90(右)] |
分别小于20度 |
人脸完整度 | completeness(0或1),0代表完整,1代表不完整 | 小于0.4 |
人脸大小 | 人脸部分的大小 建议长宽像素值范围:80*80~200*200 |
人脸部分不小于100*100像素 |
人脸比对
该请求用于比对多张图片中的人脸相似度并返回两两比对的得分,可用于判断两张脸是否是同一人的可能性大小。
典型应用场景:如人证合一验证,用户认证等,可与您现有的人脸库进行比对验证。
说明:支持对比对的两张图片做在线活体检测
$images = array(
file_get_contents('example0.jpg'),
file_get_contents('example1.jpg'),
);
// 调用人脸比对
$client->match($images);
// 如果有可选参数
$options = array();
$options["ext_fields"] = "qualities";
$options["image_liveness"] = ",faceliveness";
$options["types"] = "7,13";
// 带参数调用人脸比对
$client->match($images, $options);
人脸比对 请求参数详情
参数名称 | 是否必选 | 类型 | 可选值范围 | 说明 |
---|---|---|---|---|
images | 是 | string | base64编码后的多张图片数据,半角逗号分隔,单次请求总共最大20M | |
ext_fields | 否 | string | 返回质量信息,取值固定:目前支持qualities(质量检测)。(对所有图片都会做改处理) | |
image_liveness | 否 | string | faceliveness,faceliveness - 对比对的两张图片都做活体检测 ,faceliveness - 对第一张图片不做活体检测、第二张图做活体检测faceliveness, - 对第一张图片做活体检测、第二张图不做活体检测 |
返回的活体信息,“faceliveness,faceliveness” 表示对比对的两张图片都做活体检测;“,faceliveness” 表示对第一张图片不做活体检测、第二张图做活体检测;“faceliveness,” 表示对第一张图片做活体检测、第二张图不做活体检测; 注:需要用于判断活体的图片,图片中的人脸像素面积需要不小于100px*100px,人脸长宽与图片长宽比例,不小于1/3 |
types | 否 | string | 请求对比的两张图片的类型,示例:“7,13” 12表示带水印证件照:一般为带水印的小图,如公安网小图 7表示生活照:通常为手机、相机拍摄的人像图片、或从网络获取的人像图片等 13表示证件照片:如拍摄的身份证、工卡、护照、学生证等证件图片,注:需要确保人脸部分不可太小,通常为100px*100px |
人脸比对 返回数据参数详情
字段 | 必选 | 类型 | 说明 |
---|---|---|---|
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.49999。单帧活体检测参考阈值0.393241,超过此分值以上则可认为是活体。注意:活体检测接口主要用于判断是否为二次翻拍,需要限制用户为当场拍照获取图片;推荐配合客户端SDK有动作校验活体使用 |
人脸比对 返回示例
//请求两张图片
{
"log_id": 73473737,
"result_num":1,
"result": [
{
"index_i": 0,
"index_j": 1,
"score": 44.3
}
]
}
人脸识别
用于计算指定组内用户,与上传图像中人脸的相似度。识别前提为您已经创建了一个人脸库。
典型应用场景:如人脸闸机,考勤签到,安防监控等。
说明:人脸识别返回值不直接判断是否是同一人,只返回用户信息及相似度分值。
说明:推荐可判断为同一人的相似度分值为80,您也可以根据业务需求选择更合适的阈值。
$groupId = "group1,group2";
$image = file_get_contents('example.jpg');
// 调用人脸识别
$client->identifyUser($groupId, $image);
// 如果有可选参数
$options = array();
$options["ext_fields"] = "faceliveness";
$options["user_top_num"] = 3;
// 带参数调用人脸识别
$client->identifyUser($groupId, $image, $options);
人脸识别 请求参数详情
参数名称 | 是否必选 | 类型 | 默认值 | 说明 |
---|---|---|---|---|
group_id | 是 | string | 用户组id,标识一组用户(由数字、字母、下划线组成),长度限制128B。如果需要将一个uid注册到多个group下,group_id需要用多个逗号分隔,每个group_id长度限制为48个英文字符。注:group无需单独创建,注册用户时则会自动创建group。 产品建议:根据您的业务需求,可以将需要注册的用户,按照业务划分,分配到不同的group下,例如按照会员手机尾号作为groupid,用于刷脸支付、会员计费消费等,这样可以尽可能控制每个group下的用户数与人脸数,提升检索的准确率 |
|
image | 是 | string | 图像数据,base64编码,要求base64编码后大小不超过4M,最短边至少15px,最长边最大4096px,支持jpg/png/bmp格式 | |
ext_fields | 否 | string | 特殊返回信息,多个用逗号分隔,取值固定: 目前支持faceliveness(活体检测)。注:需要用于判断活体的图片,图片中的人脸像素面积需要不小于100px*100px,人脸长宽与图片长宽比例,不小于1/3 | |
user_top_num | 否 | string | 1 | 返回用户top数,默认为1,最多返回5个 |
人脸识别 返回数据参数详情
字段 | 必选 | 类型 | 说明 |
---|---|---|---|
log_id | 是 | uint64 | 请求唯一标识码,随机数 |
result_num | 是 | uint32 | 返回结果数目,即:result数组中元素个数 |
ext_info | 否 | array | 对应参数中的ext_fields |
+faceliveness | 否 | string | 活体分数,如0.49999。单帧活体检测参考阈值0.393241,超过此分值以上则可认为是活体。注意:活体检测接口主要用于判断是否为二次翻拍,需要限制用户为当场拍照获取图片;推荐配合客户端SDK有动作校验活体使用 |
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,这增加了验证安全度,但也增加了复杂度,具体使用哪个接口需要视您的业务场景判断。
说明:请求参数中,新增在线活体检测
$uid = "user1";
$groupId = "group1,group2";
$image = file_get_contents('example.jpg');
// 调用人脸认证
$client->verifyUser($uid, $groupId, $image);
// 如果有可选参数
$options = array();
$options["top_num"] = 3;
$options["ext_fields"] = "faceliveness";
// 带参数调用人脸认证
$client->verifyUser($uid, $groupId, $image, $options);
人脸认证 请求参数详情
参数名称 | 是否必选 | 类型 | 默认值 | 说明 |
---|---|---|---|---|
uid | 是 | string | 用户id(由数字、字母、下划线组成),长度限制128B | |
group_id | 是 | string | 用户组id,标识一组用户(由数字、字母、下划线组成),长度限制128B。如果需要将一个uid注册到多个group下,group_id需要用多个逗号分隔,每个group_id长度限制为48个英文字符。注:group无需单独创建,注册用户时则会自动创建group。 产品建议:根据您的业务需求,可以将需要注册的用户,按照业务划分,分配到不同的group下,例如按照会员手机尾号作为groupid,用于刷脸支付、会员计费消费等,这样可以尽可能控制每个group下的用户数与人脸数,提升检索的准确率 |
|
image | 是 | string | 图像数据,base64编码,要求base64编码后大小不超过4M,最短边至少15px,最长边最大4096px,支持jpg/png/bmp格式 | |
top_num | 否 | string | 1 | 返回用户top数,默认为1 |
ext_fields | 否 | string | 特殊返回信息,多个用逗号分隔,取值固定: 目前支持faceliveness(活体检测)。注:需要用于判断活体的图片,图片中的人脸像素面积需要不小于100px*100px,人脸长宽与图片长宽比例,不小于1/3 |
人脸认证 返回数据参数详情
字段 | 必选 | 类型 | 说明 |
---|---|---|---|
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。单帧活体检测参考阈值0.393241,超过此分值以上则可认为是活体。活体检测接口主要用于判断是否为二次翻拍,需要限制用户为当场拍照获取图片;推荐配合客户端SDK有动作校验活体使用 |
人脸认证 返回示例
{
"log_id": 73473737,
"result_num":2,
"result": [
99.3,
83.6
]
}
M:N 识别
待识别的图片中,存在多张人脸的情况下,支持在一个人脸库中,一次请求,同时返回图片中所有人脸的识别结果。
$groupId = "group1,group2";
$image = file_get_contents('example.jpg');
// 调用M:N 识别
$client->multiIdentify($groupId, $image);
// 如果有可选参数
$options = array();
$options["ext_fields"] = "faceliveness";
$options["detect_top_num"] = 3;
$options["user_top_num"] = 2;
// 带参数调用M:N 识别
$client->multiIdentify($groupId, $image, $options);
M:N 识别 请求参数详情
参数名称 | 是否必选 | 类型 | 默认值 | 说明 |
---|---|---|---|---|
group_id | 是 | string | 用户组id,标识一组用户(由数字、字母、下划线组成),长度限制128B。如果需要将一个uid注册到多个group下,group_id需要用多个逗号分隔,每个group_id长度限制为48个英文字符。注:group无需单独创建,注册用户时则会自动创建group。 产品建议:根据您的业务需求,可以将需要注册的用户,按照业务划分,分配到不同的group下,例如按照会员手机尾号作为groupid,用于刷脸支付、会员计费消费等,这样可以尽可能控制每个group下的用户数与人脸数,提升检索的准确率 |
|
image | 是 | string | 图像数据,base64编码,要求base64编码后大小不超过4M,最短边至少15px,最长边最大4096px,支持jpg/png/bmp格式 | |
ext_fields | 否 | string | 特殊返回信息,多个用逗号分隔,取值固定: 目前支持faceliveness(活体检测)。注:需要用于判断活体的图片,图片中的人脸像素面积需要不小于100px*100px,人脸长宽与图片长宽比例,不小于1/3 | |
detect_top_num | 否 | string | 1 | 检测多少个人脸进行比对,默认值1(最对返回10个) |
user_top_num | 否 | string | 1 | 返回识别结果top人数”,当同一个人有多张图片时,只返回比对最高的1个分数(即,scores参数只有一个值),默认为1(最多返回20个) |
M:N 识别 返回数据参数详情
参数 | 字段 | 必选 | 类型 | 说明 |
---|---|---|---|---|
log_id | - | 是 | uint32 | 请求标识码,随机数,唯一 |
result_num | - | 是 | float | 返回结果数目,即:result数组中元素个数(PS:最终返回的个数是小于等于 “实际检测到的人脸数” * “每个人脸匹配的top人数”) |
ext_info | - | 否 | array | 对应参数中的ext_fields |
- | faceliveness | 否 | string | 活体检测分数,单帧活体检测参考阈值0.393241,超过此分值以上则可认为是活体。注意:活体检测接口主要用于判断是否为二次翻拍,需要限制用户为当场拍照获取图片;推荐配合客户端SDK有动作校验活体使用 |
result | - | 是 | array(object) | - |
- | group_id | 是 | string | 对应的这个用户的group_id |
- | uid | 是 | string | 匹配到的用户id |
- | user_info | 是 | string | 注册时的用户信息 |
- | scores | 是 | array(double) | 结果数组,数组元素为匹配得分,得分[0,100.0];个数取决于user_top_num的设定。推荐80分以上即可判断为同一人 |
- | position | 是 | object | 人脸位置,如{top:111,left:222,width:333,height:444,degree:20} |
M:N 识别 返回示例
{
"log_id": 73473737,
"result_num":1,
"result": [
{
"group_id" : "test1",
"uid": "u333333",
"user_info": "Test User",
"position":{"left":726.99188232422,"top":288.37701416016,"width":44,"height":42,"degree":-4,"prob":0.91117089986801},
"scores": [
99.3
]
},
{
"group_id" : "test1",
"uid": "u2222222",
"user_info": "Test User",
"position":{"left":726.99188232422,"top":288.37701416016,"width":44,"height":42,"degree":-4,"prob":0.91117089986801},
"scores": [
82.3
]
}
]
}
人脸注册
用于从人脸库中新增用户,可以设定多个用户所在组,及组内用户的人脸图片,
典型应用场景:构建您的人脸库,如会员人脸注册,已有用户补全人脸信息等。
人脸库、用户组、用户、用户下的人脸层级关系如下所示:
|- 人脸库
|- 用户组一
|- 用户01
|- 人脸
|- 用户02
|- 人脸
|- 人脸
....
....
|- 用户组二
|- 用户组三
|- 用户组四
....
关于人脸库的设置限制
- 每个开发者账号可以创建100个appid;
- 每个appid对应一个人脸库,且不同appid之间,人脸库互不相通;
- 每个人脸库下,可以创建多个用户组,用户组(group)数量没有限制;
- 每个用户组(group)下,可添加最多无限张人脸,无限个uid;
- 每个用户(uid)所能注册的最大人脸数量没有限制;
为了保证识别效果,请控制注册人脸的质量(通过/detect
人脸检测接口判断),具体参数可详见下表所示:
质量判断
可通过人脸检测接口,基于以下字段和对应阈值,进行质量检测的判断,以保证人脸质量符合后续业务操作要求。
指标 | 字段与解释 | 推荐数值界限 |
---|---|---|
遮挡范围 | occlusion(0~1),0为无遮挡,1是完全遮挡 含有多个具体子字段,表示脸部多个部位 通常用作判断头发、墨镜、口罩等遮挡 |
left_eye : 0.6, #左眼被遮挡的阈值 right_eye : 0.6, #右眼被遮挡的阈值 nose : 0.7, #鼻子被遮挡的阈值 mouth : 0.7, #嘴巴被遮挡的阈值 left_check : 0.8, #左脸颊被遮挡的阈值 right_check : 0.8, #右脸颊被遮挡的阈值 chin_contour : 0.6, #下巴被遮挡阈值 |
模糊度范围 | Blur(0~1),0是最清晰,1是最模糊 | 小于0.7 |
光照范围 | illumination(0~255) 脸部光照的灰度值,0表示光照不好 以及对应客户端SDK中,YUV的Y分量 |
大于40 |
姿态角度 | Pitch:三维旋转之俯仰角度[-90(上), 90(下)] Roll:平面内旋转角[-180(逆时针), 180(顺时针)] Yaw:三维旋转之左右旋转角[-90(左), 90(右)] |
分别小于20度 |
人脸完整度 | completeness(0或1),0为人脸溢出图像边界,1为人脸都在图像边界内 | 视业务逻辑判断 |
人脸大小 | 人脸部分的大小 建议长宽像素值范围:80*80~200*200 |
人脸部分不小于100*100像素 |
$uid = "user1";
$userInfo = "user's info";
$groupId = "group1,group2";
$image = file_get_contents('example.jpg');
// 调用人脸注册
$client->addUser($uid, $userInfo, $groupId, $image);
// 如果有可选参数
$options = array();
$options["action_type"] = "replace";
// 带参数调用人脸注册
$client->addUser($uid, $userInfo, $groupId, $image, $options);
人脸注册 请求参数详情
参数名称 | 是否必选 | 类型 | 默认值 | 说明 |
---|---|---|---|---|
uid | 是 | string | 用户id(由数字、字母、下划线组成),长度限制128B | |
user_info | 是 | string | 用户资料,长度限制256B | |
group_id | 是 | string | 用户组id,标识一组用户(由数字、字母、下划线组成),长度限制128B。如果需要将一个uid注册到多个group下,group_id需要用多个逗号分隔,每个group_id长度限制为48个英文字符。注:group无需单独创建,注册用户时则会自动创建group。 产品建议:根据您的业务需求,可以将需要注册的用户,按照业务划分,分配到不同的group下,例如按照会员手机尾号作为groupid,用于刷脸支付、会员计费消费等,这样可以尽可能控制每个group下的用户数与人脸数,提升检索的准确率 |
|
image | 是 | string | 图像base64编码,每次仅支持单张图片,图片编码后大小不超过10M。为保证后续识别的效果较佳,建议注册的人脸,为用户正面人脸。 | |
action_type | 否 | string | append | 参数包含append、replace。如果为“replace”,则每次注册时进行替换replace(新增或更新)操作,默认为append操作。例如:uid在库中已经存在时,对此uid重复注册时,新注册的图片默认会追加到该uid下,如果手动选择action_type:replace ,则会用新图替换库中该uid下所有图片。 |
人脸注册 返回数据参数详情
字段 | 是否必选 | 类型 | 说明 |
---|---|---|---|
log_id | 是 | uint64 | 请求唯一标识码,随机数 |
人脸注册 返回示例
// 注册成功
{
"log_id": 73473737,
}
// 注册发生错误
{
"error_code": 216616,
"log_id": 674786177,
"error_msg": "image exist"
}
人脸更新
用于对人脸库中指定用户,更新其下的人脸图像。
说明:针对一个uid执行更新操作,新上传的人脸图像将覆盖此uid原有所有图像。
说明:执行更新操作,如果该uid不存在时,会返回错误。如果添加了action_type:replace,则不会报错,并自动注册该uid,操作结果等同注册新用户。
$uid = "user1";
$userInfo = "user's info";
$groupId = "group1";
$image = file_get_contents('example.jpg');
// 调用人脸更新
$client->updateUser($uid, $userInfo, $groupId, $image);
// 如果有可选参数
$options = array();
$options["action_type"] = "replace";
// 带参数调用人脸更新
$client->updateUser($uid, $userInfo, $groupId, $image, $options);
人脸更新 请求参数详情
参数名称 | 是否必选 | 类型 | 默认值 | 说明 |
---|---|---|---|---|
uid | 是 | string | 用户id(由数字、字母、下划线组成),长度限制128B | |
user_info | 是 | string | 用户资料,长度限制256B | |
group_id | 是 | string | 更新指定groupid下uid对应的信息 | |
image | 是 | string | 图像数据,base64编码,要求base64编码后大小不超过4M,最短边至少15px,最长边最大4096px,支持jpg/png/bmp格式 | |
action_type | 否 | string | append | 目前仅支持replace,uid不存在时,不报错,会自动变为注册操作;未选择该参数时,如果uid不存在会提示错误 |
人脸更新 返回数据参数详情
字段 | 是否必选 | 类型 | 说明 |
---|---|---|---|
log_id | 是 | uint64 | 请求唯一标识码,随机数 |
人脸更新 返回示例
// 更新成功
{
"log_id": 73473737,
}
// 更新发生错误
{
"error_code": 216612,
"log_id": 1137508902,
"error_msg": "user not exist"
}
人脸删除
用于从人脸库中删除一个用户。
人脸删除注意事项:
- 删除的内容,包括用户所有图像和身份信息;
- 如果一个uid存在于多个用户组内,将会同时将从各个组中把用户删除
- 如果指定了group_id,则只删除此group下的uid相关信息
$uid = "user1";
// 调用人脸删除
$client->deleteUser($uid);
// 如果有可选参数
$options = array();
$options["group_id"] = "group1";
// 带参数调用人脸删除
$client->deleteUser($uid, $options);
人脸删除 请求参数详情
参数名称 | 是否必选 | 类型 | 说明 |
---|---|---|---|
uid | 是 | string | 用户id(由数字、字母、下划线组成),长度限制128B |
group_id | 否 | string | 删除指定groupid下uid对应的信息 |
人脸删除 返回数据参数详情
字段 | 是否必选 | 类型 | 说明 |
---|---|---|---|
log_id | 是 | uint64 | 请求唯一标识码,随机数 |
人脸删除 返回示例
// 删除成功
{
"log_id": 73473737,
}
// 删除发生错误
{
"error_code": 216612,
"log_id": 1137508902,
"error_msg": "user not exist"
}
用户信息查询
用于查询人脸库中某用户的详细信息。
$uid = "user1";
// 调用用户信息查询
$client->getUser($uid);
// 如果有可选参数
$options = array();
$options["group_id"] = "group1";
// 带参数调用用户信息查询
$client->getUser($uid, $options);
用户信息查询 请求参数详情
参数名称 | 是否必选 | 类型 | 说明 |
---|---|---|---|
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_num” : 2
"result": {
[
"uid": "testuser2",
"user_info": "registed user info ...",
"group_id": "grep1",
],
[
"uid": "testuser2",
"user_info": "registed user info2 ...",
"group_id": "grep2",
],
},
"log_id": 2979357502
}
组列表查询
用于查询用户组的列表。
// 调用组列表查询
$client->getGroupList();
// 如果有可选参数
$options = array();
$options["start"] = 0;
$options["num"] = 50;
// 带参数调用组列表查询
$client->getGroupList(, $options);
组列表查询 请求参数详情
参数名称 | 是否必选 | 类型 | 默认值 | 说明 |
---|---|---|---|---|
start | 否 | string | 0 | 默认值0,起始序号 |
num | 否 | string | 100 | 返回数量,默认值100,最大值1000 |
组列表查询 返回数据参数详情
字段 | 是否必选 | 类型 | 说明 |
---|---|---|---|
result_num | 是 | number | 返回个数 |
result | 是 | array(string) | group_id列表 |
组列表查询 返回示例
{
"result_num": 2,
"result": [
"grp1",
"grp2"
],
"log_id": 3314921889
}
组内用户列表查询
用于查询指定用户组中的用户列表。
$groupId = "group1";
// 调用组内用户列表查询
$client->getGroupUsers($groupId);
// 如果有可选参数
$options = array();
$options["start"] = 0;
$options["num"] = 50;
// 带参数调用组内用户列表查询
$client->getGroupUsers($groupId, $options);
组内用户列表查询 请求参数详情
参数名称 | 是否必选 | 类型 | 默认值 | 说明 |
---|---|---|---|---|
group_id | 是 | string | 用户组id(由数字、字母、下划线组成),长度限制128B | |
start | 否 | string | 0 | 默认值0,起始序号 |
num | 否 | string | 100 | 返回数量,默认值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"
}
]
}
组间复制用户
用于将已经存在于人脸库中的用户复制到一个新的组。
说明:并不是向一个指定组内添加用户,而是直接从其它组复制用户信息 如果需要注册用户,请直接使用人脸注册接口
$srcGroupId = "group1";
$groupId = "group1,group2";
$uid = "user1";
// 调用组间复制用户
$client->addGroupUser($srcGroupId, $groupId, $uid);
组间复制用户 请求参数详情
参数名称 | 是否必选 | 类型 | 说明 |
---|---|---|---|
src_group_id | 是 | string | 从指定group里复制信息 |
group_id | 是 | string | 用户组id,标识一组用户(由数字、字母、下划线组成),长度限制128B。如果需要将一个uid注册到多个group下,group_id需要用多个逗号分隔,每个group_id长度限制为48个英文字符。注:group无需单独创建,注册用户时则会自动创建group。 产品建议:根据您的业务需求,可以将需要注册的用户,按照业务划分,分配到不同的group下,例如按照会员手机尾号作为groupid,用于刷脸支付、会员计费消费等,这样可以尽可能控制每个group下的用户数与人脸数,提升检索的准确率 |
uid | 是 | string | 用户id(由数字、字母、下划线组成),长度限制128B |
组间复制用户 返回数据参数详情
字段 | 是否必选 | 类型 | 说明 |
---|---|---|---|
log_id | 是 | uint64 | 请求标识码,随机数,唯一 |
组间复制用户 返回示例
// 正确返回值
{
"log_id": 3314921889,
}
// 发生错误时返回值
{
"error_code": 216100,
"log_id": 3111284097,
"error_msg": "already add"
}
组内删除用户
用于将用户从某个组中删除,但不会删除用户在其它组的信息。
说明:当用户仅属于单个分组时,本接口将返回错误,请使用人脸删除接口
$groupId = "group1,group2";
$uid = "user1";
// 调用组内删除用户
$client->deleteGroupUser($groupId, $uid);
组内删除用户 请求参数详情
参数名称 | 是否必选 | 类型 | 说明 |
---|---|---|---|
group_id | 是 | string | 用户组id,标识一组用户(由数字、字母、下划线组成),长度限制128B。如果需要将一个uid注册到多个group下,group_id需要用多个逗号分隔,每个group_id长度限制为48个英文字符。注:group无需单独创建,注册用户时则会自动创建group。 产品建议:根据您的业务需求,可以将需要注册的用户,按照业务划分,分配到不同的group下,例如按照会员手机尾号作为groupid,用于刷脸支付、会员计费消费等,这样可以尽可能控制每个group下的用户数与人脸数,提升检索的准确率 |
uid | 是 | string | 用户id(由数字、字母、下划线组成),长度限制128B |
组内删除用户 返回数据参数详情
字段 | 是否必选 | 类型 | 说明 |
---|---|---|---|
log_id | 是 | uint64 | 请求标识码,随机数,唯一 |
组内删除用户 返回示例
// 正确返回值
{
"log_id": 3314921889,
}
// 发生错误时返回值
{
"error_code": 216619,
"log_id": 815967402,
"error_msg": "user must be in one group at least"
}
身份验证
质量检测(可选)活体检测(可选)公安验证(必选)
$image = file_get_contents('example.jpg');
$idCardNumber = "110233112299822211";
$name = "张三";
// 调用身份验证
$client->personVerify($image, $idCardNumber, $name);
// 如果有可选参数
$options = array();
$options["quality"] = "use";
$options["quality_conf"] = "{\"left_eye\": 0.6, \"right_eye\": 0.6}";
$options["faceliveness"] = "use";
$options["faceliveness_conf"] = "{\"faceliveness\": 0.834963}";
$options["ext_fields"] = "qualities";
// 带参数调用身份验证
$client->personVerify($image, $idCardNumber, $name, $options);
身份验证 请求参数详情
参数名称 | 是否必选 | 类型 | 说明 |
---|---|---|---|
image | 是 | string | 图像数据,base64编码,要求base64编码后大小不超过4M,最短边至少15px,最长边最大4096px,支持jpg/png/bmp格式 |
id_card_number | 是 | string | 身份证号(真实身份证号号码)。我们的服务端会做格式校验,并通过错误码返回,但是为了您的产品反馈体验更及时,建议在产品前端做一下号码格式校验与反馈 |
name | 是 | string | utf8,姓名(真实姓名,和身份证号匹配) |
quality | 否 | string | 判断图片中的人脸质量是否符合条件。use表示需要做质量控制,质量不符合条件的照片会被直接拒绝 |
quality_conf | 否 | string | 人脸质量检测中每一项指标的具体阈值设定,json串形式,当指定quality:use时生效 |
faceliveness | 否 | string | 判断活体值是否达标。use表示需要做活体检测,低于活体阈值的照片会直接拒绝 |
faceliveness_conf | 否 | string | 人脸活体检测的阈值设定,json串形式,当指定faceliveness:use时生效。默认使用的阈值如下:{faceliveness:0.834963} |
ext_fields | 否 | string | 可选项为faceliveness,qualities。选择具体的项,则返回参数中将会显示相应的扩展字段。如faceliveness表示返回结果中包含活体相关内容,qualities表示返回结果中包含质量检测相关内容 |
身份验证 返回数据参数详情
参数 | 必须 | 类型 | 说明 |
---|---|---|---|
log_id | 是 | uint64 | 日志id |
result | 是 | float | 与公安小图相似度可能性,用于验证生活照与公安小图是否为同一人,有正常分数时为[0~1],推荐阈值0.8,超过即判断为同一人 |
ext_info | 否 | string | 拓展信息json串,只有选择了ext_fields 时才会返回具体信息。选择faceliveness 返回具体活体分值信息,选择qualities 返回人脸质量检测信息。两者可以同时选择,半角逗号分割。 |
+faceliveness | 否 | string | 活体检测值,单帧图片建议阈值,小于此值则认为不是活体,超过则判断为活体 |
+qualities | 否 | string | 质量检测结果 |
++occlusion | 否 | string | 人脸遮挡情况 |
+++left_eye | 否 | string | 左眼被遮挡的比例,取值范围[0~1],数值越大遮挡越多;小于阈值时有返回,默认阈值0.6 |
+++right_eye | 否 | string | 右眼被遮挡的比例,取值范围[0~1],数值越大遮挡越多;小于阈值时有返回,默认阈值0.6 |
+++nose | 否 | string | 鼻子被遮挡的比例,取值范围[0~1],数值越大遮挡越多;小于阈值时有返回,默认阈值0.7 |
+++mouth | 否 | string | 嘴巴被遮挡的比例,取值范围[0~1],数值越大遮挡越多;小于阈值时有返回,默认阈值0.7 |
+++left_cheek | 否 | string | 左脸颊被遮挡的比例,取值范围[0~1],数值越大遮挡越多;小于阈值时有返回,默认阈值0.8 |
+++right_cheek | 否 | string | 右脸颊被遮挡的比例,取值范围[0~1],数值越大遮挡越多;小于阈值时有返回,默认阈值0.8 |
+++chin | 否 | string | 下巴被遮挡的比例,取值范围[0~1],数值越大遮挡越多;小于阈值时有返回,默认阈值0.8 |
++blur | 否 | string | 人脸模糊度阈值,取值范围[0~1],数值越大越模糊;小于阈值时有返回,默认阈值0.7 |
++illumination | 否 | string | 脸部光照的灰度值阈值,取值范围[0~255],数值越大光照越强;大于阈值时有返回,默认阈值30 |
++completeness | 否 | string | 人脸完整度,0或1, 0为人脸溢出图像边界,1为人脸都在图像边界内 |
身份验证 返回示例
{
"result":0.03419,
"ext_info":{
"faceliveness":0.834963
},
"log_id":772889134072410
}
在线活体检测
人脸基础信息,人脸质量检测,基于图片的活体检测
$image = file_get_contents('example.jpg');
// 调用在线活体检测
$client->faceverify($image);
// 如果有可选参数
$options = array();
$options["max_face_num"] = 2;
$options["face_fields"] = "qualities";
// 带参数调用在线活体检测
$client->faceverify($image, $options);
在线活体检测 请求参数详情
参数名称 | 是否必选 | 类型 | 默认值 | 说明 |
---|---|---|---|---|
image | 是 | string | 图像数据,base64编码,要求base64编码后大小不超过4M,最短边至少15px,最长边最大4096px,支持jpg/png/bmp格式 | |
max_face_num | 否 | string | 1 | 最多处理人脸数目,默认值1 |
face_fields | 否 | string | 如不选择此项,返回结果默认只有人脸框、概率和旋转角度。可选参数为qualities、faceliveness。qualities:图片质量相关判断;faceliveness:活体判断。如果两个参数都需要选择,请使用半角逗号分隔。 |
在线活体检测 返回数据参数详情
参数 | 类型 | 是否必须 | 说明 |
---|---|---|---|
log_id | uint64 | 是 | 日志id |
result_num | uint32 | 是 | 人脸数目 |
result | object[] | 是 | 人脸属性对象的集合 |
+faceliveness | float | 否 | 活体分数,face_fields包括qualities时返回 |
+location | bject | 是 | 人脸在图片中的位置 |
++left | uint32 | 是 | 人脸区域离左边界的距离 |
++top | uint32 | 是 | 人脸区域离上边界的距离 |
++width | uint32 | 是 | 人脸区域的宽度 |
++height | uint32 | 是 | 人脸区域的高度 |
+face_probability | double | 是 | 人脸置信度,范围0-1 |
+rotation_angle | int32 | 是 | 人脸框相对于竖直方向的顺时针旋转角,[-180,180] |
+yaw | double | 是 | 三维旋转之左右旋转角[-90(左), 90(右)] |
+pitch | double | 是 | 三维旋转之俯仰角度[-90(上), 90(下)] |
+roll | double | 是 | 平面内旋转角[-180(逆时针), 180(顺时针)] |
+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 | 是 | 下巴 |
++blur | double | 是 | 人脸模糊程度,[0, 1]。0表示清晰,1表示模糊 |
++illumination | double | 是 | 取值范围在[0,255],表示脸部区域的光照程度 |
++completeness | double | 是 | 人脸完整度,[0, 1]。0表示完整,1表示不完整 |
++type | object | 是 | 真实人脸/卡通人脸置信度 |
+++human | double | 是 | 真实人脸置信度,[0, 1] |
+++cartoon | double | 是 | 卡通人脸置信度,[0, 1] |
在线活体检测 返回示例
{
log_id: 1900901488032821,
result_num: 1,
result: [
{
rotation_angle: 10,
yaw: 11.357421875,
faceliveness: 8.1253347161692e-05,
location: {
width: 96,
top: 73,
height: 96,
left: 283
},
qualities: {
illumination: 211,
occlusion: {
right_eye: 0,
left_eye: 0.039751552045345,
left_cheek: 0.12623985111713,
mouth: 0,
nose: 0,
chin: 0.037661049515009,
right_cheek: 0.024720622226596
},
completeness: 1,
type: {
cartoon: 0,
human: 0
},
blur: 2.5251445032182e-11
},
pitch: 1.0063140392303,
roll: 12.760620117188,
face_probability: 1
}
]
}
错误信息
错误返回格式
若请求错误,服务器将返回的JSON文本包含以下参数:
- error_code:错误码。
- error_msg:错误描述信息,帮助理解和解决发生的错误。
错误码
服务端返回的错误码
错误码 | 错误信息 | 描述 |
---|---|---|
4 | Open api request limit reached | 集群超限额 |
14 | IAM Certification failed | IAM鉴权失败,建议用户参照文档自查生成sign的方式是否正确,或换用控制台中ak sk的方式调用 |
17 | Open api daily request limit reached | 每天流量超限额 |
18 | Open api qps request limit reached | QPS超限额 |
19 | Open api total request limit reached | 请求总量超限额 |
100 | Invalid parameter | 无效参数 |
110 | Access token invalid or no longer valid | Access Token失效 |
111 | Access token expired | Access token过期 |
216015 | module closed | 模块关闭 |
216100 | invalid param | 参数异常 |
216101 | not enough param | 缺少必须的参数 |
216102 | service not support | 请求了不支持的服务,请检查调用的url |
216103 | param too long | 请求超长,一般为一次传入图片个数超过系统限制 |
216110 | appid not exist | appid不存在,请重新检查后台应用列表中的应用信息 |
216111 | invalid userid | userid信息非法,请检查对应的参数 |
216200 | empty image | 图片为空或者base64解码错误 |
216201 | image format error | 图片格式错误 |
216202 | image size error | 图片大小错误 |
216300 | db error | 数据库异常,少量发生时重试即可 |
216400 | backend error | 后端识别服务异常,可以根据具体msg查看错误原因 |
216401 | internal error | 内部错误 |
216402 | face not found | 未找到人脸,请检查图片是否含有人脸 |
216500 | unknown error | 未知错误 |
216611 | user not exist | 用户不存在,请确认该用户是否注册或注册已经生效(需要已经注册超过5s) |
216613 | fail to delete user record | 删除用户图片记录失败,重试即可 |
216614 | not enough images | 两两比对中图片数少于2张,无法比较 |
216615 | fail to process images | 服务处理该图片失败,发生后重试即可 |
216616 | image existed | 图片已存在 |
216617 | fail to add user | 新增用户图片失败 |
216618 | no user in group | 组内用户为空,确认该group是否存在或已经生效(需要已经注册超过5s) |
216631 | request add user overlimit | 本次请求添加的用户数量超限 |