Interfaces for Face Library Management

  1. Create a Face Group
  2. Edit a Face Group
  3. Set the Transfer Condition (From Stranger to Regular) 
  4. Delete a Face Group
  5. Get the List of Face Groups
  6. Add a Face Attribute
  7. Delete a Face Attribute
  8. Get the List of Newly Added Face Attributes of a Specified Face Group
  9. Add a Face
  10. Delete Faces
  11. Update a Face
  12. Get the Info of a Face
  13. Get the List of Faces
  14. Get the Last N Face Records (Ranking per When They Pay the Last Visits)
  15. Get Face Picture through picture
  16. Clear Specified Face Group

Currently, this interface is only available to SUNMI FS. When the device is bound to the digital store and the device API is activated, the “editing” interface in this section is not available. That is, only the face grouping management interface of the cloud API can be used to manage the face database at this condition.

1. Create a Face Group

Description

This interface can be used to create a face group and configure its attributes. At present, up to 10 groups can exist – 2 default groups (stranger and regular) and 8 groups that can be created by users.

Interface

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

Parameters

ParameterDescriptionExample
deviceIdIPC SNC201D98T00094
name The group name (within 96 characters). There are two default groups (stranger and regular) in the system. stranger
capacity The capacity of each group. The total capacity of all groups should be within 30K. 10000
description The group description, which shall not exceed 150 characters. Black Card Customers
callbackThe calling result

Please note:

1. The first character of a name should not be empty.

2. By default, the new customer group is named stranger, and the regular customer group is named regular.

Response Parameter

Field TypeDescription
code int The return code indicating the operation result;
The return codes of this interface contain 0, 1, 2, 3, 5, 7, 200, 201, 202, 211, 212, 220. Please refer to RPCErrorCode Class for details.

2. Edit a Face Group

Description

This interface is used to edit the attributes of a specified face group.

Interface

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

Parameters

ParameterDescriptionExample
deviceIdIPC SNC201D98T00094
oldGroupName The original name of the group. Black Card Customers
groupName The modified name of the group (it can be the same as the original name). Golden Card Customers
capacity The modified group capacity (it can be the same as the original capacity). 10000
description The group description, which shall not exceed 150 characters. Card Application and Upgrade
callbackThe calling result.

Please note:

1. The name of default face groups (stranger and regular) cannot be modified.

2. The first character of a name should not be empty.

Response Parameter

Field TypeDescription
code int The return code indicating the operation result;
The return codes of this interface contain 0, 1, 2, 3, 5, 7, 200, 201, 202, 204, 211, 212, 220. Please refer to RPCErrorCode Class for details.

3. Set the Transfer Condition (From Stranger to Regular) 

Description

When the system is activated, two face groups (stranger and regular) will be created. A stranger will be transferred to the regular group if a certain condition is met (by default, visiting a store 5 times within 7 days).

This interface is used to change the condition for the transfer.

Interface

public void updateMigration(String deviceId, int arrive_times, int period, RpcCallback‹RpcResponse› callback);

Parameters

ParameterDescriptionExample
deviceIdIPC SNC201D98T00094
arrive_times An attribute unique to the stranger group. It ranges 1~10. 5
period An attribute unique to the stranger group. It ranges 1~100 (unit: day). 20
callbackThe calling result.

Please note:

The arrive_times and period are attributes unique to the stranger group, which can be altered to change the transfer condition. A stranger will be transferred to the regular group if he/she visits certain times (arrive_times) within certain days (period).

Response Parameter

FieldType Description
code int The return code indicating the operation result;
The return codes of this interface contain 0, 1, 2, 3, 5, 7, 204, 211, 220. Please refer to RPCErrorCode Class for details.

4. Delete a Face Group

Description

This interface is used to delete a specified face group.

Interface

public void deleteGroup(String deviceId, String groupName, RpcCallback‹RpcResponse› callback);

Parameters

ParameterDescriptionExample
deviceIdIPC SNC201D98T00094
groupName The default groups (stranger and regular) cannot be deleted. And please clear a group first before deleting it. Black Card Customers
callbackThe calling result.

Response Parameter

Field Type Description
code int The return code indicating the operation result;
The return codes of this interface contain 0, 1, 2, 3, 5, 7, 201, 204, 205, 211, 220. Please refer to RPCErrorCode Class for details.

5. Get the List of Face Groups

Description

This interface is used to get the information of IPC face groups.

Interface

public void getGroupList(String deviceId, RpcCallback‹RpcResponse‹GroupCollection›› callback);

Parameters

ParameterDescriptionExample
deviceIdIPC SNC201D98T00094
callbackThe calling result.

Response Parameters

FieldType Description
code int The return code indicating the operation result;
The return codes of this interface contain 0, 1, 2, 3, 5, 7, 211, 220. Please refer to RPCErrorCode Class for details.
dataGroupCollectionThis field shows only when the return code indicates a successful operation. Please refer to RPCResponse. GroupCollection for details.

6. Add a Face Attribute

Description

Some face attributes are preset in the library. You can use this interface to add up to 5 attributes to the faces in a specified face group.

This interface is recommended to be used as needed after a group has been created but before any face has been added instead of adding face attributes after some faces have been added to a group.

Interface

public void addFaceInfoItem(String deviceId, String groupName, List‹String› attrs, RpcCallback‹RpcResponse› callback);

Parameters

ParameterDescriptionExample
deviceIdIPC SNC201D98T00094
groupName The face group name. vip
attrs It is an attribute list showing in an array. The attribute type is string and with a maximum length of 50 bytes. [“hobby”]
callbackThe calling result.

Please note:

1. No face attributes can be added to the default face groups.

2. The following fields are reserved and cannot be used as newly added attribute names: group_name, pic, age, gender, faceid, age_range, arrive_times, pic_url, total_num, return_num.

Response Parameter

FieldTypeDescription
code int The return code indicating the operation result;
The return codes of this interface contain 0, 1, 2, 3, 5, 7, 204, 211, 220, 240, 241, 242. Please refer to RPCErrorCode Class for details.

7. Delete a Face Attribute

Description

This interface is used to delete some user-defined attributes in a specified group when they go needless. However, please delete with caution.

Interface

public void removeFaceInfoItem(String deviceId, String groupName, List‹String› attrs, RpcCallback‹RpcResponse› callback);

Parameters.

ParameterDescriptionExample
deviceIdIPC SNC201D98T00094
groupName The face group name vip
attrs It is an attribute list showing in an array. The attribute type is string and with a maximum length of 50 bytes [“hobby”]
callbackThe calling result.

Please note:

No face attributes can be deleted from the default face groups.

Response Parameter

Field Type Description
code int The return code indicating the operation result;
The return codes of this interface contain 0, 1, 2, 3, 5, 7, 204, 211, 220, 240, 241, 243. Please refer to RPCErrorCode Class for details.

8. Get the List of Newly Added Face Attributes of a Specified Face Group

Description

This interface is used to get the list of face attributes added through the method stated in 2.4.6.。

Interface

public void getFaceInfoItem(String deviceId, String groupName, RpcCallback‹RpcResponse‹FaceAttributeCollection›› callback);

Parameters

ParameterDescriptionExample
deviceIdIPC SNC201D98T00094
groupNameThe face group name. stranger
callbackThe calling result

Response Parameters

FieldType Description
code int The return code indicating the operation result;
The return codes of this interface contain 0, 1, 2, 3, 5, 7, 204, 211, 220. Please refer to RPCErrorCode Class for details.
dataFaceAttributeCollection This field shows only when the return code indicates a successful operation. Please refer to RpcResponse.FaceAttributeCollection for details.

9. Add a Face

Description

This interface is used to add a face (and configure its attributes) to a specified group. One face can be added at a time.

Interface

public void addFaceRecord(String deviceId, Map‹String, String› options, RpcCallback‹RpcResponse› callback);

Parameters

ParameterDescriptionExample
deviceIdIPC SN.C201D98T00094
optionsThe attributes related to a face record. See Options Description below for details.
callback The calling result.

Options Description

Parameter Type Description RequiredExample
faceidstringFace ID, which should be within 16 English characters. N11024
pic file The face picture in jpg/png format. Its maximum resolution is 1920*1080, and the size should be within 1MB. Y 11024.jpg
group_name string The face group name Y stranger
age int Preset attribute – age. N 14
gender int Preset attribute – gender. 0: Unknow. 1: Male. 2: Female. N 1
item1 string User-defined attribute 1. N value1
item2 string User-defined attribute 2. N value2
item3 string User-defined attribute 3. N value3
item4 string User-defined attribute 4. N value4
item5 string User-defined attribute 5. N value5

Please note:

1. Attributes (item1/item2/item3/item4/item5) other than the preset face attributes stated above (which are built in the IPC database) are user-defined attributes, which should be added through calling the interface in 2.4.6. If a face attribute has not been added beforehand but a corresponding key-value has been added to the interface, the IPC won’t process the attribute.

2. If the age attribute has not been set, the IPC will automatically set the age range of a customer.

3. If the gender attribute has not been set, the IPC will automatically set the gender of a customer.

Response Parameter

Field Type Description Example
code int The return code indicating the operation result;
The return codes of this interface contain 0, 1, 2, 3, 5, 7, 204, 206, 208, 210, 211, 220. Please refer to RPCErrorCode Class for details.

10. Delete Faces

Description

This interface is used to delete some faces in a specified face group.

Interface

public void deleteFaceRecord(String deviceId, String groupName, List‹String› faceidList, RpcCallback‹RpcResponse‹DeleteFaceDetails›› callback);

Parameters

ParameterDescriptionExample
deviceIdIPC SNC201D98T00094
groupName The face group name. vip
faceidList The list of Face IDs. [“1988″,”2020”]
callbackThe calling result

Response Parameters

Field Type Description
code int The return code indicating the operation result;
The return codes of this interface contain 0, 1, 2, 3, 5, 7, 204, 211, 220. Please refer to RPCErrorCode Class for details.
dataDeleteFaceDetailsThis field shows only when the return code indicates a successful operation. Please refer to RpcResponse.DeleteFaceDetails for details.

11. Update a Face

Description

This interface is used to update the information of a specified face.

Interface

public void updateFaceRecord(String deviceId, Map‹String, String› options, RpcCallback‹RpcResponse› callback);

Parameters

ParameterDescriptionExample
deviceIdIPC SNC201D98T00094
optionsThe attributes related to a face record. See Options Description below for details.
callbackThe calling result

Options Description

Parameter Type Description RequiredExample
group_name string The face group name. Y stranger
faceid string Face ID. Y 21
new_group_name string New group name. N VIP
pic file The face picture in jpg/png format. Its maximum resolution is 1920*1080, and its size should be within 1MB. N example.jpg
age int Preset attribute – age. N 10
gender int Gender, which can be updated to use 1 to represent male and 2 to represent female. N 1
item1 string User-defined attribute 1 N value1
item2 string User-defined attribute 2N value2
item3 string User-defined attribute 3N value3
item4 string User-defined attribute 4N value4
item5 string User-defined attribute 5N value5

Response Parameter

Parameter Type Description
code int The return code indicating the operation result;
The return codes of this interface contain 0, 1, 2, 3, 5, 7, 204, 207, 208, 210, 211, 220. Please refer to RPCErrorCode Class for details.

Please note:

The hobby, vip_level, weight, phone_num (item1/item2/item3/item4) above are user-defined attributes, which can be added using the interface in 2.4.6. They are ready to be used after having been added.

12. Get the Info of a Face

Description

This interface is used to get the information of a face through a specified Face ID.

Interface

public void getFaceRecord(String deviceId, String faceId, RpcCallback‹RpcResponse‹FaceRecord›› callback);

Parameters

ParameterDescriptionExample
deviceIdIPC SNC201D98T00094
faceIdFace Id105
callbackThe calling result

Response Parameters

ParameterType Description
code int The return code indicating the operation result;
The return codes of this interface contain 0, 1, 2, 3, 5, 7,  211. Please refer to RPCErrorCode Class for details.
dataFaceRecord This field shows only when the return code indicates a successful operation. Please refer to RpcResponse.FaceRecord for details.
{    
  "code": 0,    
  "data": {        
    "arrive_time": 1566215943,        
    "arrive_count": 2,        
    "faceid": "4",        
    "group_name": "VIP",        
    "point": "113",         //User-defined attribute       
    "gender": 1,        
    "age": 10,        
    "age_range": 2,        
    "vip_level": "1",       //User-defined attribute       
    "hobby": "tennis",      //User-defined attribute       
    "weight": "60",         //User-defined attribute       
    "height": "180"        //User-defined attribute 
  }
}

Please note:

The hobby, vip_level, weight, phone_num (item1/item2/item3/item4) above are user-defined attributes, which can be added using the interface in 2.4.6. These attributes can only be returned after they have been added.

13. Get the List of Faces

Description

This interface is used to get all face information of a specified face group.

Interface

public void getFaceRecordList(String deviceId, String groupName, int pageNum, int pageSize, RpcCallback‹RpcResponse‹FaceRecordCollection›› callback);

Parameters

ParameterDescriptionExample
deviceIdIPC SNC201D98T00094
page_num The current page number, whose default and minimum value is 1.
page_sizeThe number of items on the current page, which is 10 by default and ranges [1, 100].
callbackThe calling result

Sample Result Returned

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

14. Get the Last N Face Records (Ranking per When They Pay the Last Visits)

Description

This interface is used to get the information of the N faces who have not visited the store for a long time in a specified group.

Interface

public void getFaceByArrival(String deviceId, String groupName, int num, RpcCallback‹RpcResponse‹FaceRecordCollection›› callback);

Parameters

ParameterDescriptionExample
deviceIdIPC SNC201D98T00094
groupNameThe face group name. VIP
numThe number of faces to be obtained. Its default value is 1 and it ranges 1~10. 2
callbackThe calling result.

Response Parameters

ParameterType Description
code int The return code indicating the operation result;
The return codes of this interface contain 0, 1, 2, 3, 5, 7,  207, 211. Please refer to RPCErrorCode Class for details.
dataFaceRecordCollectionThis field shows only when the return code indicates a successful operation. Please refer to RpcResponse.FaceRecordCollection for details.

Sample Result Returned

{
    “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, // User-defined attribute
                “item2”:value2, // User-defined attribute  
                “item3”:value3, // User-defined attribute
                “item4”:value4, // User-defined attribute
                “item5”:value5 // User-defined attribute             
            },
            {
                “faceid”: “10”,
                “arrive_time”: 1566110525,
                “arrive_count”: 6,
                “age_range”: 4,
                “gender”: 2,
                “age”: 0,
                “item1”: value1, // User-defined attribute  
                “item2”:value2, // User-defined attribute
                “item3”:value3, // User-defined attribute
                “item4”:value4, // User-defined attribute
                “item5”:value5 // User-defined attribute                 
            }
        ]
    }
}

15. Get Face Picture through picture

Description

This interface uses face picture to search for similar faces in IPC devices, and returns face records that are identified as the same person by eigenvalue matching.

Interface

public void getFaceRecordByPicture(String deviceId, String picPath, RpcCallback‹RpcResponse‹FaceRecord›› callback);

Parameters

ParameterDescriptionExample
deviceIdIPC SNC201D98T00094
picPathThe picture path/mnt/sdcard/1424.jpg
callbackThe calling result

Response Parameters

ParameterTypeDescription
code int The return code indicating the operation result;
The return codes of this interface contain 0, 1, 2, 3, 5, 7,  210, 211, 283. Please refer to RPCErrorCode Class for details.
dataFaceRecord This field shows only when the return code indicates a successful operation. Please refer to RpcResponse.FaceRecord for details.

16. Clear Specified Face Group

Description

Clear all face data from specified face group.

Interface

public void cleanGroup(String deviceId, String groupName, RpcCallback‹RpcResponse› callback);

Parameters

ParameterDescriptionExample
deviceIdIPC SNC201D98T00094
groupNameThe picture path“vip”
callbackThe calling result

Response Parameters

ParameterTypeDescription
code int The return code indicating the operation result;
The return codes of this interface contain 0, 2, 3, 12, 13, 204, 220. Please refer to RPCErrorCode Class for details.