开放能力
开发平台
行业应用
生态合作
开发与教学
资讯 社区 控制台
技术能力
语音技术
图像技术
文字识别
人脸与人体识别
视频技术
AR与VR
自然语言处理
知识图谱
数据智能
场景方案
部署方案
行业应用
智能教育
智能医疗
智能零售
智能工业
企业服务
智能政务
智能农业
信息服务
智能园区
智能硬件
人脸识别

    人脸库管理

    概述

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

    错误码

    请参考人脸识别错误码

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