C#-SDK
简介
Hi,您好,欢迎使用百度人脸识别服务。
本文档主要针对C#开发者,描述百度人脸识别接口服务的相关技术内容。如果您对文档内容有任何疑问,可以通过以下几种方式联系我们:
- 在百度云控制台内提交工单,咨询问题类型请选择人工智能服务;
- 如有疑问,进入AI社区交流:http://ai.baidu.com/forum/topic/list/165
接口能力
| 接口名称 | 接口能力简要描述 | 
|---|---|
| 人脸检测 | 检测人脸并定位,返回五官关键点,及人脸各属性值 | 
| 人脸比对 | 返回两两比对的人脸相似值 | 
| 人脸查找 | 在一个人脸集合中找到找到相似的人脸,由一系列接口组成,包括人脸识别、人脸认证、人脸库管理相关接口(人脸注册、人脸更新、人脸删除、用户信息查询、组列表查询、组内用户列表查询、组间复制用户、组内删除用户) | 
版本更新记录
| 上线日期 | 版本号 | 更新内容 | 
|---|---|---|
| 2019.4.17 | 3.6.11 | 人脸v3文档更新,新增N:M接口 | 
| 2018.5.10 | 3.5.1 | 细节修复 | 
| 2018.4.28 | 3.5.0 | 全面切换为人脸V3接口 | 
| 2018.4.9 | 3.4.0 | 新增.Net Core支持;新增身份证验证接口,在线活体检测接口 | 
| 2018.1.11 | 3.3.1 | 新增人脸识别N:M接口 | 
| 2017.12.21 | 3.3.0 | 接口升级 | 
| 2017.11.14 | 3.2.1 | 人脸检测接口升级 | 
| 2017.9.12 | 3.0.0 | 更新SDK打包方式:所有AI服务集成一个SDK | 
| 2017.4.1 | 1.0 | 第一版! | 
快速入门
安装人脸 C# SDK
支持平台:.Net Framework 3.5 4.0 4.5, .Net Core 2.0
方法一:使用Nuget管理依赖 (推荐)
在NuGet中搜索 Baidu.AI,安装最新版即可。
packet地址 https://www.nuget.org/packages/Baidu.AI/
方法二:下载安装
人脸 C# SDK目录结构
1Baidu.Aip
2    ├── net35
3    │   ├── AipSdk.dll             // 百度AI服务 windows 动态库
4    │   ├── AipSdk.xml             // 注释文件
5    │   └── Newtonsoft.Json.dll    // 第三方依赖
6    ├── net40
7    ├── net45
8    └── netstandard2.0
9        ├── AipSdk.deps.json
10        └── AipSdk.dll如果需要在 Unity 平台使用,可引用工程源码自行编译。
安装
1.在官方网站下载C# SDK压缩工具包。
2.解压后,将 AipSdk.dll 和 Newtonsoft.Json.dll 中添加为引用。
新建交互类
Baidu.Aip.Face.Face是人脸的交互类,为使用人脸的开发人员提供了一系列的交互方法。
用户可以参考如下代码新建一个交互类:
1// 设置APPID/AK/SK
2var APP_ID = "你的 App ID";
3var API_KEY = "你的 Api Key";
4var SECRET_KEY = "你的 Secret Key";
5
6var client = new Baidu.Aip.Face.Face(API_KEY, SECRET_KEY);
7client.Timeout = 60000;  // 修改超时时间在上面代码中,常量APP_ID在百度云控制台中创建,常量API_KEY与SECRET_KEY是在创建完毕应用后,系统分配给用户的,均为字符串,用于标识用户,为访问做签名验证,可在AI服务控制台中的应用列表中查看。
注意:如您以前是百度云的老用户,其中API_KEY对应百度云的“Access Key ID”,SECRET_KEY对应百度云的“Access Key Secret”。
接口说明
人脸检测
人脸检测:检测图片中的人脸并标记出位置信息;
1public void DetectDemo() {
2	var image = "取决于image_type参数,传入BASE64字符串或URL字符串或FACE_TOKEN字符串";
3	
4	var imageType = "BASE64";
5	
6	// 调用人脸检测,可能会抛出网络等异常,请使用try/catch捕获
7	var result = client.Detect(image, imageType);
8	Console.WriteLine(result);
9	// 如果有可选参数
10	var options = new Dictionary<string, object>{
11	    {"face_field", "age"},
12	    {"max_face_num", 2},
13	    {"face_type", "LIVE"},
14	    {"liveness_control", "LOW"}
15	};
16	// 带参数调用人脸检测
17	result = client.Detect(image, imageType, options);
18	Console.WriteLine(result);
19}人脸检测 请求参数详情
| 参数名称 | 是否必选 | 类型 | 默认值 | 说明 | 
|---|---|---|---|---|
| image | 是 | string | 图片信息(总数据大小应小于10M),图片上传方式根据image_type来判断 | |
| image_type | 是 | string | 图片类型 BASE64:图片的base64值,base64编码后的图片数据,编码后的图片大小不超过2M;URL:图片的 URL地址( 可能由于网络等原因导致下载图片时间过长);FACE_TOKEN: 人脸图片的唯一标识,调用人脸检测接口时,会为每个人脸图片赋予一个唯一的FACE_TOKEN,同一张图片多次检测得到的FACE_TOKEN是同一个 | |
| face_field | 否 | string | 包括age,expression,face_shape,gender,glasses,landmark,landmark150,quality,eye_status,emotion,face_type信息 逗号分隔. 默认只返回face_token、人脸框、概率和旋转角度 | |
| max_face_num | 否 | string | 1 | 最多处理人脸的数目,默认值为1,仅检测图片中面积最大的那个人脸;最大值10,检测图片中面积最大的几张人脸。 | 
| face_type | 否 | string | 人脸的类型 LIVE表示生活照:通常为手机、相机拍摄的人像图片、或从网络获取的人像图片等IDCARD表示身份证芯片照:二代身份证内置芯片中的人像照片 WATERMARK表示带水印证件照:一般为带水印的小图,如公安网小图 CERT表示证件照片:如拍摄的身份证、工卡、护照、学生证等证件图片 默认LIVE | |
| liveness_control | 否 | string | NONE | 活体检测控制 NONE: 不进行控制 LOW:较低的活体要求(高通过率 低攻击拒绝率) NORMAL: 一般的活体要求(平衡的攻击拒绝率, 通过率) HIGH: 较高的活体要求(高攻击拒绝率 低通过率) 默认NONE | 
人脸检测 返回数据参数详情
| 字段 | 必选 | 类型 | 说明 | 
|---|---|---|---|
| face_num | 是 | int | 检测到的图片中的人脸数量 | 
| face_list | 是 | array | 人脸信息列表,具体包含的参数参考下面的列表。 | 
| +face_token | 是 | string | 人脸图片的唯一标识 | 
| +location | 是 | array | 人脸在图片中的位置 | 
| ++left | 是 | double | 人脸区域离左边界的距离 | 
| ++top | 是 | double | 人脸区域离上边界的距离 | 
| ++width | 是 | double | 人脸区域的宽度 | 
| ++height | 是 | double | 人脸区域的高度 | 
| ++rotation | 是 | int64 | 人脸框相对于竖直方向的顺时针旋转角,[-180,180] | 
| +face_probability | 是 | double | 人脸置信度,范围【0~1】,代表这是一张人脸的概率,0最小、1最大。 | 
| +angel | 是 | array | 人脸旋转角度参数 | 
| ++yaw | 是 | double | 三维旋转之左右旋转角[-90(左), 90(右)] | 
| ++pitch | 是 | double | 三维旋转之俯仰角度[-90(上), 90(下)] | 
| ++roll | 是 | double | 平面内旋转角[-180(逆时针), 180(顺时针)] | 
| +age | 否 | double | 年龄 ,当face_field包含age时返回 | 
| +expression | 否 | array | 表情,当 face_field包含expression时返回 | 
| ++type | 否 | string | none:不笑;smile:微笑;laugh:大笑 | 
| ++probability | 否 | double | 表情置信度,范围【0~1】,0最小、1最大。 | 
| +face_shape | 否 | array | 脸型,当face_field包含face_shape时返回 | 
| ++type | 否 | double | square: 正方形 triangle:三角形 oval: 椭圆 heart: 心形 round: 圆形 | 
| ++probability | 否 | double | 置信度,范围【0~1】,代表这是人脸形状判断正确的概率,0最小、1最大。 | 
| +gender | 否 | array | 性别,face_field包含gender时返回 | 
| ++type | 否 | string | male:男性 female:女性 | 
| ++probability | 否 | double | 性别置信度,范围【0~1】,0代表概率最小、1代表最大。 | 
| +glasses | 否 | array | 是否带眼镜,face_field包含glasses时返回 | 
| ++type | 否 | string | none:无眼镜,common:普通眼镜,sun:墨镜 | 
| ++probability | 否 | double | 眼镜置信度,范围【0~1】,0代表概率最小、1代表最大。 | 
| +eye_status | 否 | array | 双眼状态(睁开/闭合) face_field包含eye_status时返回 | 
| ++left_eye | 否 | double | 左眼状态 [0,1]取值,越接近0闭合的可能性越大 | 
| ++right_eye | 否 | double | 右眼状态 [0,1]取值,越接近0闭合的可能性越大 | 
| +emotion | 否 | array | 情绪 face_field包含emotion时返回 | 
| ++type | 否 | string | angry:愤怒 disgust:厌恶 fear:恐惧 happy:高兴 sad:伤心 surprise:惊讶 neutral:无情绪 | 
| ++probability | 否 | double | 情绪置信度,范围0~1 | 
| ++probability | 否 | double | 人种置信度,范围【0~1】,0代表概率最小、1代表最大。 | 
| +face_type | 否 | array | 真实人脸/卡通人脸 face_field包含face_type时返回 | 
| ++type | 否 | string | human: 真实人脸 cartoon: 卡通人脸 | 
| ++probability | 否 | double | 人脸类型判断正确的置信度,范围【0~1】,0代表概率最小、1代表最大。 | 
| +landmark | 否 | array | 4个关键点位置,左眼中心、右眼中心、鼻尖、嘴中心。face_field包含landmark时返回 | 
| +landmark72 | 否 | array | 72个特征点位置 face_field包含landmark时返回 | 
| +landmark150 | 否 | array | 150个特征点位置 face_field包含landmark150时返回 | 
| +quality | 否 | array | 人脸质量信息。face_field包含quality时返回 | 
| ++occlusion | 否 | array | 人脸各部分遮挡的概率,范围[0~1],0表示完整,1表示不完整 | 
| +++left_eye | 否 | double | 左眼遮挡比例,[0-1] ,1表示完全遮挡 | 
| +++right_eye | 否 | double | 右眼遮挡比例,[0-1] , 1表示完全遮挡 | 
| +++nose | 否 | double | 鼻子遮挡比例,[0-1] , 1表示完全遮挡 | 
| +++mouth | 否 | double | 嘴巴遮挡比例,[0-1] , 1表示完全遮挡 | 
| +++left_cheek | 否 | double | 左脸颊遮挡比例,[0-1] , 1表示完全遮挡 | 
| +++right_cheek | 否 | double | 右脸颊遮挡比例,[0-1] , 1表示完全遮挡 | 
| +++chin_contour | 否 | double | 下巴遮挡比例,,[0-1] , 1表示完全遮挡 | 
| ++blur | 否 | double | 人脸模糊程度,范围[0~1],0表示清晰,1表示模糊 | 
| ++illumination | 否 | double | 取值范围在[0~255], 表示脸部区域的光照程度 越大表示光照越好 | 
| ++completeness | 否 | int64 | 人脸完整度,0或1, 0为人脸溢出图像边界,1为人脸都在图像边界内 | 
人脸检测 返回示例
1{
2  "face_num": 1,
3  "face_list": [
4        {
5            "face_token": "35235asfas21421fakghktyfdgh68bio",
6            "location": {
7                "left": 117,
8                "top": 131,
9                "width": 172,
10                "height": 170,
11                "rotation": 4
12            },
13            "face_probability": 1,
14            "angle" :{
15                 "yaw" : -0.34859421849251
16                 "pitch" 1.9135693311691
17                 "roll" :2.3033397197723
18            }
19            "landmark": [
20                {
21                    "x": 161.74819946289,
22                    "y": 163.30244445801
23                },
24                ...
25            ],
26            "landmark72": [
27                {
28                    "x": 115.86531066895,
29                    "y": 170.0546875
30                },
31                ...
32            ],
33            "age": 29.298097610474,
34            "expression": {
35                "type": "smile",
36                "probability" : 0.5543018579483
37            },
38            "gender": {
39                "type": "male",
40                "probability": 0.99979132413864
41            },
42            "glasses": {
43          "type": "sun",
44                "probability": 0.99999964237213
45            },
46            "face_shape": {
47                "type": "triangle",
48                "probability": 0.5543018579483
49            }
50            "quality": {
51                "occlusion": {
52                    "left_eye": 0,
53                    "right_eye": 0,
54                    "nose": 0,
55                    "mouth": 0,
56                    "left_cheek": 0.0064102564938366,
57                    "right_cheek": 0.0057411273010075,
58                    "chin": 0
59                },
60                "blur": 1.1886881756684e-10,
61                "illumination": 141,
62                "completeness": 1
63            }
64        }
65    ]
66}**72个关键点分布图(对应landmark72个点的顺序,序号从0-71):https://ai.bdstatic.com/file/52BC00FFD4754A6298D977EDAD033DA0
人脸搜索
- 1:N人脸搜索:也称为1:N识别,在指定人脸集合中,找到最相似的人脸;
- 1:N人脸认证:基于uid维度的1:N识别,由于uid已经锁定固定数量的人脸,所以检索范围更聚焦;
1:N人脸识别与1:N人脸认证的差别在于:人脸搜索是在指定人脸集合中进行直接地人脸检索操作,而人脸认证是基于uid,先调取这个uid对应的人脸,再在这个uid对应的人脸集合中进行检索(因为每个uid通常对应的只有一张人脸,所以通常也就变为了1:1对比);实际应用中,人脸认证需要用户或系统先输入id,这增加了验证安全度,但也增加了复杂度,具体使用哪个接口需要视您的业务场景判断。
1public void SearchDemo() {
2	var image = "取决于image_type参数,传入BASE64字符串或URL字符串或FACE_TOKEN字符串";
3	
4	var imageType = "BASE64";
5	
6	var groupIdList = "3,2";
7	
8	// 调用人脸搜索,可能会抛出网络等异常,请使用try/catch捕获
9	var result = client.Search(image, imageType, groupIdList);
10	Console.WriteLine(result);
11	// 如果有可选参数
12	var options = new Dictionary<string, object>{
13	    {"match_threshold", 70},
14	    {"quality_control", "NORMAL"},
15	    {"liveness_control", "LOW"},
16	    {"user_id", "233451"},
17	    {"max_user_num", 3}
18	};
19	// 带参数调用人脸搜索
20	result = client.Search(image, imageType, groupIdList, options);
21	Console.WriteLine(result);
22}人脸搜索 请求参数详情
| 参数名称 | 是否必选 | 类型 | 默认值 | 说明 | 
|---|---|---|---|---|
| image | 是 | string | 图片信息(总数据大小应小于10M),图片上传方式根据image_type来判断 | |
| image_type | 是 | string | 图片类型 BASE64:图片的base64值,base64编码后的图片数据, 编码后的图片大小不超过2M;URL:图片的 URL地址( 可能由于网络等原因导致下载图片时间过长);FACE_TOKEN: 人脸图片的唯一标识,调用人脸检测接口时,会为每个人脸图片赋予一个唯一的FACE_TOKEN,同一张图片多次检测得到的FACE_TOKEN是同一个 | |
| group_id_list | 是 | string | 从指定的group中进行查找 用逗号分隔,上限10个 | |
| match_threshold | 否 | string | 匹配阈值(设置阈值后,score低于此阈值的用户信息将不会返回) 最大100 最小0 默认80 此阈值设置得越高,检索速度将会越快,推荐使用默认阈值 80 | |
| quality_control | 否 | string | NONE | 图片质量控制 NONE: 不进行控制 LOW:较低的质量要求 NORMAL: 一般的质量要求 HIGH: 较高的质量要求 默认 NONE | 
| liveness_control | 否 | string | NONE | 活体检测控制 NONE: 不进行控制 LOW:较低的活体要求(高通过率 低攻击拒绝率) NORMAL: 一般的活体要求(平衡的攻击拒绝率, 通过率) HIGH: 较高的活体要求(高攻击拒绝率 低通过率) 默认NONE | 
| user_id | 否 | string | 当需要对特定用户进行比对时,指定user_id进行比对。即人脸认证功能。 | |
| max_user_num | 否 | string | 查找后返回的用户数量。返回相似度最高的几个用户,默认为1,最多返回50个。 | 
人脸搜索 返回数据参数详情
| 字段 | 必选 | 类型 | 说明 | 
|---|---|---|---|
| face_token | 是 | string | 人脸标志 | 
| user_list | 是 | array | 匹配的用户信息列表 | 
| +group_id | 是 | string | 用户所属的group_id | 
| +user_id | 是 | string | 用户的user_id | 
| +user_info | 是 | string | 注册用户时携带的user_info | 
| +score | 是 | float | 用户的匹配得分 | 
人脸搜索 返回示例
1{
2  "face_token": "fid",
3  "user_list": [
4     {
5        "group_id" : "test1",
6        "user_id": "u333333",
7        "user_info": "Test User",
8        "score": 99.3
9    }
10  ]
11}人脸搜索 M:N 识别
待识别的图片中,存在多张人脸的情况下,支持在一个人脸库中,一次请求,同时返回图片中所有人脸的识别结果。
1public void MultiSearchDemo() {
2	var image = "取决于image_type参数,传入BASE64字符串或URL字符串或FACE_TOKEN字符串";
3	
4	var imageType = "BASE64";
5	
6	var groupIdList = "3,2";
7	
8	// 调用人脸搜索 M:N 识别,可能会抛出网络等异常,请使用try/catch捕获
9	var result = client.MultiSearch(image, imageType, groupIdList);
10	Console.WriteLine(result);
11	// 如果有可选参数
12	var options = new Dictionary<string, object>{
13	    {"max_face_num", 3},
14	    {"match_threshold", 70},
15	    {"quality_control", "NORMAL"},
16	    {"liveness_control", "LOW"},
17	    {"max_user_num", 3}
18	};
19	// 带参数调用人脸搜索 M:N 识别
20	result = client.MultiSearch(image, imageType, groupIdList, options);
21	Console.WriteLine(result);
22}人脸搜索 M:N 识别 请求参数详情
| 参数名称 | 是否必选 | 类型 | 默认值 | 说明 | 
|---|---|---|---|---|
| image | 是 | string | 图片信息(总数据大小应小于10M),图片上传方式根据image_type来判断 | |
| image_type | 是 | string | 图片类型 BASE64:图片的base64值,base64编码后的图片数据, 编码后的图片大小不超过2M;URL:图片的 URL地址( 可能由于网络等原因导致下载图片时间过长);FACE_TOKEN: 人脸图片的唯一标识,调用人脸检测接口时,会为每个人脸图片赋予一个唯一的FACE_TOKEN,同一张图片多次检测得到的FACE_TOKEN是同一个 | |
| group_id_list | 是 | string | 从指定的group中进行查找 用逗号分隔,上限10个 | |
| max_face_num | 否 | string | 最多处理人脸的数目 默认值为1(仅检测图片中面积最大的那个人脸) 最大值10 | |
| match_threshold | 否 | string | 匹配阈值(设置阈值后,score低于此阈值的用户信息将不会返回) 最大100 最小0 默认80 此阈值设置得越高,检索速度将会越快,推荐使用默认阈值 80 | |
| quality_control | 否 | string | NONE | 图片质量控制 NONE: 不进行控制 LOW:较低的质量要求 NORMAL: 一般的质量要求 HIGH: 较高的质量要求 默认 NONE | 
| liveness_control | 否 | string | NONE | 活体检测控制 NONE: 不进行控制 LOW:较低的活体要求(高通过率 低攻击拒绝率) NORMAL: 一般的活体要求(平衡的攻击拒绝率, 通过率) HIGH: 较高的活体要求(高攻击拒绝率 低通过率) 默认NONE | 
| max_user_num | 否 | string | 查找后返回的用户数量。返回相似度最高的几个用户,默认为1,最多返回20个。 | 
人脸搜索 M:N 识别 返回数据参数详情
| 字段 | 必选 | 类型 | 说明 | 
|---|---|---|---|
| face_num | 是 | int | 图片中的人脸数量 | 
| face_list | 是 | array | 人脸信息列表 | 
| +face_token | 是 | string | 人脸标志 | 
| +location | 是 | array | 人脸在图片中的位置 | 
| ++left | 是 | double | 人脸区域离左边界的距离 | 
| ++top | 是 | double | 人脸区域离上边界的距离 | 
| ++width | 是 | double | 人脸区域的宽度 | 
| ++height | 是 | double | 人脸区域的高度 | 
| ++rotation | 是 | int64 | 人脸框相对于竖直方向的顺时针旋转角,[-180,180] | 
| +user_list | 是 | array | 匹配的用户信息列表 | 
| ++group_id | 是 | string | 用户所属的group_id | 
| ++user_id | 是 | string | 用户的user_id | 
| ++user_info | 是 | string | 注册用户时携带的user_info | 
| ++score | 是 | float | 用户的匹配得分 80分以上可以判断为同一人,此分值对应万分之一误识率 | 
人脸搜索 M:N 识别 返回示例
1{
2    "error_code": 0,
3    "error_msg": "SUCCESS",
4    "log_id": 240483475,
5    "timestamp": 1535533440,
6    "cached": 0,
7    "result": {
8        "face_num": 2,
9        "face_list": [
10            {
11                "face_token": "6fe19a6ee0c4233db9b5bba4dc2b9233",
12                "location": {
13                    "left": 31.95568085,
14                    "top": 120.3764267,
15                    "width": 87,
16                    "height": 85,
17                    "rotation": -5
18                },
19                "user_list": [
20                    {
21                        "group_id": "group1",
22                        "user_id": "5abd24fd062e49bfa906b257ec40d284",
23                        "user_info": "userinfo1",
24                        "score": 69.85684967041
25                    },
26                    {
27                        "group_id": "group1",
28                        "user_id": "2abf89cffb31473a9948268fde9e1c3f",
29                        "user_info": "userinfo2",
30                        "score": 66.586112976074
31                    }
32                ]
33            },
34            {
35                "face_token": "fde61e9c074f48cf2bbb319e42634f41",
36                "location": {
37                    "left": 219.4467773,
38                    "top": 104.7486954,
39                    "width": 81,
40                    "height": 77,
41                    "rotation": 3
42                },
43                "user_list": [
44                    {
45                        "group_id": "group1",
46                        "user_id": "088717532b094c3990755e91250adf7d",
47                        "user_info": "userinfo",
48                        "score": 65.154159545898
49                    }
50                ]
51            }
52        ]
53    }
54}人脸注册
用于从人脸库中新增用户,可以设定多个用户所在组,及组内用户的人脸图片,
典型应用场景:构建您的人脸库,如会员人脸注册,已有用户补全人脸信息等。
人脸库、用户组、用户、用户下的人脸层级关系如下所示:
1|- 人脸库
2   |- 用户组一
3      |- 用户01
4         |- 人脸
5      |- 用户02
6         |- 人脸
7         |- 人脸
8         ....
9       ....
10   |- 用户组二
11   |- 用户组三
12   |- 用户组四
13   ....关于人脸库的设置限制
- 每个appid对应一个人脸库,且不同appid之间,人脸库互不相通;
- 每个人脸库下,可以创建多个用户组,用户组(group)数量没有限制;
- 每个用户组(group)下,可添加最多无限张人脸,无限个uid;
- 每个用户(uid)所能注册的最大人脸数量20个;
为了保证识别效果,请控制注册人脸的质量(通过/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像素 | 
1public void UserAddDemo() {
2	var image = "取决于image_type参数,传入BASE64字符串或URL字符串或FACE_TOKEN字符串";
3	
4	var imageType = "BASE64";
5	
6	var groupId = "group1";
7	
8	var userId = "user1";
9	
10	// 调用人脸注册,可能会抛出网络等异常,请使用try/catch捕获
11	var result = client.UserAdd(image, imageType, groupId, userId);
12	Console.WriteLine(result);
13	// 如果有可选参数
14	var options = new Dictionary<string, object>{
15	    {"user_info", "user's info"},
16	    {"quality_control", "NORMAL"},
17	    {"liveness_control", "LOW"},
18	    {"action_type", "REPLACE"}
19	};
20	// 带参数调用人脸注册
21	result = client.UserAdd(image, imageType, groupId, userId, options);
22	Console.WriteLine(result);
23}人脸注册 请求参数详情
| 参数名称 | 是否必选 | 类型 | 默认值 | 说明 | 
|---|---|---|---|---|
| image | 是 | string | 图片信息(总数据大小应小于10M),图片上传方式根据image_type来判断。注:组内每个uid下的人脸图片数目上限为20张 | |
| image_type | 是 | string | 图片类型 BASE64:图片的base64值,base64编码后的图片数据, 编码后的图片大小不超过2M;URL:图片的 URL地址( 可能由于网络等原因导致下载图片时间过长);FACE_TOKEN: 人脸图片的唯一标识,调用人脸检测接口时,会为每个人脸图片赋予一个唯一的FACE_TOKEN,同一张图片多次检测得到的FACE_TOKEN是同一个 | |
| group_id | 是 | string | 用户组id(由数字、字母、下划线组成),长度限制128B | |
| user_id | 是 | string | 用户id(由数字、字母、下划线组成),长度限制128B | |
| user_info | 否 | string | 用户资料,长度限制256B | |
| quality_control | 否 | string | NONE | 图片质量控制 NONE: 不进行控制 LOW:较低的质量要求 NORMAL: 一般的质量要求 HIGH: 较高的质量要求 默认 NONE | 
| liveness_control | 否 | string | NONE | 活体检测控制 NONE: 不进行控制 LOW:较低的活体要求(高通过率 低攻击拒绝率) NORMAL: 一般的活体要求(平衡的攻击拒绝率, 通过率) HIGH: 较高的活体要求(高攻击拒绝率 低通过率) 默认NONE | 
| action_type | 否 | string | APPEND | 操作方式 APPEND: 当user_id在库中已经存在时,对此user_id重复注册时,新注册的图片默认会追加到该user_id下,REPLACE : 当对此user_id重复注册时,则会用新图替换库中该user_id下所有图片,默认使用APPEND | 
人脸注册 返回数据参数详情
| 字段 | 必选 | 类型 | 说明 | 
|---|---|---|---|
| log_id | 是 | uint64 | 请求标识码,随机数,唯一 | 
| face_token | 是 | string | 人脸图片的唯一标识 | 
| location | 是 | array | 人脸在图片中的位置 | 
| +left | 是 | double | 人脸区域离左边界的距离 | 
| +top | 是 | double | 人脸区域离上边界的距离 | 
| +width | 是 | double | 人脸区域的宽度 | 
| +height | 是 | double | 人脸区域的高度 | 
| +rotation | 是 | int64 | 人脸框相对于竖直方向的顺时针旋转角,[-180,180] | 
人脸注册 返回示例
1{
2  "face_token": "2fa64a88a9d5118916f9a303782a97d3",
3  "location": {
4      "left": 117,
5      "top": 131,
6      "width": 172,
7      "height": 170,
8      "rotation": 4
9  }
10}人脸更新
用于对人脸库中指定用户,更新其下的人脸图像。
说明:针对一个uid执行更新操作,新上传的人脸图像将覆盖此uid原有所有图像。
1public void UserUpdateDemo() {
2	var image = "取决于image_type参数,传入BASE64字符串或URL字符串或FACE_TOKEN字符串";
3	
4	var imageType = "BASE64";
5	
6	var groupId = "group1";
7	
8	var userId = "user1";
9	
10	// 调用人脸更新,可能会抛出网络等异常,请使用try/catch捕获
11	var result = client.UserUpdate(image, imageType, groupId, userId);
12	Console.WriteLine(result);
13	// 如果有可选参数
14	var options = new Dictionary<string, object>{
15	    {"user_info", "user's info"},
16	    {"quality_control", "NORMAL"},
17	    {"liveness_control", "LOW"},
18	    {"action_type", "REPLACE"}
19	};
20	// 带参数调用人脸更新
21	result = client.UserUpdate(image, imageType, groupId, userId, options);
22	Console.WriteLine(result);
23}人脸更新 请求参数详情
| 参数名称 | 是否必选 | 类型 | 默认值 | 说明 | 
|---|---|---|---|---|
| image | 是 | string | 图片信息(总数据大小应小于10M),图片上传方式根据image_type来判断 | |
| image_type | 是 | string | 图片类型 BASE64:图片的base64值,base64编码后的图片数据, 编码后的图片大小不超过2M;URL:图片的 URL地址( 可能由于网络等原因导致下载图片时间过长);FACE_TOKEN: 人脸图片的唯一标识,调用人脸检测接口时,会为每个人脸图片赋予一个唯一的FACE_TOKEN,同一张图片多次检测得到的FACE_TOKEN是同一个 | |
| group_id | 是 | string | 更新指定groupid下uid对应的信息 | |
| user_id | 是 | string | 用户id(由数字、字母、下划线组成),长度限制128B | |
| user_info | 否 | string | 用户资料,长度限制256B | |
| quality_control | 否 | string | NONE | 图片质量控制 NONE: 不进行控制 LOW:较低的质量要求 NORMAL: 一般的质量要求 HIGH: 较高的质量要求 默认 NONE | 
| liveness_control | 否 | string | NONE | 活体检测控制 NONE: 不进行控制 LOW:较低的活体要求(高通过率 低攻击拒绝率) NORMAL: 一般的活体要求(平衡的攻击拒绝率, 通过率) HIGH: 较高的活体要求(高攻击拒绝率 低通过率) 默认NONE | 
| action_type | 否 | string | UPDATE | 操作方式 UPDATE: 当user_id在库中已经存在时,对此user_id重复注册时,新注册的图片默认会追加到该user_id下,REPLACE : 当对此user_id重复注册时,则会用新图替换库中该user_id下所有图片,默认使用UPDATE | 
人脸更新 返回数据参数详情
| 字段 | 必选 | 类型 | 说明 | 
|---|---|---|---|
| log_id | 是 | uint64 | 请求标识码,随机数,唯一 | 
| face_token | 是 | string | 人脸图片的唯一标识 | 
| location | 是 | array | 人脸在图片中的位置 | 
| +left | 是 | double | 人脸区域离左边界的距离 | 
| +top | 是 | double | 人脸区域离上边界的距离 | 
| +width | 是 | double | 人脸区域的宽度 | 
| +height | 是 | double | 人脸区域的高度 | 
| +rotation | 是 | int64 | 人脸框相对于竖直方向的顺时针旋转角,[-180,180] | 
人脸更新 返回示例
1{
2  "face_token": "2fa64a88a9d5118916f9a303782a97d3",
3  "location": {
4      "left": 117,
5      "top": 131,
6      "width": 172,
7      "height": 170,
8      "rotation": 4
9  }
10}人脸删除
用于从人脸库中删除一个用户。
人脸删除注意事项:
- 删除的内容,包括用户所有图像和身份信息;
- 如果一个uid存在于多个用户组内,将会同时将从各个组中把用户删除
- 如果指定了group_id,则只删除此group下的uid相关信息
1public void FaceDeleteDemo() {
2	var userId = "user1";
3	
4	var groupId = "group1";
5	
6	var faceToken = "face_token_23123";
7	
8	// 调用人脸删除,可能会抛出网络等异常,请使用try/catch捕获
9	var result = client.FaceDelete(userId, groupId, faceToken);
10	Console.WriteLine(result);
11}人脸删除 请求参数详情
| 参数名称 | 是否必选 | 类型 | 说明 | 
|---|---|---|---|
| log_id | 是 | uint64 | 请求标识码,随机数,唯一 | 
| user_id | 是 | string | 用户id(由数字、字母、下划线组成),长度限制128B | 
| group_id | 是 | string | 用户组id(由数字、字母、下划线组成),长度限制128B | 
| face_token | 是 | string | 需要删除的人脸图片token,(由数字、字母、下划线组成)长度限制64B | 
人脸删除 返回数据参数详情
| 字段 | 是否必选 | 类型 | 说明 | 
|---|---|---|---|
| log_id | 是 | uint64 | 请求唯一标识码,随机数 | 
人脸删除 返回示例
1// 删除成功
2{
3  "error_code": 0,
4  "log_id": 73473737,
5}
6// 删除发生错误
7{
8  "error_code": 223106,
9  "log_id": 1382953199,
10  "error_msg": "face is not exist"
11}用户信息查询
获取人脸库中某个用户的信息(user_info信息和用户所属的组)。
1public void UserGetDemo() {
2	var userId = "user1";
3	
4	var groupId = "group1";
5	
6	// 调用用户信息查询,可能会抛出网络等异常,请使用try/catch捕获
7	var result = client.UserGet(userId, groupId);
8	Console.WriteLine(result);
9}用户信息查询 请求参数详情
| 参数名称 | 是否必选 | 类型 | 说明 | 
|---|---|---|---|
| user_id | 是 | string | 用户id(由数字、字母、下划线组成),长度限制128B | 
| group_id | 是 | string | 用户组id(由数字、字母、下划线组成),长度限制128B | 
用户信息查询 返回数据参数详情
| 字段 | 必选 | 类型 | 说明 | 
|---|---|---|---|
| log_id | 是 | uint64 | 请求标识码,随机数,唯一 | 
| user_list | 是 | array | 查询到的用户列表 | 
| +user_info | 是 | string | 用户资料,被查询用户的资料 | 
| +group_id | 是 | string | 用户组id,被查询用户的所在组 | 
用户信息查询 返回示例
1{
2  "user_list": [
3      {
4          "user_info": "user info ...",
5          "group_id": "gid1"
6      },
7      {
8          "user_info": "user info2 ...",
9          "group_id": "gid2"
10      }
11  ]
12}获取用户人脸列表
用于获取一个用户的全部人脸列表。
1public void FaceGetlistDemo() {
2	var userId = "user1";
3	
4	var groupId = "group1";
5	
6	// 调用获取用户人脸列表,可能会抛出网络等异常,请使用try/catch捕获
7	var result = client.FaceGetlist(userId, groupId);
8	Console.WriteLine(result);
9}获取用户人脸列表 请求参数详情
| 参数名称 | 是否必选 | 类型 | 说明 | 
|---|---|---|---|
| user_id | 是 | string | 用户id(由数字、字母、下划线组成),长度限制128B | 
| group_id | 是 | string | 用户组id(由数字、字母、下划线组成),长度限制128B | 
获取用户人脸列表 返回数据参数详情
| 字段 | 必选 | 类型 | 说明 | 
|---|---|---|---|
| log_id | 是 | uint64 | 请求标识码,随机数,唯一 | 
| face_list | 是 | array | 人脸列表 | 
| +face_token | 是 | string | 人脸图片的唯一标识 | 
| +ctime | 是 | string | 人脸创建时间 | 
获取用户人脸列表 返回示例
1{
2  "face_list": [
3      {
4          "face_token": "fid1",
5          "ctime": "2018-01-01 00:00:00"
6      },
7      {
8          "face_token": "fid2",
9          "ctime": "2018-01-01 10:00:00"
10      }
11  ]
12}获取用户列表
用于查询指定用户组中的用户列表。
1public void GroupGetusersDemo() {
2	var groupId = "group1";
3	
4	// 调用获取用户列表,可能会抛出网络等异常,请使用try/catch捕获
5	var result = client.GroupGetusers(groupId);
6	Console.WriteLine(result);
7	// 如果有可选参数
8	var options = new Dictionary<string, object>{
9	    {"start", 0},
10	    {"length", 50}
11	};
12	// 带参数调用获取用户列表
13	result = client.GroupGetusers(groupId, options);
14	Console.WriteLine(result);
15}获取用户列表 请求参数详情
| 参数名称 | 是否必选 | 类型 | 默认值 | 说明 | 
|---|---|---|---|---|
| group_id | 是 | string | 用户组id(由数字、字母、下划线组成),长度限制128B | |
| start | 否 | string | 0 | 默认值0,起始序号 | 
| length | 否 | string | 100 | 返回数量,默认值100,最大值1000 | 
获取用户列表 返回数据参数详情
| 字段 | 必选 | 类型 | 说明 | 
|---|---|---|---|
| user_id_list | 是 | array | 用户ID列表 | 
获取用户列表 返回示例
1{
2  "user_id_list": [
3      "uid1",
4      "uid2"
5  ]
6}复制用户
用于将已经存在于人脸库中的用户复制到一个新的组。
1public void UserCopyDemo() {
2	var userId = "user1";
3	
4	// 调用复制用户,可能会抛出网络等异常,请使用try/catch捕获
5	var result = client.UserCopy(userId);
6	Console.WriteLine(result);
7	// 如果有可选参数
8	var options = new Dictionary<string, object>{
9	    {"src_group_id", "11111"},
10	    {"dst_group_id", "222222"}
11	};
12	// 带参数调用复制用户
13	result = client.UserCopy(userId, options);
14	Console.WriteLine(result);
15}复制用户 请求参数详情
| 参数名称 | 是否必选 | 类型 | 说明 | 
|---|---|---|---|
| user_id | 是 | string | 用户id(由数字、字母、下划线组成),长度限制128B | 
| src_group_id | 否 | string | 从指定组里复制信息 | 
| dst_group_id | 否 | string | 需要添加用户的组id | 
复制用户 返回数据参数详情
| 字段 | 必选 | 类型 | 说明 | 
|---|---|---|---|
| log_id | 是 | id | log_id | 
复制用户 返回示例
1// 正确返回值
2{
3   "error_code": 0,
4  "log_id": 3314921889,
5}
6// 发生错误时返回值
7{
8  "error_code": 216100,
9  "log_id": 3111284097,
10  "error_msg": "already add"
11}删除用户
用于将用户从某个组中删除。
1public void UserDeleteDemo() {
2	var groupId = "group1";
3	
4	var userId = "user1";
5	
6	// 调用删除用户,可能会抛出网络等异常,请使用try/catch捕获
7	var result = client.UserDelete(groupId, userId);
8	Console.WriteLine(result);
9}删除用户 请求参数详情
| 参数名称 | 是否必选 | 类型 | 说明 | 
|---|---|---|---|
| group_id | 是 | string | 用户组id(由数字、字母、下划线组成),长度限制128B | 
| user_id | 是 | string | 用户id(由数字、字母、下划线组成),长度限制128B | 
删除用户 返回数据参数详情
| 字段 | 是否必选 | 类型 | 说明 | 
|---|---|---|---|
| log_id | 是 | uint64 | 请求唯一标识码,随机数 | 
删除用户 返回示例
1// 正确返回值
2{
3
4  "error_code": 0,
5  "log_id": 3314921889,
6}
7// 发生错误时返回值
8{
9  "error_code":  223103,
10  "log_id": 815967402,
11  "error_msg": "user is not exist"
12}创建用户组
用于创建一个空的用户组,如果用户组已存在 则返回错误。
1public void GroupAddDemo() {
2	var groupId = "group1";
3	
4	// 调用创建用户组,可能会抛出网络等异常,请使用try/catch捕获
5	var result = client.GroupAdd(groupId);
6	Console.WriteLine(result);
7}创建用户组 请求参数详情
| 参数名称 | 是否必选 | 类型 | 说明 | 
|---|---|---|---|
| group_id | 是 | string | 用户组id(由数字、字母、下划线组成),长度限制128B | 
创建用户组 返回数据参数详情
| 字段 | 必选 | 类型 | 说明 | 
|---|---|---|---|
| log_id | 是 | uint64 | 请求标识码,随机数,唯一 | 
创建用户组 返回示例
1{
2
3  "error_code": 0,
4  "log_id": 3314921889,
5}
6// 发生错误时返回值
7{
8  "error_code":  223101,
9  "log_id": 815967402,
10  "error_msg": " group is already exist"
11}删除用户组
删除用户组下所有的用户及人脸,如果组不存在 则返回错误。
1public void GroupDeleteDemo() {
2	var groupId = "group1";
3	
4	// 调用删除用户组,可能会抛出网络等异常,请使用try/catch捕获
5	var result = client.GroupDelete(groupId);
6	Console.WriteLine(result);
7}删除用户组 请求参数详情
| 参数名称 | 是否必选 | 类型 | 说明 | 
|---|---|---|---|
| group_id | 是 | string | 用户组id(由数字、字母、下划线组成),长度限制128B | 
删除用户组 返回数据参数详情
| 字段 | 必选 | 类型 | 说明 | 
|---|---|---|---|
| log_id | 是 | uint64 | 请求标识码,随机数,唯一 | 
删除用户组 返回示例
1// 正确返回值
2{
3
4  "error_code":0,
5  "log_id": 3314921889,
6}
7// 发生错误时返回值
8{
9  "error_code": 223100,
10  "log_id": 815967402,
11  "error_msg": " group is not exist"
12}组列表查询
用于查询用户组的列表。
1public void GroupGetlistDemo() {
2	// 调用组列表查询,可能会抛出网络等异常,请使用try/catch捕获
3	var result = client.GroupGetlist();
4	Console.WriteLine(result);
5	// 如果有可选参数
6	var options = new Dictionary<string, object>{
7	    {"start", 0},
8	    {"length", 50}
9	};
10	// 带参数调用组列表查询
11	result = client.GroupGetlist(options);
12	Console.WriteLine(result);
13}组列表查询 请求参数详情
| 参数名称 | 是否必选 | 类型 | 默认值 | 说明 | 
|---|---|---|---|---|
| start | 否 | string | 0 | 默认值0,起始序号 | 
| length | 否 | string | 100 | 返回数量,默认值100,最大值1000 | 
组列表查询 返回数据参数详情
| 字段 | 必选 | 类型 | 说明 | 
|---|---|---|---|
| group_id_list | 是 | array | group | 
组列表查询 返回示例
1{
2    "group_id_list": [
3        "gid1",
4        "gid2"
5    ]
6}身份验证
质量检测(可选)活体检测(可选)公安验证(必选)
1public void PersonVerifyDemo() {
2	var image = "取决于image_type参数,传入BASE64字符串或URL字符串或FACE_TOKEN字符串";
3	
4	var imageType = "BASE64";
5	
6	var idCardNumber = "110233112299822211";
7	
8	var name = "张三";
9	
10	// 调用身份验证,可能会抛出网络等异常,请使用try/catch捕获
11	var result = client.PersonVerify(image, imageType, idCardNumber, name);
12	Console.WriteLine(result);
13	// 如果有可选参数
14	var options = new Dictionary<string, object>{
15	    {"quality_control", "NORMAL"},
16	    {"liveness_control", "LOW"}
17	};
18	// 带参数调用身份验证
19	result = client.PersonVerify(image, imageType, idCardNumber, name, options);
20	Console.WriteLine(result);
21}身份验证 请求参数详情
| 参数名称 | 是否必选 | 类型 | 默认值 | 说明 | 
|---|---|---|---|---|
| image | 是 | string | 图片信息(总数据大小应小于10M),图片上传方式根据image_type来判断 | |
| image_type | 是 | string | 图片类型 BASE64:图片的base64值,base64编码后的图片数据, 编码后的图片大小不超过2M;URL:图片的 URL地址( 可能由于网络等原因导致下载图片时间过长);FACE_TOKEN: 人脸图片的唯一标识,调用人脸检测接口时,会为每个人脸图片赋予一个唯一的FACE_TOKEN,同一张图片多次检测得到的FACE_TOKEN是同一个 | |
| id_card_number | 是 | string | 身份证号(真实身份证号号码) | |
| name | 是 | string | utf8,姓名(真实姓名,和身份证号匹配) | |
| quality_control | 否 | string | NONE | 图片质量控制 NONE: 不进行控制 LOW:较低的质量要求 NORMAL: 一般的质量要求 HIGH: 较高的质量要求 默认 NONE | 
| liveness_control | 否 | string | NONE | 活体检测控制 NONE: 不进行控制 LOW:较低的活体要求(高通过率 低攻击拒绝率) NORMAL: 一般的活体要求(平衡的攻击拒绝率, 通过率) HIGH: 较高的活体要求(高攻击拒绝率 低通过率) 默认NONE | 
身份验证 返回数据参数详情
| 参数 | 必须 | 类型 | 说明 | 
|---|---|---|---|
| log_id | 是 | uint64 | 日志id | 
| score | 是 | float | 与公安小图相似度可能性,用于验证生活照与公安小图是否为同一人,有正常分数时为[0~1],推荐阈值0.8,超过即判断为同一人 | 
身份验证 返回示例
1{
2  "score": 44.3,
3}语音校验码接口
此接口主要用于生成随机码,用于视频的语音识别校验使用,以判断视频的即时性,而非事先录制的,提升作弊的难度。
1public void VideoSessioncodeDemo() {
2	// 调用语音校验码接口,可能会抛出网络等异常,请使用try/catch捕获
3	var result = client.VideoSessioncode();
4	Console.WriteLine(result);
5	// 如果有可选参数
6	var options = new Dictionary<string, object>{
7	    {"appid", "223245"}
8	};
9	// 带参数调用语音校验码接口
10	result = client.VideoSessioncode(options);
11	Console.WriteLine(result);
12}语音校验码接口 请求参数详情
| 参数名称 | 是否必选 | 类型 | 说明 | 
|---|---|---|---|
| appid | 否 | string | 百度云创建应用时的唯一标识ID | 
语音校验码接口 返回数据参数详情
| 字段 | 必选 | 类型 | 说明 | 
|---|---|---|---|
| session_id | 是 | string | 语音校验码会话id | 
| code | 是 | string | 语音验证码,数字形式,3~6位数字 | 
语音校验码接口 返回示例
1{
2  "err_no": 0,
3  "err_msg": "SUCCESS",
4  "result": {
5    "session_id": "S59faeeebb9111890355690",
6    "code": "9940"
7  },
8  "timestamp": 1509617387,
9  "cached": 0,
10  "serverlogid": "0587756642"
11}人脸对比
接口能力
- 两张人脸图片相似度对比:比对两张图片中人脸的相似度,并返回相似度分值;
- 多种图片类型:支持生活照、证件照、身份证芯片照、带网纹照四种类型的人脸对比;
- 活体检测:基于图片中的破绽分析,判断其中的人脸是否为二次翻拍(举例:如用户A用手机拍摄了一张包含人脸的图片一,用户B翻拍了图片一得到了图片二,并用图片二伪造成用户A去进行识别操作,这种情况普遍发生在金融开户、实名认证等环节。);
- 质量检测:返回模糊、光照等质量检测信息,用于辅助判断图片是否符合识别要求;
业务应用
用于比对多张图片中的人脸相似度并返回两两比对的得分,可用于判断两张脸是否是同一人的可能性大小。
典型应用场景:如人证合一验证,用户认证等,可与您现有的人脸库进行比对验证。
1public string ReadImg(string img)
2{
3    return Convert.ToBase64String(File.ReadAllBytes(img));
4}
5
6public void demo()
7{
8    var faces = new JArray
9    {
10        new JObject
11        {
12            {"image", ReadImg("ym1.jpeg")},
13            {"image_type", "BASE64"},
14            {"face_type", "LIVE"},
15            {"quality_control", "LOW"},
16            {"liveness_control", "NONE"},
17        },
18        new JObject
19        {
20            {"image", ReadImg("ym2.jpeg")},
21            {"image_type", "BASE64"},
22            {"face_type", "LIVE"},
23            {"quality_control", "LOW"},
24            {"liveness_control", "NONE"},
25        }
26    };
27
28    var result = client.Match(faces);
29    Console.Write(result);
30}请求参数
参数为 JArray,JArray中的元素为JObject
JObject 中的参数:
| 参数 | 必选 | 类型 | 说明 | 
|---|---|---|---|
| image | 是 | string | 图片信息(总数据大小应小于10M),图片上传方式根据image_type来判断。 两张图片通过json格式上传,格式参考表格下方示例 | 
| image_type | 是 | string | 图片类型 BASE64:图片的base64值,base64编码后的图片数据, 编码后的图片大小不超过2M;URL:图片的 URL地址( 可能由于网络等原因导致下载图片时间过长);FACE_TOKEN: 人脸图片的唯一标识,调用人脸检测接口时,会为每个人脸图片赋予一个唯一的FACE_TOKEN,同一张图片多次检测得到的FACE_TOKEN是同一个。 | 
| face_type | 否 | string | 人脸的类型 LIVE表示生活照:通常为手机、相机拍摄的人像图片、或从网络获取的人像图片等,IDCARD表示身份证芯片照:二代身份证内置芯片中的人像照片, WATERMARK表示带水印证件照:一般为带水印的小图,如公安网小图 CERT表示证件照片:如拍摄的身份证、工卡、护照、学生证等证件图片 默认LIVE | 
| quality_control | 否 | string | 图片质量控制 NONE: 不进行控制 LOW:较低的质量要求 NORMAL: 一般的质量要求 HIGH: 较高的质量要求 默认 NONE | 
| liveness_control | 否 | string | 活体检测控制 NONE: 不进行控制 LOW:较低的活体要求(高通过率 低攻击拒绝率) NORMAL: 一般的活体要求(平衡的攻击拒绝率, 通过率) HIGH: 较高的活体要求(高攻击拒绝率 低通过率) 默认NONE | 
最终上传的内容如下:
JSON1[ 2 { 3 "image": "sfasq35sadvsvqwr5q...", 4 "image_type": "BASE64", 5 "face_type": "LIVE", 6 "quality_control": "LOW", 7 "liveness_control": "HIGH" 8 }, 9 { 10 "image": "sfasq35sadvsvqwr5q...", 11 "image_type": "BASE64", 12 "face_type": "IDCARD", 13 "quality_control": "LOW", 14 "liveness_control": "HIGH" 15 } 16]
返回参数
| 参数名 | 必选 | 类型 | 说明 | 
|---|---|---|---|
| score | 是 | float | 人脸相似度得分 | 
| face_list | 是 | array | 人脸信息列表 | 
| +face_token | 是 | string | 人脸的唯一标志 | 
返回示例
1{
2  "score": 44.3,
3  "face_list": [  //返回的顺序与传入的顺序保持一致
4      {
5          "face_token": "fid1"
6      },
7      {
8          "face_token": "fid2"
9      }
10  ]
11}关于活体检测faceliveness的判断阈值选择,可参考以下数值信息:
| 拒绝率(TRR) | 误拒率(FRR) | 通过率(TAR) | 阈值(Threshold) | 
|---|---|---|---|
| 0.90325733 | 0.1% | 99.9% | 0.022403 | 
| 0.96254072 | 0.5% | 99.5% | 0.393241(推荐) | 
| 0.97557003 | 1% | 99% | 0.649192 | 
| 0.98990228 | 2% | 98% | 0.933801 | 
| 0.99446254 | 3% | 97% | 0.973637 | 
| 0.99641694 | 4% | 96% | 0.988479 | 
| 0.99739414 | 5% | 95% | 0.994058 | 
关于以上数值的概念介绍:
- 拒绝率(TRR):如99%,代表100次作弊假体攻击,会有99次被拒绝。
- 误拒率(FRR):如0.5%,指1000次真人请求,会有5次因为活体分数低于阈值被错误拒绝。
- 通过率(TAR):如99%,指100次真人请求,会有99次因为活体分数高于阈值而通过。
- 阈值(Threshold):高于此数值,则可判断为活体。
在线活体检测
人脸基础信息,人脸质量检测,基于图片的活体检测
1public string ReadImg(string img)
2{
3    return Convert.ToBase64String(File.ReadAllBytes(img));
4}
5
6public void Demo() {
7    var faces = new JArray
8    {
9        new JObject
10        {
11            {"image", ReadImg("/ym1.jpeg")},
12            {"image_type", "BASE64"},
13            {"face_field", "age"},
14        },
15        new JObject
16        {
17            {"image", ReadImg("/ym2.jpeg")},
18            {"image_type", "BASE64"}
19        }
20    };
21    var result = client.Faceverify(faces);
22    Console.WriteLine(result);
23}在线活体检测 请求参数详情
| 参数名称 | 是否必选 | 类型 | 说明 | 
|---|---|---|---|
| image | 是 | String | 图片信息(总数据大小应小于10M),图片上传方式根据image_type来判断 | 
| image_type | 是 | String | 图片类型 BASE64:图片的base64值,base64编码后的图片数据, 编码后的图片大小不超过2M;URL:图片的 URL地址( 可能由于网络等原因导致下载图片时间过长);FACE_TOKEN: 人脸图片的唯一标识,调用人脸检测接口时,会为每个人脸图片赋予一个唯一的FACE_TOKEN,同一张图片多次检测得到的FACE_TOKEN是同一个 | 
| face_fields | 否 | String | 包括age,expression,faceshape,gender,glasses,landmark,quality,facetype信息,逗号分隔,默认只返回face_token、活体数、人脸框、概率和旋转角度。 | 
在线活体检测 返回数据参数详情
| 参数 | 类型 | 是否必须 | 说明 | 
|---|---|---|---|
| log_id | 是 | uint64 | 请求唯一标识码,随机数 | 
| face_liveness | 是 | float | 活体分数值 | 
| thresholds | 是 | array | 由服务端返回最新的阈值数据(随着模型的优化,阈值可能会变化),可以作为活体判断的依据。 frr_1e-4:万分之一误识率的阈值;frr_1e-3:千分之一误识率的阈值;frr_1e-2:百分之一误识率的阈值。误识率越底,准确率越高。 | 
| face_list | 是 | array | 每张图片的详细信息描述,如果只上传一张图片,则只返回一个结果。 | 
在线活体检测 返回示例
1{
2    "thresholds": {
3        "frr_1e-4": 0.05,
4        "frr_1e-3": 0.3,
5        "frr_1e-2": 0.9
6    },
7    "face_liveness": 0.05532243927,
8    "face_list": [
9        {
10            "face_token": "df46f7c7db4aa09a093c26fb8d1a8d44",
11            "location": {
12                "left": 328.9026489,
13                "top": 97.16340637,
14                "width": 162,
15                "height": 154,
16                "rotation": 32
17            },
18            "face_probability": 1,
19            "angle": {
20                "yaw": 10.16196251,
21                "pitch": 2.244354248,
22                "roll": 33.82199097
23            },
24            "liveness": {
25                "faceliveness": 0.004187555984,
26                "livemapscore": 0.04492170034
27            },
28            "age": 23
29        },
30        {
31            "face_token": "901d2c64274fccd687d311a6e6110a01",
32            "location": {
33                "left": 411.4876404,
34                "top": 166.3593445,
35                "width": 329,
36                "height": 308,
37                "rotation": 45
38            },
39            "face_probability": 0.9194830656,
40            "angle": {
41                "yaw": -1.716423035,
42                "pitch": 7.344647408,
43                "roll": 45.79914856
44            },
45            "liveness": {
46                "faceliveness": 0.0001665892196,
47                "livemapscore": 0.001787073661
48            },
49            "age": 23
50        },
51        {
52            "face_token": "7d57e36981c48b4946eb97c8d838b02a",
53            "location": {
54                "left": 161.4559937,
55                "top": 199.8726501,
56                "width": 218,
57                "height": 201,
58                "rotation": -1
59            },
60            "face_probability": 1,
61            "angle": {
62                "yaw": -8.187754631,
63                "pitch": 6.973727226,
64                "roll": -1.25429821
65            },
66            "liveness": {
67                "faceliveness": 0.02942637168,
68                "livemapscore": 0.05532243927
69            },
70            "age": 23
71        }
72    ]
73}人脸实名认证V4
能力介绍
1. 业务能力
- 质量检测(可选):判断图片中是否包含人脸,以及人脸在姿态、遮挡、模糊、光照等方面是否符合识别条件。
- 活体检测(可选):基于图片中的破绽分析,判断其中的人脸是否为二次翻拍(举例:如用户A用手机拍摄了一张包含人脸的图片一,用户B翻拍了图片一得到了图片二,并用图片二伪造成用户A去进行识别操作,这种情况普遍发生在金融开户、实名认证等环节)。
- 图片加密及风控(可选):当配合增强级采集SDK、增强级安全加固采集SDK、金融级采集SDK、金融级安全加固采集SDK版本使用,对采集SDK输出的加密图片进行解密(加密传输可以有效避免第三方非法黑产绕过APP模拟请求攻击云端接口的行为,Eg:脚本攻击等); 以及结合百度安全实验室大数据风控能力,对采集SDK的发起端设备进行风控识别,辨别是否为风险设备,Eg:ROM注入、视频劫持等;
- 人脸实名认证(必选):基于姓名和身份证号,调取公安权威数据源人脸图,将当前获取的人脸图片,与公安数据源人脸图进行对比,得出比对分数,并基于此进行业务判断是否为同一人。由于公安数据源人脸图具有最权威的身份证明作用,故对用户本人的验证结果可信度也最为合理。
2. 业务逻辑
- 上述能力,人脸实名认证能力为必选能力,质量检测、活体检测、图片加密及风控为可选能力,验证顺序为人脸质量检测->活体检测->人脸实名认证。
- 如选择了质量检测和活体检测能力,则有任意一个条件不通过,整个请求流程终止,并返回错误码,描述具体的不符合信息。
- 基于此顺序串行验证逻辑,可以避免大量不符合条件的请求流转到人脸实名认证,节约您的成本。
3. 推荐阈值
- 此接口使用的对比算法,针对带水纹证件照采用了专项的模型处理,可保证水纹信息的影响降到尽可能低。
- 如比对成功,最终返回的有效数据为一个对比分值,在0~100之间,您可以设定具体的阈值来判断是否验证通过。
- 人证相似度的推荐阈值为80,对应的误识率为万分之一。
1public void Demo() {
2  
3  // 必填参数
4	var idCardNumber = "";
5	var name = "";
6  var image = ""
7  
8  // 选填参数
9	var options = new Dictionary<string, object>{
10	    {"xxx", "xxx"},
11	};
12	
13	// 调用接口
14	result = client.faceMingJingVerify(idCardNumber, name, image, options);
15	Console.WriteLine(result);
16}请求参数
| 参数 | 必选 | 类型 | 说明 | 
|---|---|---|---|
| app | 否 | string | APP端类型,配合采集SDK使用时须传入 ios:iOS端采集SDK android:安卓端采集SDK | 
| sec_level | 否 | string | SDK安全级别,配合采集SDK使用时须传入,默认common common : 配合4.1/4.1.5版本采集SDK,人脸图片未进行加密处理 lite: 配合5.2版本SDK | 
| skey | 否 | string | 使用5.2版本SDK请求时必填 skey:从SDK获取的密钥信息skey | 
| x_device_id | 否 | string | 使用5.2版本SDK请求时必填 deviceId:从SDK 获取的密钥信息deviceId | 
| data | 否 | string | 使用5.2版本SDK请求时必填, SDK输出的加密数据 | 
| id_card_number | 是 | string | 身份证件号 | 
| name | 是 | string | 姓名(需要是 utf8 编码) | 
| liveness_control | 否 | string | 活体控制参数 NONE: 不进行控制 LOW:较低的活体要求(高通过率 低攻击拒绝率) NORMAL: 一般的活体要求(平衡的攻击拒绝率, 通过率) HIGH: 较高的活体要求(高攻击拒绝率 低通过率) 默认为NONE | 
| spoofing_control | 否 | string | 合成图控制参数 NONE: 不进行控制 LOW:较低的合成图阈值数值,由于合成图判定逻辑为大于阈值视为合成图攻击,该项代表低通过率、高攻击拒绝率 NORMAL: 一般的合成图阈值数值,由于合成图判定逻辑为大于阈值视为合成图攻击,该项代表平衡的攻击拒绝率, 通过率 HIGH: 较高的合成图阈值数值,由于合成图判定逻辑为大于阈值视为合成图攻击,该项代表高通过率、低攻击拒绝率) 默认为NONE | 
| quality_control | 否 | string | 质量控制参数 NONE: 不进行控制 LOW:较低的质量要求 NORMAL: 一般的质量要求 HIGH: 较高的质量要求 默认为NONE | 
| image | 是 | string | 图片信息(数据大小应小于10M 分辨率应小于1920*1080),5.2版本SDK请求时已包含在加密数据data中,无需额外传入 | 
| image_type | 否 | string | 图片类型 BASE64 : 图片的base64值 URL : 图片的 URL FACE_TOKEN : 人脸标识 默认 BASE64 | 
返回参数
| 参数 | 类型 | 说明 | 
|---|---|---|
| log_id | number | 调用的日志id | 
| result | jsonObject | 认证返回的结果 | 
| +score | float | 与公安数据源人脸图相似度可能性,用于验证生活照与公安数据源人脸图是否为同一人,有正常分数时为[0~100],推荐阈值80,超过即判断为同一人 | 
| +verify_status | number | 认证状态,取值如下: 0 : 正常 1 : 身份证号与姓名不匹配或该身份证号不存在 2 : 公安网图片不存在或质量过低 | 
| dec_image | string | 对SDK传入的加密图片进行解密。 仅APP场景且进行了图片加密时,此参数返回解密后的人脸图片信息 | 
| risk_level | string | 判断设备是否发生过风险行为来判断风险级别,取值(数值由高到低): 1 – 高危 2 – 嫌疑 3 – 普通 4 – 正常 | 
| risk_tag | string | 风险标签,若判断为有风险,则会有风险标签json 数组告知风险类型 例如:general_inject | 
返回示例
1{
2    "log_id": 1370579072568000512,
3    "result": {
4        "score": 40.884,
5        "verify_status": 0
6    },
7    "dec_image": "/9j/4AAQSkZJRgABAgAAAQABAAD",
8    "risk_level": "3",
9    "risk_tag": [
10        "若判断为有风险,则会有风险标签json 数组告知风险类型,如:general_inject"
11    ]
12}人脸比对V4
能力介绍
1. 接口能力
- 两张人脸图片相似度对比:对比两张图片中人脸的相似度,并返回相似度分值;
- 多种图片类型:支持生活照、证件照、身份证芯片照、带网纹照四种类型的人脸对比;
- 活体检测控制:基于图片中的破绽分析,判断其中的人脸是否为二次翻拍(举例:如用户A用手机拍摄了一张包含人脸的图片一,用户B翻拍了图片一得到了图片二,并用图片二伪造成用户A去进行识别操作,这种情况普遍发生在金融开户、实名认证等环节。);
- 质量检测控制:分析图片的中人脸的模糊度、角度、光照强度等特征,判断图片质量;
- 
图片加密及风控:配合增强级、金融级采集SDK使用 - 对采集SDK输出的加密图片进行解密(加密传输可以有效避免第三方非法黑产绕过APP模拟请求攻击云端接口的行为,Eg:脚本攻击等);
- 以及结合百度安全实验室大数据风控能力,对采集SDK的发起端设备进行风控识别,辨别是否为风险设备,Eg:ROM注入、视频劫持等;
 
2. 业务应用
- 用于对比多张图片中的人脸相似度并返回两两对比的得分,可用于判断两张脸是否是同一人的可能性大小。
- 典型应用场景:如人证合一验证,用户认证等,可与您现有的人脸库进行对比验证。
1public void Demo() {
2  
3  // 必填参数
4	var image = "";
5	var imageType = "";
6  var registerImage = "";
7  var registerImageType = "";
8  
9  // 选填参数
10	var options = new Dictionary<string, object>{
11	    {"xxx", "xxx"},
12	};
13	
14	// 调用接口
15	result = client.faceMingJingMatch(image, imageType, registerImage, registerImageType, options);
16	Console.WriteLine(result);
17}请求参数
| 参数 | 必选 | 类型 | 说明 | 
|---|---|---|---|
| app | 否 | string | APP类型,配合采集SDK使用时须传入 ios:iOS端采集SDK android:安卓端采集SDK | 
| sec_level | 否 | string | SDK安全级别,配合采集SDK使用时须传入,默认common common : 配合4.1/4.1.5版本SDK使用,人脸图片未进行加密处理 lite:配合5.2版本SDK使用 | 
| skey | 否 | string | 使用5.2版本SDK请求时必填 从SDK获取的密钥信息 | 
| x_device_id | 否 | string | 使用5.2版本SDK请求时必填 从SDK获取的密钥信息 | 
| data | 否 | string | 使用5.2版本SDK请求时必填 SDK输出的加密数据 | 
| image | 是 | string | 图片信息(数据大小应小于10M 分辨率应小于1920*1080),*5.2版本SDK请求时已包含在加密数据data中,无需额外传入 | 
| image_type | 是 | string | 图片类型 BASE64 : 图片的base64值 URL : 图片的URL FACE_TOKEN : 人脸标识 默认 BASE64 | 
| face_type | 否 | string | 人脸的类型 LIVE:表示生活照:通常为手机、相机拍摄的人像图片、或从网络获取的人像图片等 IDCARD:表示身份证芯片照:二代身份证内置芯片中的人像照片 WATERMARK:表示带水印证件照:一般为带水印的小图,如公安网小图 CERT:表示证件照片:如拍摄的身份证、工卡、护照、学生证等证件图片 INFRARED 表示红外照片:使用红外相机拍摄的照片 默认LIVE | 
| quality_control | 否 | string | 质量控制 NONE: 不进行控制 LOW:较低的质量要求 NORMAL: 一般的质量要求 HIGH: 较高的质量要求 默认NONE | 
| liveness_control | 否 | string | 活体控制 NONE: 不进行控制 LOW:较低的活体要求(高通过率 低攻击拒绝率) NORMAL: 一般的活体要求(平衡的攻击拒绝率, 通过率) HIGH: 较高的活体要求(高攻击拒绝率 低通过率) 默认NONE | 
| registerimage | 是 | string | 图片信息(总数据大小应小于10M),图片上传方式根据imagetype来判断。本图片特指客户服务器上传图片,非加密图片Base64值 | 
| registerimagetype | 是 | string | 图片类型 BASE64 : 图片的base64值 URL : 图片的 URL FACE_TOKEN : 人脸标识 默认 BASE64 | 
| registerfacetype | 否 | string | 人脸的类型 | 
| registerqualitycontrol | 否 | string | 图片质量控制 NONE: 不进行控制 LOW:较低的质量要求 NORMAL: 一般的质量要求 HIGH: 较高的质量要求 默认 NONE 若图片质量不满足要求,则返回结果中会提示质量检测失败 | 
| registerlivenesscontrol | 否 | string | 活体检测控制 NONE: 不进行控制 LOW:较低的活体要求(高通过率 低攻击拒绝率) NORMAL: 一般的活体要求(平衡的攻击拒绝率, 通过率) HIGH: 较高的活体要求(高攻击拒绝率 低通过率) 默认 NONE 若活体检测结果不满足要求,则返回结果中会提示活体检测失败 | 
| facesorttype | 否 | int | 人脸检测排序类型 0:代表检测出的人脸按照人脸面积从大到小排列 1:代表检测出的人脸按照距离图片中心从近到远排列 默认为0 | 
返回参数
| 参数名 | 类型 | 说明 | 
|---|---|---|
| log_id | number | 调用的日志id | 
| result | jsonObject | 认证返回的结果 | 
| + score | number | 人脸相似度得分,推荐阈值80分 | 
| + face_list | jsonArray | 人脸信息列表 | 
| ++ face_token | string | 人脸标志 | 
| dec_image | string | APP场景传入加密图片时,该项返回解密后的图片 | 
| risk_level | string | 风控返回参数,只有在 risk_identify 为 true 时才返回,判断设备是否发生过风险行为来判断风险级别,取值(数值有高到低): 1 – 高危 2 – 嫌疑 3 – 普通 4 – 正常 | 
| risk_tag | jsonArray | 风控返回参数,只有在 risk_identify 为 true 时才返回,风险标签,若判断为有风险,则会有风险标签 json 数组告知风险类型 | 
| risk_warn_code | number | 风控返回参数,只有在 risk_identify 为 true 时才返回,只有在风控服务异常的时候才返回这个字段 | 
返回示例
1  {
2    "log_id": 1370585066551377920,
3    "result": {
4        "score": 99.06919861,
5        "face_list": [
6            {
7                "face_token": "549f9f1d1c7ec8c86931540b1939e8ed"
8            },
9            {
10                "face_token": "1a319460ef89e8d27fb59062a28dbad7"
11            }
12        ]
13    },
14    "dec_image": "/9j/4AAQSkZJRgABAQAAAQABAAD",
15    "risk_level": "3",
16    "risk_tag": [
17        "空"
18    ]
19}
20 在线图片活体V4
能力介绍
1. 接口能力
- 人脸基础信息:包括人脸框位置,人脸空间旋转角度,人脸置信度等信息。
- 人脸质量检测:判断人脸的遮挡、光照、模糊度、完整度等质量信息。可用于判断上传的人脸是否符合标准。
- 基于图片的活体检测:基于单张图片,判断图片中的人脸是否为二次翻拍(举例:如用户A用手机拍摄了一张包含人脸的图片一,用户B翻拍了图片一得到了图片二,并用图片二伪造成用户A去进行识别操作,这种情况普遍发生在金融开户、实名认证等环节)以及是否为合成图攻击。此能力可用于H5场景下的一些人脸采集场景中,增加人脸注册的安全性和真实性。
- 图片加密及风控:配合采集SDK5.0版本使用,对采集SDK输出的加密图片进行解密(加密传输可以有效避免第三方非法黑产绕过APP模拟请求攻击云端接口的行为,Eg:脚本攻击等); 以及结合百度安全实验室大数据风控能力,对采集SDK的发起端设备进行风控识别,辨别是否为风险设备,Eg:ROM注入、视频劫持等;
1public void Demo() {
2  
3  // 必填参数
4	var sdkVersion = "";
5  
6  // 选填参数
7	var options = new Dictionary<string, object>{
8	    {"xxx", "xxx"},
9	};
10	
11	// 调用接口
12	result = client.onlinePictureLiveV4(sdkVersion, options);
13	Console.WriteLine(result);
14}请求参数
| 参数 | 是否必选 | 类型 | 说明 | 
|---|---|---|---|
| sdk_version | 是 | string | 1 :非加密图片,适用于4.1/4.1.5版本SDK、H5场景或纯服务端场景 4:适用于5.2版本SDK | 
| face_field | 否 | string | 包括age,expression,face_shape,gender,glasses,landmark,quality,face_type,spoofing信息,逗号分隔,默认只返回face_token、活体数、人脸框、概率和旋转角度 | 
| option | 否 | string | 场景信息,程序会视不同的场景选用相对应的模型。当前支持的场景有COMMON(通用场景),GATE(闸机场景),FINANCE(金融场景),LOGISTICS(物流场景),INTERNET(泛互联网场景), 默认使用COMMON 。注意:如果请求参数中存在多个option值时,则取第一个option的值,同时除通用场景外的其他场景需要联系工作人员对您所使用的appid进行配置 | 
| app | 否 | string | 端类型 ios / android 5.2版本SDK必传该项 | 
| s_key | 否 | string | 端上提供的用于解密图片的skey 5.2版本SDK必传该项 | 
| device_id | 否 | string | 端上提供的用于解密图片的deviceId 5.2版本SDK必传该项 | 
| data | 否 | string | 端上提供的加密后的图片数组 5.2版本SDK必传该项 | 
| image_list | 否 | array | 图片BASE64数组 4.1/4.1.5版本SDK、H5场景或纯服务端场景必填 | 
返回参数
| 参数 | 是否必须 | 类型 | 说明 | 
|---|---|---|---|
| log_id | 是 | string | 日志id | 
| error_code | 是 | int | 错误码状态,若为0则表示认证成功 | 
| error_msg | 是 | string | 错误码说明,若为 success 则表示认证成功 | 
| result | 是 | object | 活体结果 | 
| +face_liveness | 是 | float | 活体分数值 | 
| +thresholds | 是 | array | 由服务端返回最新的阈值数据(随着模型的优化,阈值可能会变化),将此参数与返回的face_liveness进行比较,可以作为活体判断的依据。 frr_1e-4:万分之一误识率的阈值; frr_1e-3:千分之一误识率的阈值; frr_1e-2:百分之一误识率的阈值。 误识率越低,准确率越高,相应的拒绝率也越高 | 
| +face_list | 是 | array | 每张图片的详细信息描述,如果只上传一张图片,则只返回一个结果。 | 
| ++face_token | 是 | string | 人脸图片的唯一标识 | 
| ++location | 是 | array | 人脸在图片中的位置 | 
| +++left | 是 | double | 人脸区域离左边界的距离 | 
| +++top | 是 | double | 人脸区域离上边界的距离 | 
| +++width | 是 | double | 人脸区域的宽度 | 
| +++height | 是 | double | 人脸区域的高度 | 
| +++rotation | 是 | int64 | 人脸框相对于竖直方向的顺时针旋转角,[-180,180] | 
| ++face_probability | 是 | double | 人脸置信度,范围【0~1】,代表这是一张人脸的概率,0最小、1最大。 | 
| ++angel | 是 | array | 人脸旋转角度参数 | 
| +++yaw | 是 | double | 三维旋转之左右旋转角[-90(左), 90(右)] | 
| +++pitch | 是 | double | 三维旋转之俯仰角度[-90(上), 90(下)] | 
| +++roll | 是 | double | 平面内旋转角[-180(逆时针), 180(顺时针)] | 
| ++age | 否 | double | 年龄 ,当face_field包含age时返回 | 
| ++expression | 否 | array | 表情,当 face_field包含expression时返回 | 
| +++type | 否 | string | none:不笑;smile:微笑;laugh:大笑 | 
| +++probability | 否 | double | 表情置信度,范围【0~1】,0最小、1最大。 | 
| ++face_shape | 否 | array | 脸型,当face_field包含face_shape时返回 | 
| +++type | 否 | double | square: 正方形 triangle:三角形 oval: 椭圆 heart: 心形 round: 圆形 | 
| +++probability | 否 | double | 置信度,范围【0~1】,代表这是人脸形状判断正确的概率,0最小、1最大。 | 
| ++gender | 否 | array | 性别,face_field包含gender时返回 | 
| +++type | 否 | string | male:男性 female:女性 | 
| +++probability | 否 | double | 性别置信度,范围【0~1】,0代表概率最小、1代表最大。 | 
| ++glasses | 否 | array | 是否带眼镜,face_field包含glasses时返回 | 
| ++type | 否 | string | none:无眼镜,common:普通眼镜,sun:墨镜 | 
| +++probability | 否 | double | 眼镜置信度,范围【0~1】,0代表概率最小、1代表最大。 | 
| ++face_type | 否 | array | 真实人脸/卡通人脸 face_field包含face_type时返回 | 
| +++type | 否 | string | human: 真实人脸 cartoon: 卡通人脸 | 
| +++probability | 否 | double | 人脸类型判断正确的置信度,范围【0~1】,0代表概率最小、1代表最大。 | 
| ++landmark | 否 | array | 4个关键点位置,左眼中心、右眼中心、鼻尖、嘴中心。face_field包含landmark时返回 | 
| ++landmark72 | 否 | array | 72个特征点位置 face_field包含landmark时返回 | 
| ++quality | 否 | array | 人脸质量信息。face_field包含quality时返回 | 
| +++occlusion | 否 | array | 人脸各部分遮挡的概率,范围[0~1],0表示完整,1表示不完整 | 
| ++++left_eye | 否 | double | 左眼遮挡比例,[0-1] , 1表示完全遮挡 | 
| ++++right_eye | 否 | double | 右眼遮挡比例,[0-1] , 1表示完全遮挡 | 
| ++++nose | 否 | double | 鼻子遮挡比例,[0-1] , 1表示完全遮挡 | 
| ++++mouth | 否 | double | 嘴巴遮挡比例,[0-1] , 1表示完全遮挡 | 
| ++++left_cheek | 否 | double | 左脸颊遮挡比例,[0-1] , 1表示完全遮挡 | 
| ++++right_cheek | 否 | double | 右脸颊遮挡比例,[0-1] , 1表示完全遮挡 | 
| ++++chin | 否 | double | 下巴遮挡比例,,[0-1] , 1表示完全遮挡 | 
| +++blur | 否 | double | 人脸模糊程度,范围[0~1],0表示清晰,1表示模糊 | 
| +++illumination | 否 | double | 取值范围在[0~255], 表示脸部区域的光照程度 越大表示光照越好 | 
| +++completeness | 否 | int64 | 人脸完整度,0或1, 0为人脸溢出图像边界,1为人脸都在图像边界内 | 
| ++spoofing | 否 | double | 合成图打分 判断图片是否为合成图 face_field包含时返回spoofing | 
| risk_level | 否 | string | 判断设备是否发生过风险行为来判断风险级别,取值(数值有高到低):1 – 高危 2 – 嫌疑 3 – 普通 4 – 正常 | 
| risk_tag | 否 | string | 风险标签,若判断为有风险,则会有风险标签 json 数组告知风险类型 | 
| dec_image | 否 | array | 非安全加固增强级采集sdk、非安全加固金融级采集sdk、安全加固增强级采集sdk、安全加固金融级采集sdk会返回解密后的原图 | 
返回示例
1{
2    "result": {
3        "thresholds": {
4            "frr_1e-3": 0.3,
5            "frr_1e-2": 0.9,
6            "frr_1e-4": 0.05
7        },
8        "face_liveness": 0.1976952702,
9        "face_list": [
10            {
11                "liveness": {
12                    "livemapscore": 0.1976952702
13                },
14                "angle": {
15                    "roll": 0.31,
16                    "pitch": -2.07,
17                    "yaw": 0.85
18                },
19                "face_token": "abd1b4ce743099336cfed40193ff4944",
20                "location": {
21                    "top": 161.74,
22                    "left": 79.04,
23                    "rotation": 1,
24                    "width": 318,
25                    "height": 333
26                },
27                "face_probability": 1
28            },
29            {
30                "liveness": {
31                    "livemapscore": 0.1976952702
32                },
33                "angle": {
34                    "roll": 0.31,
35                    "pitch": -2.07,
36                    "yaw": 0.85
37                },
38                "face_token": "abd1b4ce743099336cfed40193ff4944",
39                "location": {
40                    "top": 161.74,
41                    "left": 79.04,
42                    "rotation": 1,
43                    "width": 318,
44                    "height": 333
45                },
46                "face_probability": 1
47            },
48            {
49                "liveness": {
50                    "livemapscore": 0.1976952702
51                },
52                "angle": {
53                    "roll": 0.31,
54                    "pitch": -2.07,
55                    "yaw": 0.85
56                },
57                "face_token": "abd1b4ce743099336cfed40193ff4944",
58                "location": {
59                    "top": 161.74,
60                    "left": 79.04,
61                    "rotation": 1,
62                    "width": 318,
63                    "height": 333
64                },
65                "face_probability": 1
66            },
67            {
68                "liveness": {
69                    "livemapscore": 0.1976952702
70                },
71                "angle": {
72                    "roll": 0.31,
73                    "pitch": -2.07,
74                    "yaw": 0.85
75                },
76                "face_token": "abd1b4ce743099336cfed40193ff4944",
77                "location": {
78                    "top": 161.74,
79                    "left": 79.04,
80                    "rotation": 1,
81                    "width": 318,
82                    "height": 333
83                },
84                "face_probability": 1
85            },
86            {
87                "liveness": {
88                    "livemapscore": 0.1976952702
89                },
90                "angle": {
91                    "roll": 0.31,
92                    "pitch": -2.07,
93                    "yaw": 0.85
94                },
95                "face_token": "abd1b4ce743099336cfed40193ff4944",
96                "location": {
97                    "top": 161.74,
98                    "left": 79.04,
99                    "rotation": 1,
100                    "width": 318,
101                    "height": 333
102                },
103                "face_probability": 1
104            },
105            {
106                "liveness": {
107                    "livemapscore": 0.1976952702
108                },
109                "angle": {
110                    "roll": 0.31,
111                    "pitch": -2.07,
112                    "yaw": 0.85
113                },
114                "face_token": "abd1b4ce743099336cfed40193ff4944",
115                "location": {
116                    "top": 161.74,
117                    "left": 79.04,
118                    "rotation": 1,
119                    "width": 318,
120                    "height": 333
121                },
122                "face_probability": 1
123            },
124            {
125                "liveness": {
126                    "livemapscore": 0.1976952702
127                },
128                "angle": {
129                    "roll": 0.31,
130                    "pitch": -2.07,
131                    "yaw": 0.85
132                },
133                "face_token": "abd1b4ce743099336cfed40193ff4944",
134                "location": {
135                    "top": 161.74,
136                    "left": 79.04,
137                    "rotation": 1,
138                    "width": 318,
139                    "height": 333
140                },
141                "face_probability": 1
142            },
143            {
144                "liveness": {
145                    "livemapscore": 0.1976952702
146                },
147                "angle": {
148                    "roll": 0.31,
149                    "pitch": -2.07,
150                    "yaw": 0.85
151                },
152                "face_token": "abd1b4ce743099336cfed40193ff4944",
153                "location": {
154                    "top": 161.74,
155                    "left": 79.04,
156                    "rotation": 1,
157                    "width": 318,
158                    "height": 333
159                },
160                "face_probability": 1
161            }
162        ]
163    },
164    "risk_level": "3",
165    "log_id": 1423545654699779516,
166    "risk_tag": [
167        "空"
168    ],
169    "dec_image": [
170            "/9j/4AAQ..."
171    ]
172}FAQ
1. 调用接口时抛出异常:基础连接已关闭
此问题一般是网络原因,请检查网络相关问题:
- 检查网络连通性
- 检查网络是否有代理
2. SSL报错 "The authentication or decryption has failed"
可能由于网络代理等原因导致证书不正确,属于常见的https问题,可以参考这个答案。 如果报此错,请开发者务必关注HTTPS安全。
3. 调用接口,等待一段时间后出现超时
可以设置Timeout参数。
4. 在.Net Core下运行报错 'GBK' is not a supported encoding name'
添加System.Text.Encoding.CodePages引用,并注册。 Encoding.RegisterProvider(CodePagesEncodingProvider.Instance)
错误信息
错误返回格式
若请求错误,服务器将返回的JSON文本包含以下参数:
- error_code:错误码。
- error_msg:错误描述信息,帮助理解和解决发生的错误。
错误码
| 错误码 | 错误信息 | 描述 | 
|---|---|---|
| 1 | Unknown error | 服务器内部错误,请再次请求, 如果持续出现此类错误,请通过QQ群(860337848)或提交工单联系技术支持团队。 | 
| 2 | Service temporarily unavailable | 服务暂不可用,请再次请求, 如果持续出现此类错误,请通过QQ群(860337848)或提交工单联系技术支持团队。 | 
| 3 | Unsupported openapi method | 调用的API不存在,请检查请求URL后重新尝试,一般为URL中有非英文字符,如“-”,可手动输入重试 | 
| 4 | Open api request limit reached | 集群超限额,请再次请求, 如果持续出现此类错误,请通过QQ群(860337848)或提交工单联系技术支持团队。 | 
| 6 | No permission to access data | 无权限访问该用户数据,创建应用时未勾选相关接口 | 
| 13 | Get service token failed | 获取token失败 | 
| 14 | IAM Certification failed | IAM 鉴权失败 | 
| 15 | app not exsits or create failed | 应用不存在或者创建失败 | 
| 17 | Open api daily request limit reached | 每天请求量超限额,可通过QQ群(860337848)联系群管、提交工单提升限额 | 
| 18 | Open api qps request limit reached | QPS超限额,可通过QQ群(860337848)联系群管、提交工单提升限额 | 
| 19 | Open api total request limit reached | 请求总量超限额,可通过QQ群(860337848)联系群管、提交工单提升限额 | 
| 100 | Invalid parameter | 无效的access_token参数,请检查后重新尝试 | 
| 110 | Access token invalid or no longer valid | access_token无效 | 
| 111 | Access token expired | access token过期 | 
| 222001 | param[] is null | 必要参数未传入 | 
| 222002 | param[start]  format error | 参数格式错误 | 
| 222003 | param[length]  format error | 参数格式错误 | 
| 222004 | param[op_app_id_list] format error | 参数格式错误 | 
| 222005 | param[group_id_list] format error | 参数格式错误 | 
| 222006 | group_id format error | 参数格式错误 | 
| 222007 | uid format error | 参数格式错误 | 
| 222008 | face_id format error | 参数格式错误 | 
| 222009 | quality_conf  format error | 参数格式错误 | 
| 222010 | user_info format error | 参数格式错误 | 
| 222011 | param[uid_list] format error | 参数格式错误 | 
| 222012 | param[op_app_id] format error | 参数格式错误 | 
| 222013 | param[image]  format error | 参数格式错误 | 
| 222014 | param[app_id]  format error | 参数格式错误 | 
| 222015 | param[image_type] format error | 参数格式错误 | 
| 222016 | param[max_face_num] format error | 参数格式错误 | 
| 222017 | param[face_field] format error | 参数格式错误 | 
| 222018 | param[user_id] format error | 参数格式错误 | 
| 222019 | param[quality_control] format error | 参数格式错误 | 
| 222020 | param[liveness_control] format error | 参数格式错误 | 
| 222021 | param[max_user_num] format error | 参数格式错误 | 
| 222022 | param[id_card_number] format error | 参数格式错误 | 
| 222023 | param[name] format error | 参数格式错误 | 
| 222024 | param[face_type] format error | 参数格式错误 | 
| 222025 | param[face_token] format error | 参数格式错误 | 
| 222026 | param[max_star_num] format error | 参数格式错误 | 
| 222201 | network not available | 服务端请求失败 | 
| 222202 | pic not has face | 图片中没有人脸 | 
| 222203 | image check fail | 无法解析人脸 | 
| 222204 | image_url_download_fail | 从图片的url下载 图片失败 | 
| 222205 | network not availablel | 服务端请求失败 | 
| 222206 | rtse service return fail | 服务端请求失败 | 
| 222207 | match user is not found | 未找到匹配的用户 | 
| 222208 | the number of image is incorrect | 图片的数量错误 | 
| 222209 | face token not exist | face token不存在 | 
| 222300 | add face fail | 人脸图片添加失败 | 
| 222301 | get face fail | 获取人脸图片失败 | 
| 222302 | system error | 服务端请求失败 | 
| 222303 | get face fail | 获取人脸图片失败 | 
| 223100 | group is not exist | 操作的用户组不存在 | 
| 223101 | group is already exist | 该用户组已存在 | 
| 223102 | user is already exist | 该用户已存在 | 
| 223103 | user is not exist | 找不到该用户 | 
| 223104 | group_list is too large | group_list包含组 数量过多 | 
| 223105 | face is already exist | 该人脸已存在 | 
| 223106 | face is not exist | 该人脸不存在 | 
| 223110 | uid_list is too large | uid_list包含数量过多 | 
| 223111 | dst group is not exist | 目标用户组不存在 | 
| 223112 | quality_conf format error | quality_conf格式不正确 | 
| 223113 | face is covered | 人脸有被遮挡 | 
| 223114 | face is fuzzy | 人脸模糊 | 
| 223115 | face light is not good | 人脸光照不好 | 
| 223116 | incomplete face | 人脸不完整 | 
| 223117 | app_list is too large | app_list包含app数量 过多 | 
| 223118 | quality control error | 质量控制项错误 | 
| 223119 | liveness control item error | 活体控制项错误 | 
| 223120 | liveness check fail | 活体检测未通过 | 
| 223121 | left eye is occlusion | 质量检测未通过 左眼 遮挡程度过高 | 
| 223122 | right eye is occlusion | 质量检测未通过 右眼 遮挡程度过高 | 
| 223123 | left cheek is occlusion | 质量检测未通过 左脸 遮挡程度过高 | 
| 223124 | right cheek is occlusion | 质量检测未通过 右脸 遮挡程度过高 | 
| 223125 | chin contour is occlusion | 质量检测未通过 下巴遮挡程度过高 | 
| 223126 | nose is occlusion | 质量检测未通过 鼻子遮挡程度过高 | 
| 223127 | mouth is occlusion | 质量检测未通过 嘴巴 遮挡程度过高 | 
| 222350 | police picture is none or low quality | 公安网图片不存在或 质量过低 | 
| 222351 | id number and name not match or id number not exist | 身份证号与姓名不匹配或该 身份证号不存在 | 
| 222352 | name format error | 身份证名字格式错误 | 
| 222353 | id number format error | 身份证号码格式错误 | 
| 222354 | id number not exist | 公安库里不存在此身份证号 | 
| 222355 | police picture not exist | 身份证号码正确,公安库里没有 对应的照片 | 
| 222360 | invalid name or id number | 身份证号码或名字非法(公安网校 验不通过) | 
| 222901 | system busy | 系统繁忙 | 
| 222902 | system busy | 系统繁忙 | 
| 222903 | system busy | 系统繁忙 | 
| 222904 | system busy | 系统繁忙 | 
| 222905 | system busy | 系统繁忙 | 
| 222906 | system busy | 系统繁忙 | 
| 222907 | system busy | 系统繁忙 | 
| 222908 | system busy | 系统繁忙 | 
| 222909 | system busy | 系统繁忙 | 
| 222910 | system busy | 系统繁忙 | 
| 222911 | system busy | 系统繁忙 | 
| 222912 | system busy | 系统繁忙 | 
| 222913 | system busy | 系统繁忙 | 
| 222914 | system busy | 系统繁忙 | 
| 222915 | system busy | 系统繁忙 | 
| 222916 | system busy | 系统繁忙 | 
| 222361 | system busy | 系统繁忙 | 
