百度人脸识别SDK学习

　　之前看到同事说人脸识别多么高大上之类的， 我就好奇搜索了一下， 本人是小白级别，喜欢用百度多一点，所以就使用了百度的人脸识别SDK进行研究。不得不说百度提供的完档很详细，在学习过程中很少出现不能解决的问题， 所以本人也偷个懒，把sdk文档复制下来。

　　注：貌似有个bug,我在百度语音中菜单下创建的人脸识别，然后获取API_key和Secret_key, 在学习尝试过程中， 或多或少有请求量， 但是报表中却没有任何记录， 难道是bug吗？ 我在想是不是可以无限制的调用了，作为尝试， 没去批量去测试，感兴趣的小伙伴可以试试

 

准备工作：

1、需要有百度账号（没有的话可以注册）

注册地址： https://login.bce.baidu.com/

注册登录之后，在“产品服务” 菜单下找到人脸识别 

 

点击去创建自己的应用名称，其实最主要的就是 API_key  和 Secret_key

 

有了这些就可以进一步去看 百度提供的SDK 文档了。

这是百度的SDK地址：http://ai.baidu.com/sdk

选择自己喜欢的开发语言进行研究， 里面文档很详细， 下载中有Demo 

本人采用的是C# 进行研究。

参考地址：http://ai.baidu.com/docs#/Face-Csharp-SDK/top

 

主要接口：

接口名称	接口能力简要描述
人脸检测	检测人脸并定位，返回五官关键点，及人脸各属性值
人脸比对	返回两两比对的人脸相似值
人脸识别	在人脸库中查找相似的人脸
人脸认证	识别上传的图片是否为指定用户
人脸库设置	对人脸库的相关操作，如注册、删除、更新、查找用户信息等

 

快速入门

安装人脸 C# SDK

人脸 C# SDK目录结构

Baidu.Aip
   ├── AipSdk.dll                          // 百度AI服务 windows 动态库
   ├── AipSdk.XML                          // DLL注释
   ├── Demo/                              // Demo文件夹
   └── thirdparty                         // 第三方依赖

支持平台：.Net Framework 3.5 及以上版本

使用步骤

1.在官方网站下载C# SDK压缩工具包。

2.解压后，将 AipSdk.dll 和 thirdparty 中 的dll文件添加为引用。

3.如需使用demo，将 Demo 文件夹中相关Demo文件添加至工程即可。

使用SDK

Baidu.Aip.Face是主要命名空间，基本使用方法如下：

var APP_ID = "你的 App ID";
var API_KEY = "你的 Api Key";
var SECRET_KEY = "你的 Secret Key";

var client = new Baidu.Aip.Face.Face(API_KEY, SECRET_KEY);
var image = File.ReadAllBytes("图片文件");
var options = new Dictionary<string, object>()
{
    {"face_fields", "beauty,age"}
};
// 过程中发生的网络失败等系统错误，将会抛出相关异常，请使用 try/catch 捕获。
var result = client.FaceDetect(image, options);

在上面代码中，常量APP_ID在百度云控制台中创建，常量API_KEY与SECRET_KEY是在创建完毕应用后，系统分配给用户的，均为字符串，用于标识用户，为访问做签名验证，可在AI服务控制台中的应用列表中查看。

注意：如您以前是百度云的老用户，其中API_KEY对应百度云的“Access Key ID”，SECRET_KEY对应百度云的“Access Key Secret”。

接口说明

人脸检测

接口描述

检测请求图片中的人脸，返回人脸位置、72个关键点坐标、及人脸相关属性信息。

检测响应速度，与图片中人脸数量相关，人脸数量较多时响应时间会有些许延长。

典型应用场景：如人脸属性分析，基于人脸关键点的加工分析，人脸营销活动等。

五官位置会标记具体坐标；72个关键点坐标也包含具体坐标，但不包含对应位置的详细位置描述。

请求说明

图片接受类型支持本地图片路径字符串，图片文件二进制数组。

举例，要对一张图片进行人脸识别，具体的人脸信息在返回的result字段中。自定的参数在options字典中：

public static void FaceDetect()
{
    var client = new Baidu.Aip.Face.Face("Api Key", "Secret Key");
    var image = File.ReadAllBytes("图片文件路径");
    var options = new Dictionary<string, object>()
    {
        {"face_fields", "beauty,age"}
    };
    var result = client.FaceDetect(image, options);
}

人脸检测 请求参数详情

参数	类型	描述	是否必须
face_fields	string	包括age、beauty、expression、faceshape、gender、glasses、landmark、race、qualities信息，逗号分隔，默认只返回人脸框、概率和旋转角度。	否
max_face_num	number	最多处理人脸数目，默认值1	是
image	byte[]	图像数据	是

返回说明

参数	类型	是否一定输出	描述
log_id	number	是	日志id
result_num	number	是	人脸数目
result	array	是	人脸属性对象的集合
+age	number	否	年龄。face_fields包含age时返回
+beauty	number	否	美丑打分，范围0-1，越大表示越美。face_fields包含beauty时返回
+location	array	是	人脸在图片中的位置
++left	number	是	人脸区域离左边界的距离
++top	number	是	人脸区域离上边界的距离
++width	number	是	人脸区域的宽度
++height	number	是	人脸区域的高度
+face_probability	number	是	人脸置信度，范围0-1
+rotation_angle	number	是	人脸框相对于竖直方向的顺时针旋转角，[-180,180]
+yaw	number	是	三维旋转之左右旋转角[-90(左), 90(右)]
+pitch	number	是	三维旋转之俯仰角度[-90(上), 90(下)]
+roll	number	是	平面内旋转角[-180(逆时针), 180(顺时针)]
+expression	number	否	表情，0，不笑；1，微笑；2，大笑。face_fields包含expression时返回
+expression_probability	number	否	表情置信度，范围0~1。face_fields包含expression时返回
+faceshape	array	否	脸型置信度。face_fields包含faceshape时返回
++type	string	是	脸型：square/triangle/oval/heart/round
++probability	number	是	置信度：0~1
+gender	string	否	male、female。face_fields包含gender时返回
+gender_probability	number	否	性别置信度，范围0~1。face_fields包含gender时返回
+glasses	number	否	是否带眼镜，0-无眼镜，1-普通眼镜，2-墨镜。face_fields包含glasses时返回
+glasses_probability	number	否	眼镜置信度，范围0~1。face_fields包含glasses时返回
+landmark	array	否	4个关键点位置，左眼中心、右眼中心、鼻尖、嘴中心。face_fields包含landmark时返回
++x	number	否	x坐标
++y	number	否	y坐标
+landmark72	array	否	72个特征点位置，示例图 。face_fields包含landmark时返回
++x	number	否	x坐标
++y	number	否	y坐标
+race	string	否	yellow、white、black、arabs。face_fields包含race时返回
+race_probability	number	否	人种置信度，范围0~1。face_fields包含race时返回
+qualities	array	否	人脸质量信息。face_fields包含qualities时返回
++occlusion	array	是	人脸各部分遮挡的概率， [0, 1] （待上线）
+++left_eye	number	是	左眼
+++right_eye	number	是	右眼
+++nose	number	是	鼻子
+++mouth	number	是	嘴
+++left_cheek	number	是	左脸颊
+++right_cheek	number	是	右脸颊
+++chin	number	是	下巴
++type	array	是	真实人脸/卡通人脸置信度
+++human	number	是	真实人脸置信度，[0, 1]
+++cartoon	number	是	卡通人脸置信度，[0, 1]

人脸比对

接口描述

该请求用于比对多张图片中的人脸相似度并返回两两比对的得分，可用于判断两张脸是否是同一人的可能性大小。

典型应用场景：如人证合一验证，用户认证等，可与您现有的人脸库进行比对验证。

说明：支持对比对的两张图片做在线活体检测

请求说明

public static void FaceMatch()
{
    var client = new Baidu.Aip.Face.Face("Api Key", "Secret Key");
    var image1 = File.ReadAllBytes("图片文件路径");
    var image2 = File.ReadAllBytes("图片文件路径");

    var images = new byte[][] {image1, image2};

    // 人脸对比
    var result = client.FaceMatch(images);
}

人脸比对请求参数：

所有图片经base64编码后的图片数据总和不超过10M。以下可选参数放在接口最后的options参数中。

参数	是否必选	类型	说明
ext_fields	否	string	返回质量信息，取值固定: 目前支持qualities(质量检测)。(对所有图片都会做改处理)
image_liveness	否	string	返回的活体信息，“faceliveness,faceliveness” 表示对比对的两张图片都做活体检测；“,faceliveness” 表示对第一张图片不做活体检测、第二张图做活体检测；“faceliveness,” 表示对第一张图片做活体检测、第二张图不做活体检测

返回说明

字段	是否必选	类型	说明
log_id	是	number	请求唯一标识码，随机数
result_num	是	number	返回结果数目，即：result数组中元素个数
result	是	array	结果数据，index和请求图片index对应。数组元素为每张图片的匹配得分数组，top n。 得分[0,100.0]
+index_i	是	number	比对图片1的index
+index_j	是	number	比对图片2的index
+score	是	double	比对得分
ext_info	否	array	对应参数中的ext_fields
+qualities	否	string	质量相关的信息，无特殊需求可以不使用
+faceliveness	否	string	活体分数“0,0.9999”（表示第一个图不做活体检测、第二个图片活体分数为0.9999）。活体检测参考分数0.4494，以上则可认为是活体（测试期间）

返回样例：

//请求为四张图片，第三张解析失败
{
    "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，您也可以根据业务需求选择更合适的阈值。

请求说明

public static void FaceIdentify()
{
    var client = new Baidu.Aip.Face.Face("Api Key", "Secret Key");
    var image1 = File.ReadAllBytes("图片文件路径");

    var result = client.User.Identify(image1, new []{"groupId"}, 1, 1);
}

人脸识别请求参数详情：

参数	是否必选	类型	说明
group_id	是	string	用户组id（由数字、字母、下划线组成）列表，每个groupid长度限制48
image	是	byte[]	图像数据
ext_fields	否	string	特殊返回信息，多个用逗号分隔，取值固定: 目前支持 faceliveness(活体检测)
user_top_num	否	number	返回用户top数，默认为1，最多返回5个

返回说明

字段	是否必选	类型	说明
log_id	是	number	请求唯一标识码，随机数
result_num	是	number	返回结果数目，即：result数组中元素个数
ext_info	否	array	对应参数中的ext_fields
+faceliveness	否	string	活体分数，如0.49999。活体检测参考分数0.4494，以上则可认为是活体（测试期间
result	是	array	结果数组
+group_id	是	string	对应的这个用户的group_id
+uid	是	string	匹配到的用户id
+user_info	是	string	注册时的用户信息
+scores	是	array	结果数组，数组元素为匹配得分，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中是否为uid的用户：

public static void FaceVerify()
{
    var client = new Baidu.Aip.Face.Face("Api Key", "Secret Key");
    var image1 = File.ReadAllBytes("图片文件路径");

    var result = client.User.Verify(image1, "uid", new []{"groupId"}, 1);
}

人脸认证请求参数详情：

可选参数均放在接口最后的options参数中。

参数	是否必选	类型	说明
uid	是	string	用户id（由数字、字母、下划线组成），长度限制128B
image	是	byte[]	图像数据
group_id	是	string	用户组id（由数字、字母、下划线组成）列表，每个groupid长度限制48
top_num	否	number	返回匹配得分top数，默认为1
ext_fields	否	string	特殊返回信息，多个用逗号分隔，取值固定: 目前支持 faceliveness(活体检测)

返回说明

字段	是否必选	类型	说明
log_id	是	number	请求唯一标识码，随机数
result_num	是	number	返回结果数目，即：result数组中元素个数
result	是	array	结果数组，数组元素为匹配得分，top n。 得分范围[0,100.0]。推荐得分超过80可认为认证成功
ext_info	否	array	对应参数中的ext_fields
+faceliveness	否	string	活体分数，如0.49999。活体检测参考分数0.4494，以上则可认为是活体（测试期间）

返回样例：

{
  "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为uid，加入组id为group1, 注册成功后服务端会返回操作的logid：

public static void FaceRegister()
{
    var client = new Baidu.Aip.Face.Face("Api Key", "Secret Key");
    var image1 = File.ReadAllBytes("图片文件路径");

    var result = client.User.Register(image1, "uid", "user info here", new []{"groupId"});
}

人脸注册请求参数要求：

所有图片经base64编码后的图片数据总和不超过10M。

人脸注册返回数据参数详情：

参数	是否必选	类型	说明
uid	是	string	用户id（由数字、字母、下划线组成），长度限制128B
image	是	byte[]	图片数据
group_id	是	string	用户组id（由数字、字母、下划线组成），长度限制48
user_info	是	string	新的user_info信息
action_type	否	string	如果为replace时，则uid不存在时，不报错，会自动注册。 不存在该参数时，如果uid不存在会提示错误

返回说明

字段	是否必选	类型	说明
log_id	是	number	请求标识码，随机数，唯一

返回样例：

// 注册成功
{
    "log_id": 73473737,
}
// 注册发生错误
{
  "error_code": 216616,
  "log_id": 674786177,
  "error_msg": "image exist"
}

人脸更新

接口描述

用于对人脸库中指定用户，更新其下的人脸图像。

说明：针对一个uid执行更新操作，新上传的人脸图像将覆盖此uid原有所有图像。

说明：执行更新操作，如果该uid不存在时，会返回错误。如果添加了action_type:replace,则不会报错，并自动注册该uid，操作结果等同注册新用户。

请求说明

举例，要更新一个用户，用户id为uid， 更新成功后服务端会返回操作的logid：

public static void FaceUpdate()
 {
     var client = new Baidu.Aip.Face.Face("Api Key", "Secret Key");
     var image1 = File.ReadAllBytes("图片文件路径");

     var result = client.User.Update(image1, "uid", "groupId", "new user info");
 }

人脸更新请求参数详情：

参数	是否必选	类型	说明
uid	是	string	用户id（由数字、字母、下划线组成），长度限制128B
image	是	byte[]	图片数据
group_id	是	string	用户组id（由数字、字母、下划线组成），长度限制48
user_info	是	string	新的user_info信息

返回说明

字段	是否必选	类型	说明
log_id	是	number	请求标识码，随机数，唯一

// 更新成功
{
    "log_id": 73473737,
}
// 更新发生错误
{
  "error_code": 216612,
  "log_id": 1137508902,
  "error_msg": "user not exist"
}

人脸删除

接口描述

用于从人脸库中删除一个用户。

人脸删除注意事项：

• 删除的内容，包括用户所有图像和身份信息；
• 如果一个uid存在于多个用户组内且没有指定group_id，将会同时将从各个组中把用户删除
• 如果指定了group_id，则只删除此group下的uid相关信息

请求说明

public static void FaceDelete()
{
    var client = new Baidu.Aip.Face.Face("Api Key", "Secret Key");
    var result = client.User.Delete("uid");
    result = client.User.Delete("uid", new []{"group1"});
}

人脸删除请求参数要求：

参数	是否必选	类型	说明
uid	是	string	用户id（由数字、字母、下划线组成），长度限制128B
group_id	是	string	删除指定group_id中的uid信息

返回说明

人脸删除返回数据参数详情：

字段	是否必选	类型	说明
log_id	是	number	请求标识码，随机数，唯一

返回样例：

// 更新成功
{
    "log_id": 73473737,
}
// 更新发生错误
{
  "error_code": 216612,
  "log_id": 1137508902,
  "error_msg": "user not exist"
}

用户信息查询

接口描述

用于查询人脸库中某用户的详细信息。

请求说明

举例，要查询指定用户的信息：

public static void UserInfo()
 {
     var client = new Baidu.Aip.Face.Face("Api Key", "Secret Key");
     var result = client.User.GetInfo("uid");
 }

用户信息查询请求参数要求：

以下可选参数放在接口最后的options参数中。

参数	是否必选	类型	说明
uid	是	string	用户id（由数字、字母、下划线组成），长度限制128B
group_id	否	string	选择指定group_id则只查找group列表下的uid内容，如果不指定则查找所有group下对应uid的信息

用户信息查询返回数据参数详情：

字段	是否必选	类型	说明
log_id	是	number	请求标识码，随机数，唯一
result	是	array	结果数组
+uid	是	string	匹配到的用户id
+user_info	是	string	注册时的用户信息
+groups	是	array	用户所属组列表

返回样例：

{
    "result": {
        "uid": "testuser2",
        "user_info": "registed user info ...",
        "groups": [
            "grp1",
            "grp2",
            "grp3"
        ]
    },
    "log_id": 2979357502
}

组列表查询

接口描述

用于查询用户组的列表。

请求说明

举例：

public static void GroupList()
{
   var client = new Baidu.Aip.Face.Face("Api Key", "Secret Key");
   var result = client.Group.GetAllGroups(0, 100);
}

组列表查询请求参数详情：

参数	是否必选	类型	说明
start	否	number	默认值0，起始序号
num	否	number	返回数量，默认值100，最大值1000

组列表查询返回数据参数详情：

字段	是否必选	类型	说明
log_id	是	number	请求标识码，随机数，唯一
result_num	是	number	返回个数
result	是	array	group_id列表

返回样例：

{
    "result_num": 2,
    "result": [
        "grp1",
        "grp2"
    ],
    "log_id": 3314921889
}

组内用户列表查询

接口描述

用于查询指定用户组中的用户列表。

请求说明

举例：

public static void GroupUsers()
{
    var client = new Baidu.Aip.Face.Face("Api Key", "Secret Key");
    var result = client.Group.GetUsers("groupId", 0, 100);
}

组内用户列表查询请求参数详情：

参数	是否必选	类型	说明
group_id	是	string	用户组id
start	否	number	默认值0，起始序号
num	否	number	返回数量，默认值100，最大值1000

组内用户列表查询返回数据参数详情：

字段	是否必选	类型	说明
log_id	是	number	请求标识码，随机数，唯一
result_num	是	number	返回个数
result	是	array	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 static void GroupAddUser()
{
    var client = new Baidu.Aip.Face.Face("Api Key", "Secret Key");
    var result = client.Group.AddUser(new []{"toGroupId"}, "uid", "fromGroupId");
}

组间复制用户请求参数详情：

参数	是否必选	类型	说明
src_group_id	是	string	从指定group里复制信息
group_id	是	string	需要添加信息的组id列表
uid	是	string	用户id

####返回说明

字段	是否必选	类型	说明
log_id	是	number	请求标识码，随机数，唯一

返回样例：

// 正确返回值 
{
    "log_id": 3314921889,
}
// 发生错误时返回值 
{
  "error_code": 216100,
  "log_id": 3111284097,
  "error_msg": "already add"
}

组内删除用户

接口描述

用于将用户从某个组中删除，但不会删除用户在其它组的信息。

说明：当用户仅属于单个分组时，本接口将返回错误，请使用人脸删除接口

请求说明

举例：

public static void GroupDeleteUser()
{
    var client = new Baidu.Aip.Face.Face("Api Key", "Secret Key");
    var result = client.Group.DeleteUser(new []{"groupId"}, "uid");
}

组内删除用户请求参数详情：

参数	是否必选	类型	说明
group_id	是	string	用户组id列表
uid	是	string	用户id

返回说明

字段	是否必选	类型	说明
log_id	是	number	请求标识码，随机数，唯一

返回样例：

// 正确返回值 
{
    "log_id": 3314921889,
}
// 发生错误时返回值 
{
  "error_code": 216619,
  "log_id": 815967402,
  "error_msg": "user must be in one group at least"
}

错误信息

错误返回格式

若请求错误，服务器将返回的JSON文本包含以下参数：

• error_code：错误码。
• error_msg：错误描述信息，帮助理解和解决发生的错误。

错误码

错误码	错误信息	描述
4	Open api request limit reached	集群超限额
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	用户不存在，请确认该用户是否注册或注册已经生效(需要已经注册超过35s）
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是否存在或已经生效(需要已经注册超过35s)
216631	request add user overlimit	本次请求添加的用户数量超限