人脸库管理

更新时间：2019-11-24

概述

人脸识别接口分为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为人脸都在图像边界内	视业务逻辑判断
人脸大小	人脸部分的大小建议长宽像素值范围：8080~200200	人脸部分不小于*100100**像素

调用方式

请求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"
}

错误码

请参考人脸识别错误码

人脸查找

身份验证