资讯 社区 文档
技术能力
语音技术
文字识别
人脸与人体
图像技术
语言与知识
视频技术

人脸库管理

概述

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

错误码

请参考人脸识别错误码

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