人脸查找
所有文档

          人脸识别

          人脸查找

          概述

          人脸识别接口分为V2和V3两个版本,本文档为V2版本接口的说明文档,请确认您在百度云后台获得的是V2版本接口权限,再来阅读本文档。

          辨别接口版本的方法是:在百度云后台进入【应用列表】,点击【应用名称】,在【API列表】中可以看到【请求地址】,若请求地址中带有【v2】标识,则您具有的是v2权限,可以阅读本文档;若请求地址中带有【v3】标识,则您具有的是v3权限,应该去阅读v3文档。 如果您对文档内容有任何疑问,可以通过以下几种方式联系我们:

          • 在百度云控制台内 提交工单,咨询问题类型请选择人工智能服务
          • 如有需要讨论的疑问,欢迎进入 AI社区 与其他开发者们一同交流。

          能力介绍

          业务能力

          • 1:N人脸识别:也称为1:N识别,在指定人脸集合中,找到最相似的人脸;
          • 1:N人脸认证:基于uid维度的1:N识别,由于uid已经锁定固定数量的人脸,所以检索范围更聚焦;
          • M:N多人脸识别:也称为M:N识别,待识别图片中含有多个人脸时,在指定人脸集合中,找到这多个人脸分别最相似的人脸;

          1:N人脸识别1:N人脸认证的差别在于:人脸识别是在指定人脸集合中进行直接地人脸检索操作,而人脸认证是基于uid,先调取这个uid对应的人脸,再在这个uid对应的人脸集合中进行检索(因为每个uid通常对应的只有一张人脸,所以通常也就变为了1:1对比);实际应用中,人脸认证需要用户或系统先输入id,这增加了验证安全度,但也增加了复杂度,具体使用哪个接口需要视您的业务场景判断。

          M:N识别的原理,相当于在多个人脸的图片中,先分别找出所有人脸,然后分别在待查找的人脸集合中,分别做1:N识别,最后将识别结果汇总在一起进行返回。

          提示:进行人脸查找相关操作前,建议先阅读 人脸库管理 相关内容。

          调用方式

          请求URL数据格式

          向API服务地址使用POST发送请求,必须在URL中带上参数access_token,可通过后台的API Key和Secret Key生成,具体方式请参考“Access Token获取”。

          获取access_token的示例代码

          {% AccessToken %}

          注意access_token的有效期为30天,切记需要每30天进行定期更换,或者每次请求都拉取新token

          例如此接口,使用HTTPS POST发送:

          https://aip.baidubce.com/rest/2.0/face/v2/identify?access_token=24.f9ba9c5341b67688ab4added8bc91dec.2592000.1485570332.282335-8574074

          POST中Body的参数,按照下方请求参数说明选择即可。

          提示:如果您为百度云老用户,正在使用其他非AI的服务,可以参考百度云AKSK鉴权方式发送请求,虽然请求方式鉴权方法和本文所介绍的不同,但请求参数和返回结果一致。

          人脸识别

          接口描述

          用于计算指定组内用户,与上传图像中人脸的相似度。识别前提为您已经创建了一个人脸库

          典型应用场景:如人脸闸机考勤签到安防监控等。

          说明:人脸识别返回值不直接判断是否是同一人,只返回用户信息及相似度分值。

          提示:进行人脸查找相关操作前,建议先阅读 人脸库管理 相关内容。

          请求说明

          注意事项

          • 请求体格式化:Content-Type为application/x-www-form-urlencoded,通过urlencode格式化请求体。
          • Base64编码:请求的图片需经过Base64编码,图片的base64编码指将图片数据编码成一串字符串,使用该字符串代替图像地址。您可以首先得到图片的二进制,然后用Base64格式编码即可。需要注意的是,图片的base64编码是不包含图片头的,如data:image/jpg;base64,
          • 图片格式:现支持PNG、JPG、JPEG、BMP,不支持GIF图片
          • 人脸识别接口分为V2和V3两个版本,本文档为V2版本接口的说明文档,请确认您在百度云后台获得的是V2版本接口权限,再来阅读本文档。

          辨别接口版本的方法是:在百度云后台进入【应用列表】,点击【应用名称】,在【API列表】中可以看到【请求地址】,若请求地址中带有【v2】标识,则您具有的是v2权限,可以阅读本文档;若请求地址中带有【v3】标识,则您具有的是v3权限,应该去阅读v3文档。

          请求示例

          HTTP方法:POST

          请求URL: https://aip.baidubce.com/rest/2.0/face/v2/identify

          URL参数:

          参数
          access_token 通过API Key和Secret Key获取的access_token,参考“Access Token获取

          Header:

          参数
          Content-Type application/x-www-form-urlencoded

          Body中放置请求参数,参数详情如下:

          请求参数

          参数 必选 类型 说明
          image string base64编码后的图片数据,需urlencode,每次只支持单张图片,编码后的图片大小不超过10M
          group_id string 用户组id(由数字、字母、下划线组成),长度限制128B,如果需要查询多个用户组id,用逗号分隔
          ext_fields string 特殊返回信息,多个用逗号分隔,取值固定: 目前支持faceliveness(活体检测)。注:需要用于判断活体的图片,图片中的人脸像素面积需要不小于100px*100px,人脸长宽与图片长宽比例,不小于1/3
          user_top_num uint32 识别后返回的用户top数,默认为1,最多返回5个

          请求代码示例

          提示一:使用示例代码前,请记得替换其中的示例Token、图片地址或Base64信息。

          提示二:部分语言依赖的类或库,请在代码注释中查看下载地址。

          {% Face-API-Identify %}

          返回说明

          返回参数

          字段 必选 类型 说明
          log_id uint64 请求唯一标识码,随机数
          result_num uint32 返回结果数目,即:result数组中元素个数
          ext_info array 对应参数中的ext_fields
          +faceliveness string 活体检测分数,单帧活体检测参考阈值0.3,超过此分值以上则可认为是活体。注意:活体检测接口主要用于判断是否为二次翻拍,需要限制用户为当场拍照获取图片;推荐配合客户端SDK有动作校验活体使用
          result array(object) 结果数组
          +group_id string 对应的这个用户的group_id
          +uid string 匹配到的用户id
          +user_info string 注册时的用户信息
          +scores array(double) 结果数组,数组元素为匹配得分,top n。得分[0,100.0]。推荐80分作为阈值,80分以上可以判断为同一人,此分值对应万分之一误识率。

          返回示例

          {
              "log_id": 73473737,
              "result_num":1,
              "result": [
                  {
                      "group_id" : "test1",
                      "uid": "u333333",
                      "user_info": "Test User",
                      "scores": [
                              99.3,
                              83.4
                      ]
                  }
              ]
          }

          关于活体检测faceliveness的判断阈值选择,可参考以下数值信息

          阈值(Threshold) 误拒率(FRR) 通过率(TAR) 攻击拒绝率(TRR))
          0.05 0.01% 99.99% 97.75%
          0.1 0.05% 99.95% 98.33%
          0.3 (推荐 0.1% 99.9% 98.82%
          0.5 0.5% 99.5% 99.67%
          0.9 1% 99% 99.77%

          关于以上数值的概念介绍

          • 拒绝率(TRR):如99%,代表100次作弊假体攻击,会有99次被拒绝。
          • 误拒率(FRR):如0.5%,指1000次真人请求,会有5次因为活体分数低于阈值被错误拒绝。
          • 通过率(TAR):如99%,指100次真人请求,会有99次因为活体分数高于阈值而通过。
          • 阈值(Threshold):高于此数值,则可判断为活体。

          人脸认证

          接口描述

          用于识别上传的图片是否为指定用户,即查找前需要先确定要查找的用户在人脸库中的id。

          典型应用场景:如人脸登录人脸签到

          提示:进行人脸查找相关操作前,建议先阅读 人脸库管理 相关内容。

          请求说明

          注意事项

          • 请求体格式化:Content-Type为application/x-www-form-urlencoded,通过urlencode格式化请求体。
          • Base64编码:请求的图片需经过Base64编码,图片的base64编码指将图片数据编码成一串字符串,使用该字符串代替图像地址。您可以首先得到图片的二进制,然后用Base64格式编码即可。需要注意的是,图片的base64编码是不包含图片头的,如data:image/jpg;base64,
          • 图片格式:现支持PNG、JPG、JPEG、BMP,不支持GIF图片

          请求示例

          HTTP方法:POST

          请求URL: https://aip.baidubce.com/rest/2.0/face/v2/verify

          URL参数:

          参数
          access_token 通过API Key和Secret Key获取的access_token,参考“Access Token获取

          Header如下:

          参数
          Content-Type application/x-www-form-urlencoded

          Body中放置请求参数,参数详情如下:

          请求参数

          参数 必选 类型 说明
          uid string 用户id(由数字、字母、下划线组成),长度限制128B
          image string base64编码后的图片数据,需urlencode,每次只支持单张图片,编码后的图片大小不超过10M
          group_id string 用逗号分隔,表示从指定的group中查找
          top_num uint32 返回匹配得分top数,默认为1
          ext_fields string 特殊返回信息,多个用逗号分隔,取值固定: 目前支持faceliveness(活体检测)。注:需要用于判断活体的图片,图片中的人脸像素面积需要不小于100px*100px,人脸长宽与图片长宽比例,不小于1/3

          请求代码示例

          提示一:使用示例代码前,请记得替换其中的示例Token、图片地址或Base64信息。

          提示二:部分语言依赖的类或库,请在代码注释中查看下载地址。

          {% Face-API-Verify %}

          返回说明

          返回参数

          字段 必选 类型 说明
          log_id uint64 请求唯一标识码,随机数
          result_num uint32 返回结果数目,即:result数组中元素个数
          result array(double) 结果数组,数组元素为匹配得分,top n。 得分范围[0,100.0]。超过80分可认为认证成功
          ext_info array 对应参数中的ext_fields
          +faceliveness string 活体检测分数,单帧活体检测参考阈值0.3,超过此分值以上则可认为是活体。活体检测接口主要用于判断是否为二次翻拍,需要限制用户为当场拍照获取图片;推荐配合客户端SDK有动作校验活体使用

          返回示例

          {
              "log_id": 73473737,
              "result_num":2,
              "result": [
                      99.3,
                      83.6
              ]
          }

          关于活体检测faceliveness的判断阈值选择,可参考以下数值信息

          阈值(Threshold) 误拒率(FRR) 通过率(TAR) 攻击拒绝率(TRR))
          0.05 0.01% 99.99% 97.75%
          0.1 0.05% 99.95% 98.33%
          0.3 (推荐 0.1% 99.9% 98.82%
          0.5 0.5% 99.5% 99.67%
          0.9 1% 99% 99.77%

          关于以上数值的概念介绍

          • 拒绝率(TRR):如99%,代表100次作弊假体攻击,会有99次被拒绝。
          • 误拒率(FRR):如0.5%,指1000次真人请求,会有5次因为活体分数低于阈值被错误拒绝。
          • 通过率(TAR):如99%,指100次真人请求,会有99次因为活体分数高于阈值而通过。
          • 阈值(Threshold):高于此数值,则可判断为活体。

          M:N 识别

          待识别的图片中,存在多张人脸的情况下,支持在一个人脸库中,一次请求,同时返回图片中所有人脸的识别结果。

          提示:进行人脸查找相关操作前,建议先阅读 人脸库管理 相关内容。

          请求说明

          注意事项

          • 请求体格式化:Content-Type为application/x-www-form-urlencoded,通过urlencode格式化请求体。
          • Base64编码:请求的图片需经过Base64编码,图片的base64编码指将图片数据编码成一串字符串,使用该字符串代替图像地址。您可以首先得到图片的二进制,然后用Base64格式编码即可。需要注意的是,图片的base64编码是不包含图片头的,如data:image/jpg;base64,
          • 图片格式:现支持PNG、JPG、JPEG、BMP,不支持GIF图片

          请求示例

          HTTP方法:POST

          请求URL: https://aip.baidubce.com/rest/2.0/face/v2/multi-identify

          URL参数:

          参数
          access_token 通过API Key和Secret Key获取的access_token,参考“Access Token获取

          Header如下:

          参数
          Content-Type application/x-www-form-urlencoded

          Body中放置请求参数,参数详情如下:

          请求参数

          参数 必选 类型 说明
          image string base64编码后的图片数据,需urlencode,每次只支持单张图片,编码后的图片大小不超过10M
          group_id string 用户组id(由数字、字母、下划线组成),长度限制128B,用户组id,如果有多个,用逗号分隔,最多支持10个,不允许出现空ID重复ID
          ext_fields string 特殊返回信息,多个用逗号分隔,取值固定: 目前支持faceliveness(活体检测)。注:需要用于判断活体的图片,图片中的人脸像素面积需要不小于100px*100px,人脸长宽与图片长宽比例,不小于1/3
          detect_top_num uint32 检测多少个人脸进行比对,默认值1(最对返回10个)
          user_top_num uint32 返回识别结果top数,当同一个人有多张图片时,只返回比对最高的1个分数(即,scores参数只有一个值),默认为1(最多返回20个)

          返回说明

          返回参数

          参数 字段 必选 类型 说明
          log_id - uint32 请求标识码,随机数,唯一
          result_num - float 返回结果数目,即:result数组中元素个数(PS:最终返回的个数是小于等于 “实际检测到的人脸数” * “每个人脸匹配的top人数”)
          ext_info - array 对应参数中的ext_fields
          - faceliveness string 活体检测分数,单帧活体检测参考阈值0.3,超过此分值以上则可认为是活体。注意:活体检测接口主要用于判断是否为二次翻拍,需要限制用户为当场拍照获取图片;推荐配合客户端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}

          返回示例

          {
              "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
                      ]
                  }
              ]
          }

          关于活体检测faceliveness的判断阈值选择,可参考以下数值信息

          阈值(Threshold) 误拒率(FRR) 通过率(TAR) 攻击拒绝率(TRR))
          0.05 0.01% 99.99% 97.75%
          0.1 0.05% 99.95% 98.33%
          0.3 (推荐 0.1% 99.9% 98.82%
          0.5 0.5% 99.5% 99.67%
          0.9 1% 99% 99.77%

          关于以上数值的概念介绍

          • 拒绝率(TRR):如99%,代表100次作弊假体攻击,会有99次被拒绝。
          • 误拒率(FRR):如0.5%,指1000次真人请求,会有5次因为活体分数低于阈值被错误拒绝。
          • 通过率(TAR):如99%,指100次真人请求,会有99次因为活体分数高于阈值而通过。
          • 阈值(Threshold):高于此数值,则可判断为活体。

          错误码

          请参考人脸识别错误码

          上一篇
          人脸对比
          下一篇
          人脸库管理