FaceManage 人脸库管理接口

  1. 新建人脸分组
  2. 编辑人脸分组
  3. 设置生人到熟人的迁移条件
  4. 删除人脸分组
  5. 获取人脸分组列表
  6. 新增人脸的属性
  7. 删除人脸的属性
  8. 获取指定人脸分组新增属性列表
  9. 新增人脸
  10. 删除人脸
  11. 更新人脸
  12. 获取人脸
  13. 获取人脸列表
  14. 获取到达时间最旧的人脸

1. 新建人脸分组

描述

通过此接口新建一个人脸分组，并配置其属性。人脸分组当前最多支持10个，系统默认存在两个人脸分组，分别是生人分组和熟人分组，即用户最多还可以创建8个分组。

接口

public void createGroup(String deviceId, String groupName, int capacity, String description, RPCCallback‹RPCResponse› callback);

参数说明

参数名称描述示例
deviceIdIPC序列号C201D98T00094
name 分组名称，不长于32个汉字，目前系统默认存在“生人”和 “熟人”两个分组生人
capacity 分组容量，所有分组容量加起来不得超过3W10000
description 分组的描述，不超过50个汉字。黑卡的客户
callback调用结果

注：

1. 名称第一个字符不得为空格 ；

2. 默认生人库名为stranger，默认熟人库名为regular 。

响应参数

字段名称 类型 描述
code int 返回码，表示操作的结果；
本接口返回码有：0、1、2、3、5、7、200、201、202、211、212、220，见错误码的描述

2. 编辑人脸分组

描述

通过此接口编辑指定人脸分组的属性。

接口

public void updateGroup(String deviceId, String oldGroupName, String groupName, int capacity, String description, RPCCallback‹RPCResponse› callback);

参数说明

参数名称描述示例
deviceIdIPC序列号C201D98T00094
oldGroupName 要编辑的人脸分组名称 黑卡客户
groupName 修改后的分组名称，可与旧的一样 金卡客户
capacity 修改后的分组容量，可与旧的一样 10000
description 分组的描述，不超过50个汉字。 办卡升级
callback调用结果

注：

1.修改默认生人分组和熟人分组的属性时候，name必须与old_name一致，即不允许修改默认分组的组名；

2.名称第一个字符不得为空格。

响应参数

字段名称 类型 描述
code int 返回码，表示操作的结果；
本接口返回码有：0、1、2、3、5、7、200、201、202、204、211、212、220，见错误码的描述

3. 设置生人到熟人的迁移条件

描述

系统在激活时会默认创建生人分组和熟人分组两个组，且设备会默认把某个生人来的次数满足一定条件（默认7天内来了5次）的情况下，自动把这个生人移动到熟人分组。

通过此接口可修改生人移动到熟人分组的移动条件。

接口

public void updateMigration(String deviceId, int arrive_times, int period, RPCCallback‹RPCResponse› callback);

参数说明

参数名称描述示例
deviceIdIPC序列号C201D98T00094
arrive_times 必选，生人分组才需要的属性，取值范围1~10 5
period 必选，生人分组才需要的属性，取值范围1~100，单位为天 20
callback调用结果

注：

arrive_times和period是生人分组才需要修改的属性，代表一个生人在一定时间内（period设置，单位为天）来过多少次（arrive_times设置）就移动到熟人分组中去。 

响应参数

字段名称 类型 描述
code int 返回码，表示操作的结果；
本接口返回码有：0、1、2、3、5、7、204、211、220，见错误码的描述

4. 删除人脸分组

描述

删除指定人脸分组。

接口

public void deleteGroup(String deviceId, String groupName, RPCCallback‹RPCResponse› callback);

参数说明

参数名称描述示例
deviceIdIPC序列号C201D98T00094
groupName 要删除的分组名称，生人和熟人分组不能被删除，分组中有人脸也不能删除，只能先清空。 黑卡客户
callback调用结果

响应参数

字段名称 类型 描述
code int 返回码，表示操作的结果；
本接口返回码有：0、1、2、3、5、7、201、204、205、211、220，见错误码的描述

5. 获取人脸分组列表

描述

通过此接口获取IPC上所有的人脸分组信息。

接口

public void getGroupList(String deviceId, RPCCallback‹RPCResponse‹GroupBean›› callback);

参数说明

参数名称描述示例
deviceIdIPC序列号C201D98T00094
callback调用结果

响应参数

字段名称 类型 描述
code int 返回码，表示操作的结果；
本接口返回码有：0、1、2、3、5、7、211、220，见错误码的描述
dataGroupBean返回码成功才会有此字段，详见RPCResponse.GroupBean

6. 新增人脸的属性

描述

库中给每个人脸预置了一些属性，可以通过此接口为指定人脸分组中的人脸增加最多5个属性。

强烈建议在创建新分组后添加人脸前，按需求先调用本接口添加人脸的属性，而不是在添加人脸后中途调用本接口添加人脸ID属性。

接口

public void addFaceInfoItem(String deviceId, String groupName, List‹String› attrs, RPCCallback‹RPCResponse› callback);

参数说明

参数名称描述示例
deviceIdIPC序列号C201D98T00094
groupName 人脸分组名称 vip
attrs 类型为数组，属性名称列表,每个属性类型是string，属性长度最大为50字节 [“hobby”]
callback调用结果

注：

1. 默认库不允许添加人脸ID属性；

2. 以下字段作为保留字段，不允许作为新添加的属性名： group_name, pic, age, gender, faceid, age_range, arrive_times, pic_url, total_num, return_num。

响应参数

字段名称 类型 描述
code int 返回码，表示操作的结果；
本接口返回码有：0、1、2、3、5、7、204、211、220、240、241、242，见错误码的描述

7. 删除人脸的属性

描述

对于指定分组中的自定义属性，用户可以在不需要的时候删除，这里建议用户不要轻易删除。

接口

public void removeFaceInfoItem(String deviceId, String groupName, List‹String› attrs, RPCCallback‹RPCResponse› callback);

参数说明

参数名称描述示例
deviceIdIPC序列号C201D98T00094
groupName 人脸分组名称 vip
attrs 类型为数组，属性名称列表,每个属性类型是string，属性长度最大为50字节 [“hobby”]
callback调用结果

注：

默认库不允许删除人脸ID属性

响应参数

字段名称 类型 描述
code int 返回码，表示操作的结果；
本接口返回码有：0、1、2、3、5、7、204、211、220、240、241、242、243，见错误码的描述

8. 获取指定人脸分组新增属性列表

描述

通过此接口可以查询某个特定人脸分组中用户通过2.4.6指令添加的所有属性列表。

接口

public void getFaceInfoItem(String deviceId, String groupName, RPCCallback‹RPCResponse‹AttributesBean›› callback);

参数说明

参数名称描述示例
deviceIdIPC序列号C201D98T00094
groupName分组名称 stranger
callback调用结果

响应参数

字段名称 类型 描述
code int 返回码，表示操作的结果；
本接口返回码有：0、1、2、3、5、7、204、211、220，见错误码的描述
dataAttributesBean返回码成功才会有此字段，详见RPCResponse.AttributesBean

9. 新增人脸

描述

通过此接口可以向某个特定的人脸分组增加新人脸,并给每个人脸配置相关属性值。一次增加一个人脸。

接口

public void addFaceRecord(String deviceId, HashMap‹String, String› options, RPCCallback‹RPCResponse› callback);

参数说明

参数名称描述示例
deviceIdIPC序列号C201D98T00094
options人脸记录相关属性参数，详见以下options说明
callback调用结果

options说明

参数名称 类型 描述 是否 必须 示例
faceidstring人脸id，不超过16个英文字符YVip11024
pic file jpg/png格式的人脸图片文件，最大分辨率为1920*1080，大小在1MB以内 Y 11024.jpg
group_name string 分组名称 Y stranger
age int 预置属性，年龄 N 14
gender int 预置属性，性别，0表示未知，1表示男性，2表示女性 N 1
item1 string 自定义属性1 N value1
item2 string 自定义属性2 N value2
item3 string 自定义属性3 N value3
item4 string 自定义属性4 N value4
item5 string 自定义属性5 N value5

注：

1.上面的预置属性是IPC数据库中内置的人脸具备的属性，其他的item1/item2/item3/item4/item5是用户自定义属性，若要使用自定义属性，则要调用2.4.6一节的接口来添加自定义属性，如果用户没有先添加人脸属性，直接在这个接口加上对应属性的key-value，IPC设备是不会处理那些属性的；

2.对于age属性，如果不设定，则会由摄像头自动设置此人的年龄段；

3.对于gender，如果不设定，则会由摄像头自动设置此人的性别。

响应参数

字段名称 类型 描述 示例
code int 返回码，表示操作的结果；
本接口返回码有：0、1、2、3、5、7、204、206、208、210、211、220，见错误码的描述

10. 删除人脸

描述

通过此接口可以删除指定人脸分组中的某些人脸。

接口

public void deleteFaceRecord(String deviceId, String groupName, List‹String› faceidList, RPCCallback‹RPCResponse‹FaceDeleteSubResult›› callback);

参数说明

参数名称描述示例
deviceIdIPC序列号C201D98T00094
groupName 分组名称 vip
faceidList 人脸I列表 [“1988″,”2020”]
callback调用结果

响应参数

字段名称 类型 描述
code int 返回码，表示操作的结果；
本接口返回码有：0、1、2、3、5、7、204、211、220，见错误码的描述
dataFaceDeleteSubResult返回码成功才会有此字段，详见RPCResponse.FaceDeleteSubResult

11. 更新人脸

描述

更新指定的人脸信息。

接口

public void updateFaceRecord(String deviceId, HashMap‹String, String› options, RPCCallback‹RPCResponse› callback);

参数说明

参数名称描述示例
deviceIdIPC序列号C201D98T00094
options人脸记录相关属性参数，详见以下options说明
callback调用结果

options说明

参数名称 类型 描述 是否必须 示例
group_name string 人脸分组名称 Y stranger
faceid string 人脸ID Y 21
new_group_name string 新人脸分组名称 N VIP
pic file jpg/png格式的人脸图片文件，最大分辨率为1920*1080，大小不超过1MB N example.jpg
age int 预置属性，年龄 N 10
gender int 性别，可更新为1表示男性、2表示女性 N 1
item1 string 自定义属性1 N value1
item2 string 自定义属性2 N value2
item3 string 自定义属性3 N value3
item4 string 自定义属性4 N value4
item5 string 自定义属性5 N value5

响应参数

参数名称 类型 描述
code int 返回码，表示操作的结果；
本接口返回码有：0、1、2、3、5、7、204、207、208、210、211、220，见错误码的描述

注：

上述 hobby、vip_level、weight、phone_num 是用户自定义属性，对应item1/item2/item3/item4，自定义属性可以通过 2.4.6 一节的接口来添加。添加之后方可使用。

12. 获取人脸

描述

通过指定人脸ID获取人脸信息。

接口

public void getFaceRecord(String deviceId, String faceId, RPCCallback‹RPCResponse‹FaceRecordBean›› callback);

参数说明

参数名称描述示例
deviceIdIPC序列号C201D98T00094
faceId人脸ID105
callback调用结果

响应参数

参数名称 类型 描述
code int 返回码，表示操作的结果；
本接口返回码有：0、1、2、3、5、7、211，见错误码的描述
dataFaceRecordBean返回码成功才会有此字段，详见RPCResponse.FaceRecordBean

注：

上述point、hobby、vip_level、weight、height是用户自定义属性，对应item1/item2/item3/item4/itme5，自定义属性可以通过2.4.6一节的接口来添加。添加之后才有返回这些属性。

13. 获取人脸列表

描述

获取指定人脸分组的所有人脸信息。

接口

public void getFaceRecordList(String deviceId, String groupName, int pageNum, int pageSize, RPCCallback‹RPCResponse‹FaceRecordListBean›› callback);

参数说明

参数名称描述示例
deviceIdIPC序列号C201D98T00094
page_num 当前页码，默认值和最小值为1
page_size当前页面条目数，默认为10，范围为[1, 100]
options 详见options说明
callback调用结果

options说明

参数名称 类型 描述 是否必须 示例
group_name string 人脸分组名称 Y VIP
page_num int 当前页码，默认值和最小值为1 N 4
page_size int 当前页面条目数，默认为10，范围为[1, 100] N 10

返回示例

{    
“code”: 0,    
“data”: {        
“total_num”: 2,        
“num”: 2,        
“faceid_list”: [            
{                
“arrive_time”: 1566215929,                
“arrive_count”: 2,                
“faceid”: “3”,                
“point”: “113”,         //自定义属性                
“gender”: 2,                
“vip_level”: “3”,       //自定义属性                
“hobby”: “tennis”,      //自定义属性                 
“weight”: “60”,         //自定义属性                
“height”: “180”,        //自定义属性                
“age”: 10,                
“age_range”: 2            
},            
{                
“arrive_time”: 1566215998                
“arrive_count”: 1                 
“faceid”: “4”,                
“point”: “113”,         //自定义属性                
“gender”: 1,                
“vip_level”: “1”,       //自定义属性                
“hobby”: “tennis”,      //自定义属性                
“weight”: “60”,         //自定义属性                
“height”: “180”,        //自定义属性                
“age”: 10,                
“age_range”: 2            
}        
]    
}
}

14. 获取到达时间最旧的人脸

描述

获取指定人脸分组按到达时间排序最旧的N条人脸信息。

接口

public void getFaceByArrival(String deviceId, String groupName, int num, RPCCallback‹RPCResponse‹FaceRecordListBean›› callback);

参数说明

参数名称描述示例
deviceIdIPC序列号C201D98T00094
groupName 人脸分组名称 VIP
num获取人脸数量，默认值和最小值为1，最大值为10 2
callback调用结果

响应参数

参数名称 类型 描述
code int 返回码，表示操作的结果；
本接口返回码有：0、1、2、3、5、7、207、211，见错误码的描述
dataFaceRecordListBean返回码成功才会有此字段，详见RPCResponse.FaceRecordListBean

返回示例

{
    “code”: 0,
    “data”: {
        “return_num”: 2,
        “faceid_list”: [
            {
                “faceid”: “8”,
                “arrive_time”: 1566215929,
                “arrive_count”: 7,
                “age_range”: 5,
                “gender”: 1,
                “age”: 0,
                “item1”:value1, //自定义属性   
                “item2”:value2, //自定义属性   
                “item3”:value3, //自定义属性   
                “item4”:value4, //自定义属性   
                “item5”:value5 //自定义属性               
            },
            {
                “faceid”: “10”,
                “arrive_time”: 1566110525,
                “arrive_count”: 6,
                “age_range”: 4,
                “gender”: 2,
                “age”: 0,
                “item1”: value1, //自定义属性   
                “item2”:value2, //自定义属性   
                “item3”:value3, //自定义属性   
                “item4”:value4, //自定义属性   
                “item5”:value5 //自定义属性                   
            }
        ]
    }
}