Create a Face Group
Edit a Face Group
Set the Transfer Condition (From Stranger to Regular)
Delete a Face Group
Get the List of Face Groups
Add a Face Attribute
Delete a Face Attribute
Get the List of Newly Added Face Attributes of a Specified Face Group
Add a Face
Delete Faces
Update a Face
Get the Info of a Face
Get the List of Faces
Get the Last N Face Records (Ranking per When They Pay the Last Visits)
Get Face Picture through picture
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

Parameter	Description	Example
deviceId	IPC SN	C201D98T00094
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
callback	The 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	Type	Description
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

Parameter	Description	Example
deviceId	IPC SN	C201D98T00094
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
callback	The 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	Type	Description
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

Parameter	Description	Example
deviceId	IPC SN	C201D98T00094
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
callback	The 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

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.

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

Parameter	Description	Example
deviceId	IPC SN	C201D98T00094
groupName	The default groups (stranger and regular) cannot be deleted. And please clear a group first before deleting it.	Black Card Customers
callback	The 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

Parameter	Description	Example
deviceId	IPC SN	C201D98T00094
callback	The 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, 211, 220. Please refer to RPCErrorCode Class for details.
data	GroupCollection	This 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

Parameter	Description	Example
deviceId	IPC SN	C201D98T00094
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”]
callback	The 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

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, 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.

Parameter	Description	Example
deviceId	IPC SN	C201D98T00094
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”]
callback	The 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

Parameter	Description	Example
deviceId	IPC SN	C201D98T00094
groupName	The face group name.	stranger
callback	The 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.
data	FaceAttributeCollection	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

Parameter	Description	Example
deviceId	IPC SN.	C201D98T00094
options	The attributes related to a face record. See Options Description below for details.
callback	The calling result.

Options Description

Parameter	Type	Description	Required	Example
faceid	string	Face ID, which should be within 16 English characters.	N	11024
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

Parameter	Description	Example
deviceId	IPC SN	C201D98T00094
groupName	The face group name.	vip
faceidList	The list of Face IDs.	[“1988″,”2020”]
callback	The 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.
data	DeleteFaceDetails	This 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

Parameter	Description	Example
deviceId	IPC SN	C201D98T00094
options	The attributes related to a face record. See Options Description below for details.
callback	The calling result

Options Description

Parameter	Type	Description	Required	Example
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 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

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

Parameter	Description	Example
deviceId	IPC SN	C201D98T00094
faceId	Face Id	105
callback	The calling result

Response Parameters

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, 211. Please refer to RPCErrorCode Class for details.
data	FaceRecord	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

Parameter	Description	Example
deviceId	IPC SN	C201D98T00094
page_num	The current page number, whose default and minimum value is 1.
page_size	The number of items on the current page, which is 10 by default and ranges [1, 100].
callback	The 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

Parameter	Description	Example
deviceId	IPC SN	C201D98T00094
groupName	The face group name.	VIP
num	The number of faces to be obtained. Its default value is 1 and it ranges 1~10.	2
callback	The calling result.

Response Parameters

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, 207, 211. Please refer to RPCErrorCode Class for details.
data	FaceRecordCollection	This 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

Parameter	Description	Example
deviceId	IPC SN	C201D98T00094
picPath	The picture path	/mnt/sdcard/1424.jpg
callback	The calling result

Response Parameters

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, 210, 211, 283. Please refer to RPCErrorCode Class for details.
data	FaceRecord	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

Parameter	Description	Example
deviceId	IPC SN	C201D98T00094
groupName	The picture path	“vip”
callback	The calling result

Response Parameters

Parameter	Type	Description
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.

Sunmi Developer Docs

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