人脸识别

    人脸库管理

    概述

    人脸识别接口分为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"
    }

    错误码

    请参考人脸识别错误码

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