人脸库管理
所有文档

          人脸识别

          人脸库管理

          概述

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

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

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

          能力介绍

          业务能力

          人脸库管理相关接口,要完成1:N或者M:N识别,首先需要构建一个人脸库,用于存放所有人脸特征,相关接口如下:

          • 人脸注册:向人脸库中添加人脸
          • 人脸更新:更新人脸库中,指定用户下的人脸信息
          • 人脸删除:删除人脸库中的某个用户
          • 用户信息查询:查询人脸库中某个用户的详细信息
          • 组列表查询:查询人脸库中用户组的列表
          • 组内用户列表查询:查询指定用户组中的用户列表
          • 组间复制用户:将已经存在于人脸库中的用户复制到一个新的组
          • 组内删除用户:将指定用户从某个组中删除,但不会删除用户在其它组的信息

          人脸库结构

          人脸库、用户组、用户、用户下的人脸层级关系如下所示:

          |- 人脸库(appid)
             |- 用户组一(group_id)
                |- 用户01(uid)
                   |- 人脸(faceid)
                |- 用户02(uid)
                   |- 人脸(faceid)
                   |- 人脸(faceid)
                   ....
                 ....
             |- 用户组二(group_id)
             |- 用户组三(group_id)
             ....

          关于人脸库的设置限制

          • 每个开发者账号可以创建100个appid;
          • 每个appid对应一个人脸库,且不同appid之间,人脸库互不相通
          • 每个人脸库下,可以创建多个用户组,用户组(group)数量没有限制
          • 每个用户组(group)下,可添加最多无限张人脸,无限个uid;
          • 每个用户(uid)所能注册的最大人脸数量20

          提醒:每个人脸库对应一个appid,一定确保不要轻易删除后台应用列表中的appid,删除后则此人脸库将失效,无法进行任何查找!

          质量判断

          为了保证识别效果,请控制注册人脸的质量(通过/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像素

          调用方式

          请求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/faceset/user/add?access_token=24.f9ba9c5341b67688ab6added8bc91dec.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/faceset/user/add

          URL参数:

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

          Header如下:

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

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

          请求参数

          参数 必选 类型 说明
          uid string 用户id(由数字、字母、下划线组成),长度限制128B。
          group_id string 用户组id,标识一组用户(由数字、字母、下划线组成),长度限制128B。如果需要将一个uid注册到多个group下,group_id需要用多个逗号分隔,每个group_id长度限制为48个英文字符。注:group无需单独创建,注册用户时则会自动创建group。
          产品建议:根据您的业务需求,可以将需要注册的用户,按照业务划分,分配到不同的group下,例如按照会员手机尾号作为groupid,用于刷脸支付、会员计费消费等,这样可以尽可能控制每个group下的用户数与人脸数,提升检索的准确率
          image string base64编码后的图片数据,需urlencode,每次只支持单张图片,编码后的图片大小不超过10M。为保证后续识别的效果较佳,建议注册的人脸,为用户正面人脸,且保持人脸都在图片之内
          user_info string 用户资料,长度限制256B
          action_type string 参数包含app、replace。如果为“replace”,则每次注册时进行替换replace(新增或更新)操作,默认为append操作。例如:uid在库中已经存在时,对此uid重复注册时,新注册的图片默认会追加到该uid下,如果手动选择action_type:replace,则会用新图替换库中该uid下所有图片。

          说明:人脸注册完毕后,生效时间一般为5s以内,之后便可以进行识别或认证操作。

          请求代码示例

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

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

          {% Face-API-Add %}

          返回说明

          返回参数

          字段 必选 类型 说明
          log_id uint64 请求标识码,随机数,唯一

          返回示例

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

          人脸更新

          接口描述

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

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

          说明:在uid不存在时,调用此接口,会报错。如果希望此uid不在人脸库中时,创建这个uid,请添加action_type:replace,注册该uid,操作结果等同注册新用户。

          请求说明

          注意事项

          • 请求体格式化: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/faceset/user/update

          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
          user_info string 用户信息,长度限制256位
          group_id string 更新指定groupid下uid对应的信息
          action_type string 在uid不存在时,调用此接口,会报错。
          如果希望此uid不在人脸库中时,创建这个uid,请添加replace参数,
          注册该uid,操作结果等同注册新用户

          请求代码示例

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

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

          {% Face-API-Update %}

          返回说明

          返回参数

          字段 必选 类型 说明
          log_id uint64 请求标识码,随机数,唯一

          返回示例

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

          人脸删除

          接口描述

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

          人脸删除注意事项

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

          请求说明

          请求示例

          HTTP方法:POST

          请求URL: https://aip.baidubce.com/rest/2.0/face/v2/faceset/user/delete

          URL参数:

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

          Header如下:

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

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

          请求参数

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

          请求代码示例

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

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

          {% Face-API-Delete %}

          返回说明

          返回参数

          字段 必选 类型 说明
          log_id uint64 请求标识码,随机数,唯一

          返回示例

          // 删除成功
          {
              "log_id": 73473737,
          }
          // 删除发生错误
          {
            "error_code": 216612,
            "log_id": 1382953199,
            "error_msg": "user not exist"
          }

          用户信息查询

          接口描述

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

          请求说明

          请求示例

          HTTP方法:POST

          请求URL: https://aip.baidubce.com/rest/2.0/face/v2/faceset/user/get

          URL参数:

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

          Header如下:

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

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

          请求参数

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

          请求代码示例

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

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

          {% Face-API-UserGet %}

          返回说明

          返回参数

          字段 必选 类型 说明
          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
          }

          组列表查询

          接口描述

          用于查询用户组的列表。

          请求说明

          请求示例

          HTTP方法:POST

          请求URL: https://aip.baidubce.com/rest/2.0/face/v2/faceset/group/getlist

          URL参数:

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

          Header如下:

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

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

          请求参数

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

          请求代码示例

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

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

          {% Face-API-GroupGetlist %}

          返回说明

          返回参数

          字段 必选 类型 说明
          log_id uint64 请求标识码,随机数,唯一
          result_num uint32 返回个数
          result array(string) group_id列表

          返回示例

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

          组内用户列表查询

          接口描述

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

          请求说明

          请求示例

          HTTP方法:GET

          请求URL: https://aip.baidubce.com/rest/2.0/face/v2/faceset/group/getusers

          URL参数:

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

          Header如下:

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

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

          请求参数

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

          请求代码示例

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

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

          {% Face-API-GroupGetusers %}

          返回说明

          返回参数

          字段 必选 类型 说明
          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"
                  }
              ]
          }

          组间复制用户

          接口描述

          用于将已经存在于人脸库中的用户复制到一个新的组

          说明:并不是向一个指定组内添加用户,而是直接从其它组复制用户信息 如果需要注册用户,请直接使用人脸注册接口

          请求说明

          请求示例

          HTTP方法:POST

          请求URL: https://aip.baidubce.com/rest/2.0/face/v2/faceset/group/adduser

          URL参数:

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

          Header如下:

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

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

          请求参数

          参数 必选 类型 说明
          group_id string 需要添加信息的组id,多个的话用逗号分隔
          uid string 用户id
          src_group_id string 从指定group里复制信息

          请求代码示例

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

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

          {% Face-API-GroupAdduser %}

          返回说明

          返回参数

          字段 必选 类型 说明
          log_id uint64 请求标识码,随机数,唯一

          返回示例

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

          组内删除用户

          接口描述

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

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

          请求说明

          请求示例

          HTTP方法:POST

          请求URL: https://aip.baidubce.com/rest/2.0/face/v2/faceset/group/deleteuser

          URL参数:

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

          Header如下:

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

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

          请求参数

          参数 必选 类型 说明
          group_id string 用户组id,多个的话用逗号分隔
          uid string 用户id

          请求代码示例

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

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

          {% Face-API-GroupDeleteuser %}

          返回说明

          返回参数

          字段 必选 类型 说明
          log_id uint64 请求标识码,随机数,唯一

          返回示例

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

          错误码

          请参考人脸识别错误码

          上一篇
          人脸查找
          下一篇
          身份验证