Face Recognition – Sunmi Developer Docs

Create Face Group
Edit Face Group
Configure The Stranger-to-regular Conditions
Delete Face Group
Get The List of Face Group
Add Attributes to A Face Group
Delete Attributes of A Face Group
Get List of User-defined Attributes of A Face Group
Add Face Record
Delete Face Record
Update Face Record
Get Face Record
Get List of Face Records
Get Face Records That Don’t Arrival For The Longgest Time

1. Create Face Group

Description

Create a new face group via this interface and configure its attributes. The IPC supports up to 10 face groups including the default stranger group and regular group and maximum 8 user groups.

Request link

https://192.168.0.1/ openapi/face/createGroup, 192.168.0.1 needs to be replaced with the actual IP address of IPC.

Request Parameters

Below are private parameters for this API, please refer to Public Parameters for more details.

Parameter	Type	Description	Required	Example
name	string	The name of group, maximum 96 characters. The system has two default group, stranger and regular.	Y	vip
capacity	int	Capacity of group, the sum of all group capacities shall not exceed 30000.	Y	10000
Description	string	Description of group, maximum 150 characters.	Y	Customers with gold card.

Note:

1. The first character of name shall not be a blank space;

2. By default, the name of stranger group is stranger, the name of regular group is regular.

Response Parameters

Parameter	Type	Description
code	int	Return code, represent the request result, possible return codes are 0, 1, 2, 3, 5, 7, 200, 201, 202, 211, 212, 220, see Error Code for further details.

Request Example

POST openapi/face/createGroup HTTP/1.1
Host: 192.168.0.1
Content-Type: application/x-www-form-urlencoded

app_id=mdk923idkf&random=289192&timestamp=15930292837&sign=IDKNFLK392038KDS932K& name=vip&capacity=10000&description=Customers with gold card.

Response Example

{
    "code": 0
}

2. Edit Face Group

Description

This API is used to edit attributes of a face group.

Request link

https://192.168.0.1/openapi/face/updateGroup, 192.168.0.1 needs to be replaced with the actual IP address of IPC.

Request Parameters

Below are private parameters for this API, please refer to Public Parameters for more details.

Parameter	Type	Description	Required	Example
old_name	string	The name of Face Group you want to modify.	Y	vip
name	string	The new name of Face Group, can be same with old_name.	Y	svip
capacity	int	The new capacity of Face Group, can be same with the old capacity.	Y	10000
Description	string	Description of group, maximum 150 characters.	Y	Customers with platinum card.

Note:

1.name must be same with old_name when you edit stranger group or regular group, in other words, the name of default groups art not allowed to be modified;

2.The first character of name shall not be a blank space.

Response Parameters

Parameter	Type	Description
code	int	Return code, represent the request result, possible return codes are 0, 1, 2, 3, 5, 7, 200, 201, 202, 204, 211, 212, 220, see Error Code for further details.

Request Example

POST openapi/face/updateGroup HTTP/1.1
Host: 192.168.0.1
Content-Type: application/x-www-form-urlencoded

app_id=mdk923idkf&random=289192&timestamp=15930292837&sign=IDKNFLK392038KDS932K& old_name=vip&name=svip&capacity=10000&description=Customers with platinum card.

Response Example

{
    "code": 0
}

3. Configure The Stranger-to-regular Conditions

Description

Stranger and regular face groups will be created once the IPC is activated. The records in stranger face group will be moved to the regular face group when they meet the moving conditions which is 5 times in 7 days by default. This API is used to Configure The Stranger-to-regular Conditions.

Request Link

https://192.168.0.1/openapi/face/updateMigration, 192.168.0.1 needs to be replaced with the actual IP address of IPC.

Request Parameters

Below are private parameters for this API, please refer to Public Parameters for more details.

Parameter	Type	Description	Required	Example
arrive_times	int	value range 1~10.	Y	5
period	int	value range 1~100, unit: day.	Y	20

Note:

It means that record will be move from stranger to regular while the face was captured more than [arrive_times] times in [period] days. So this api is only applicable to the stranger face group.

Response Parameters

Parameter	Type	Description
code	int	Return code, represent the request result, possible return codes are 0, 1, 2, 3, 5, 7, 204, 211, 220, see Error Code for further details.

Request Example

POST openapi/face/updateMigrationHTTP/1.1
Host: 192.168.0.1
Content-Type: application/x-www-form-urlencoded

app_id=mdk923idkf&random=289192&timestamp=15930292837&sign=IDKNFLK392038KDS932K&arrive_times=5&period=3

Response Example

{
    "code": 0
}

4. Delete Face Group

Description

Delete the specified face group.

Request Link

https://192.168.0.1/openapi/face/deleteGroup, 192.168.0.1 needs to be replaced with the actual IP address of IPC.

Request Parameters

Below are private parameters for this API, please refer to Public Parameters for more details.

Parameter	Type	Description	Required	Example
name	string	The name of group to be deleted, stranger and regular group art not allowed to be deleted. The group should be empty before it is deleted.	Y	vip

Response Parameters

Parameter	Type	Description
code	int	Return code, represent the request result, possible return codes are 0, 1, 2, 3, 5, 7, 201, 204, 205, 211, 220, see Error Code for further details.

Request Example

POST openapi/face/deleteGroup HTTP/1.1
Host: 192.168.0.1
Content-Type: application/x-www-form-urlencoded

app_id=mdk923idkf&random=289192&timestamp=15930292837&sign=IDKNFLK392038KDS932K& name=vip

Response Example

{
    "code": 0
}

5. Get The List of Face Group

Description

This API is used to get infomations of all groups.

Request Link

https://192.168.0.1/openapi/face/getGroupList, 192.168.0.1 needs to be replaced with the actual IP address of IPC.

Request Parameters

No private parameter for this API, please refer to Public Parameters for more details.

Response Parameters

Parameter	Type	Description
code	int	Return code, represent the request result, possible return codes are 0, 1, 2, 3, 5, 7, 211, 220, see Error Code for further details.
num	int	number of groups
name	string	name of group
capacity	int	capacity of group.
Description	string	description of group.
times	int	attribute only for stranger.
period	int	attribute only for stranger.
count	int	number of records in the group.

Request Example

POST openapi/face/getGroupList HTTP/1.1
Host: 192.168.0.1
Content-Type: application/x-www-form-urlencoded

app_id=mdk923idkf&random=289192&timestamp=15930292837&sign=IDKNFLK392038KDS932K

Response Example

{
    "data": {
        "face_group": [
            {
                "capacity": 5000,
                "count": 0,
                "name": "regular",
                "description": "this is regular group"
            },
            {
                "capacity": 1000,
                "count": 0,
                "name": "employee",
                "description": "this is employee group"
            },
            {
                "capacity": 1000,
                "count": 0,
                "name": "blacklist",
                "description": "this is blacklist group"
            },
            {
                "name": "stranger",
                "times": 5,
                "capacity": 1000,
                "count": 0,
                "period": 2,
                "description": "this is stranger group"
            }
        ],
        "num": 4
    },
    "code": 0
}

6. Add Attributes to A Face Group

Description

Each face group has 5 user-defined fields or attributes that can be filled with string with up to 50 characters for every records, except the default groups.

It is strongly recommended to add user-defined attributes after creating the face group and before adding any record with this interface.

Request Link

https://192.168.0.1/openapi/face/addFaceInfoItem, 192.168.0.1 needs to be replaced with the actual IP address of IPC.

Request Parameters

Below are private parameters for this API, please refer to Public Parameters for more details.

Parameter	Type	Description	Required	Example
num	int	Number of attributes to add.	Y	1
group_name	string	Name of group.	Y	vip
name_list	string array	Attribute name list, maximum 50 characters in length for each name.	Y	[“hobby”]

Note:

1. The default groups (stranger and regular) are not allowed to add attributes;

2. The following names are reserved and can not be used as attribute names: group_name, pic, age, gender, faceid, age_range, arrive_times, pic_url, total_num, return_num。

Response Parameters

Parameter	Type	Description
code	int	Return code, represent the request result, possible return codes are 0, 1, 2, 3, 5, 7, 204, 211, 220, 240, 241, 242, see Error Code for further details.

Request Example

POST openapi/face/addFaceInfoItem HTTP/1.1
Host: 192.168.0.1
Content-Type: application/x-www-form-urlencoded

app_id=mdk923idkf&random=289192&timestamp=15930292837&sign=IDKNFLK392038KDS932K& num=2&group_name=vip&name_list=[“phone_num”, “weight”]

Response Example

{
    "code": 0
}

7. Delete Attributes of A Face Group

Description

This interface is used to delete user-defined attributes in a specified face group.

Request Link

https://192.168.0.1/openapi/face/removeFaceInfoItem, 192.168.0.1 needs to be replaced with the actual IP address of IPC.

Request Parameters

Below are private parameters for this API, please refer to Public Parameters for more details.

Parameter	Type	Description	Required	Example
num	int	Number of attributes to delete.	Y	1
group_name	string	Name of group	Y	vip
name_list	string	Attribute name list, maximum 50 characters in length for each name.	Y	[“hobby”]

Response Parameters

Parameter	Type	Description
code	int	Return code, represent the request result, possible return codes are 0, 1, 2, 3, 5, 7, 204, 211, 220, 240, 241, 242, 243, see Error Code for further details.

Request Example

POST openapi/face/removeFaceInfoItem HTTP/1.1
Host: 192.168.0.1
Content-Type: application/x-www-form-urlencoded

app_id=mdk923idkf&random=289192&timestamp=15930292837&sign=IDKNFLK392038KDS932K& num=2&group_name=vip&name_list=[“phone_num”, “weight”]

Response Example

{
    "code": 0
}

8. Get List of User-defined Attributes of A Face Group

Description

This interface is used to get the list of user-defined attribute of a specified group.

Request Link

https://192.168.0.1/openapi/face/getFaceInfoItem, 192.168.0.1 needs to be replaced with the actual IP address of IPC.

Request Parameters

Below are private parameters for this API, please refer to Public Parameters for more details.

Parameter	Type	Description	Required	Example
group_name	string	name of group	Y	stranger

Response Parameters

Parameter	Type	Description
code	int	Return code, represent the request result, possible return codes are 0, 1, 2, 3, 5, 7, 204, 211, 220, see Error Code for further details.
num	int	Number of attributes.
name_list	string	Attribute name list.

Request Example

POST openapi/face/getFaceInfoItemHTTP/1.1
Host: 192.168.0.1
Content-Type: application/x-www-form-urlencoded

app_id=mdk923idkf&random=289192&timestamp=15930292837&sign=IDKNFLK392038KDS932K& num=2&group_name=vip

Response Example

{
    "code": 0,
    "data": {
        "num": 3,
        "name_list": [
            "phone",
            "address",
            "vip_level"
        ]
    }
}

9. Add Face Record

Description

This API is used to add a face record in the specified group.

Request Type

Content-Type is multipart/form-data, and all arguments except file are signed according to the signature rules.

Request Link

https://192.168.0.1/openapi/face/addFace, 192.168.0.1 needs to be replaced with the actual IP address of IPC.

Request Parameters

Below are private parameters for this API, please refer to Public Parameters for more details.

Parameter	Type	Description	Required	Example
faceid	string	Faceid, a positive 64-bit numeric string, the device will generate if not supply	N	123456
pic	file	Face photo file in jpg/png format, maximum resulution is 1920*1080, the size of file must not exceed 1M bytes.	N	example.jpg
group_name	string	name of group	Y	stranger
age	int	preset attribute, age	N	14
gender	int	preset attribute , gender, 0 for unknown, 1 for male, 2 for 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

Note:

1.The preset attributes above are built-in attribute of face record in the databse, and others include item1/item2/item3/item4/item5 are user-defined attributes. Users must call the interface to add user-defined attributes before using; The IPC will ignore the parameters if the corresponding attributes are not found.

2.If the attribute age is not provided, the age range will be set automatically by the IPC;

3. If the attribute gender is not provided, this field will be set automatically by the IPC.

Response Parameters

Parameter	Type	Description	Example
code	int	Return code, represent the request result, possible return codes are 0, 1, 2, 3, 5, 7, 204, 206, 208, 210, 211, 220, see Error Code for further details.
faceid	string	Face ID.	105

Request Example

POST /openapi/face/addFace HTTP/1.1
Host: 192.168.0.1
Content-Type: multipart/form-data; boundary=————————–962974737227706390007700
Content-Length: 1683

—————————-962974737227706390007700
Content-Disposition: form-data; name=”app_id”

mdk923idk
—————————-962974737227706390007700
Content-Disposition: form-data; name=”random”

289192
—————————-962974737227706390007700
Content-Disposition: form-data; name=”timestamp”

15930292837
—————————-962974737227706390007700
Content-Disposition: form-data; name=”sign”

IDKNFLK392038KDS932K
—————————-962974737227706390007700
Content-Disposition: form-data; name=”group_name”

VIP
—————————-962974737227706390007700
Content-Disposition: form-data; name=”age”

21
—————————-962974737227706390007700
Content-Disposition: form-data; name=”gender”

1
—————————-962974737227706390007700
Content-Disposition: form-data; name=”hobby”

hiking
—————————-962974737227706390007700
Content-Disposition: form-data; name=”vip_level”

2
—————————-962974737227706390007700
Content-Disposition: form-data; name=”weight”

60
—————————-962974737227706390007700
Content-Disposition: form-data; name=”phone_num”

1234
—————————-962974737227706390007700
Content-Disposition: form-data; name=”pic”; filename=”11024.jpg”
Content-Type: image/jpeg

(binary data of picture)
—————————-962974737227706390007700–

Note:

The above hobby, vip_level, weight and phone_num are user-defined attributes, should be added before using them.

Response Example

{
    "code": 0,
    "data": {
        "faceid": "105"
    }
}

10. Delete Face Record

Description

This API is used to delete the face records from the specified group.

Request Link

https://192.168.0.1/openapi/face/deleteFace, 192.168.0.1 needs to be replaced with the actual IP address of IPC.

Request Parameters

Below are private parameters for this API, please refer to Public Parameters for more details.

Parameter	Type	Description	Required	Example
num	int	Number of face records to delete	Y	1
group_name	string	Name of group	Y	Example
faceid_list	string array	List of face record to delete.	Y	[“105”]

Response Parameters

Paramter	Type	Description
code	int	Return code, represent the request result, possible return codes are 0, 1, 2, 3, 5, 7, 204, 211, 220, see Error Code for further details.
success_list	string array	List of face records that have been deleted
failed_list	string array	List of failed deleting face records
not_exist_list	string array	List of face records that are not exist.

Request Example

POST openapi/face/deleteFace HTTP/1.1
Host: 192.168.0.1
Content-Type: application/x-www-form-urlencoded

app_id=mdk923idkf&random=289192&timestamp=15930292837&sign=IDKNFLK392038KDS932K& group_name=vip&faceid_list=[“000001”, “0000002”]&num=2

Response Example

{
    "code": 0,
    "data": {
        "success_list": [
            "000001",
            "000002"
        ],
        "failed_list": [],
        "not_exist_list": [
            "000003"
        ]
    }
}

11. Update Face Record

Description

Update the information of the specified face record.

Request Link

https://192.168.0.1/openapi/face/updateFace, 192.168.0.1 needs to be replaced with the actual IP address of IPC.

Request Method

Content-Type is multipart/form-data, and all arguments except file are signed according to the signature rules.

Request Parameters

Below are private parameters for this API, please refer to Public Parameters for more details.

Parameter	Type	Description	Required	Example
group_name	string	Name of group	Y	svip
faceid	string	Face ID	Y	21
new_group_name	string	New group name, the record will be moved to this group if provided.	N	vip
pic	file	Face photo file in jpg/png format, maximum resulution is 1920*1080, the size of file must not exceed 1M bytes.	N	example.jpg
age	int	preset attribute, age	N	10
gender	int	preset attribute , gender, 0 for unknown, 1 for male, 2 for 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 Parameters

Parameter	Type	Description
code	int	Return code, represent the request result, possible return codes are 0, 1, 2, 3, 5, 7, 204, 207, 208, 210, 211, 220, see Error Code for further details.

Request Example

POST /openapi/face/addFace HTTP/1.1
Host: 192.168.0.1
Content-Type: multipart/form-data; boundary=————————–962974737227706390007700
Content-Length: 1683

—————————-962974737227706390007700
Content-Disposition: form-data; name=”app_id”

mdk923idk
—————————-962974737227706390007700
Content-Disposition: form-data; name=”random”

289192
—————————-962974737227706390007700
Content-Disposition: form-data; name=”timestamp”

15930292837
—————————-962974737227706390007700
Content-Disposition: form-data; name=”sign”

IDKNFLK392038KDS932K
—————————-962974737227706390007700
Content-Disposition: form-data; name=”group_name”

stranger
—————————-962974737227706390007700
Content-Disposition: form-data; name=”facdid”

21
—————————-962974737227706390007700
Content-Disposition: form-data; name=”new_group_name”

VIP
—————————-962974737227706390007700
Content-Disposition: form-data; name=”hobby”

hiking
—————————-962974737227706390007700
Content-Disposition: form-data; name=”vip_level”

2
—————————-962974737227706390007700
Content-Disposition: form-data; name=”weight”

60
—————————-962974737227706390007700
Content-Disposition: form-data; name=”phone_num”

1234
—————————-962974737227706390007700–

Note:

The above hobby, vip_level, weight and phone_num are user-defined attributes, should be added before using them.

Response Example

{
    "code": 0
}

12. Get Face Record

Description

Get information of the face record by face ID.

Request Link

https://192.168.0.1/openapi/face/getFace, 192.168.0.1 needs to be replaced with the actual IP address of IPC.

Request Parameters

Below are private parameters for this API, please refer to Public Parameters for more details.

Parameter	Type	Description	Required	Example
faceid	string	ace ID	Y	4

Response Parameters

Parameter	Type	Description
code	int	Return code, represent the request result, possible return codes are 0, 1, 2, 3, 5, 7, 211, see Error Code for further details.
faceid	string	Face ID
group_name	string	Group name
age	int	age, NULL means user has not set the age of the face record.
age_range	int	age range, 1 means 1~6 years old, 2 means 7~12 years old, 3 means 13~18 years old, 5 means 19~28 years old, 5 means 29~35 years old, 6 means 36~45 years old, 7 means 45~55 years old, 8 means 55~100 years old
gender	int	gender, 0 means unknown, 1 means male, 2 means female
arrive_count	int	Total number of arrivals
arrive_time	int	Timestamp of the last arrival
item1	string	User-defined attribute 1, only returned if exist.
item2	string	User-defined attribute 2, only returned if exist.
item3	string	User-defined attribute 3, only returned if exist.
item4	string	User-defined attribute 4, only returned if exist.
item5	string	User-defined attribute 5, only returned if exist.

Request Example

POST openapi/face/getFace HTTP/1.1
Host: 192.168.0.1
Content-Type: application/x-www-form-urlencoded

app_id=mdk923idkf&random=289192&timestamp=15930292837&sign=IDKNFLK392038KDS932K&
faceid=4

Response Example

{
    "code": 0,
    "data": {
        "arrive_time": 1566215943,
        "arrive_count": 2,
        "faceid": "4",
        "group_name": "vip",
        "point": "113",
        "gender": 1,
        "age": 10,
        "age_range": 2,
        "vip_level": "1",
        "hobby": "tennis",
        "weight": "60",
        "height": "180"
    }
}

Note:

The above hobby, vip_level, weight and phone_num are user-defined attributes, should be added before using them.

13. Get List of Face Records

Description

Get list of the face records in the specified group.

Request Link

https://192.168.0.1/openapi/face/getFaceList, 192.168.0.1 needs to be replaced with the actual IP address of IPC.

Request Parameters

Below are private parameters for this API, please refer to Public Parameters for more details.

Parameter	Type	Description	Required	Example
group_name	string	name of group	Y	vip
page_num	int	Current page number, default and minimum is 1	N	4
page_size	int	Current page entries, default is 10, range is [1, 100]	N	10

Response Parameters

Parameter	Type	Description
code	int	Return code, represent the request result, possible return codes are 0, 1, 2, 3, 5, 7, 211, see Error Code for further details.
total_num	int	Total number of face records
return_num	int	Number of face records currently returned
faceid	string	Face ID
age	int	age, NULL means user has not set the age of the face record.
age_range	int	age range, 1 means 1~6 years old, 2 means 7~12 years old, 3 means 13~18 years old, 5 means 19~28 years old, 5 means 29~35 years old, 6 means 36~45 years old, 7 means 45~55 years old, 8 means 55~100 years old
gender	int	gender, 0 for unknown, 1 for male, 2 for female
arrive_count	int	Total number of arrivals
arrive_time	int	Timestamp of the last arrival
item1	string	User-defined attribute 1, only returned if exist.
item2	string	User-defined attribute 2, only returned if exist.
item3	string	User-defined attribute 3, only returned if exist.
item4	string	User-defined attribute 4, only returned if exist.
item5	string	User-defined attribute 6, only returned if exist.

Request Example

POST openapi/face/getFaceIDList HTTP/1.1
Host: 192.168.0.1
Content-Type: application/x-www-form-urlencoded

app_id=mdk923idkf&random=289192&timestamp=15930292837&sign=IDKNFLK392038KDS932K& group_name=vip

Response Example

{
    "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. Get Face Records That Don’t Arrive For The Longest Time

Description

Get list of last N face records sorted by the “last arrival” time.

Request Link

https://192.168.0.1/openapi/face/getFaceByArrival, 192.168.0.1 needs to be replaced with the actual IP address of IPC.

Request Parameters

Below are private parameters for this API, please refer to Public Parameters for more details.

Parameter	Type	Description	Required	Example
group_name	string	Name of group	Y	vip
num	int	Number of face records, range is 1~10, default is 1.	N	2

Response Parameters

Parameter	Type	Description
code	int	Return code, represent the request result, possible return codes are 0, 1, 2, 3, 5, 7, 207, 211, see Error Code for further details.
return_num	int	Number of face records currently returned
faceid	string	Face ID
age	int	Age, NULL means user has not set the age of the face record.
age_range	int	age range, 1 means 1~6 years old, 2 means 7~12 years old, 3 means 13~18 years old, 5 means 19~28 years old, 5 means 29~35 years old, 6 means 36~45 years old, 7 means 45~55 years old, 8 means 55~100 years old
gender	int	Gender, 0 for unknown, 1 for male, 2 for female
arrive_count	int	Total number of arrivals
arrive_time	int	Timestamp of the last arrival
item1	string	User-defined attribute 1, only returned if exist.
item2	string	User-defined attribute 2, only returned if exist.
item3	string	User-defined attribute 3, only returned if exist.
item4	string	User-defined attribute 4, only returned if exist.
item5	string	User-defined attribute 5, only returned if exist.

Request Example

POST openapi/face/getFaceByArrival HTTP/1.1
Host: 192.168.0.1
Content-Type: application/x-www-form-urlencoded

app_id=mdk923idkf&random=289192&timestamp=15930292837&sign=IDKNFLK392038KDS932K& group_name=vip&num=2

Response Example

{
    "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"
            }
        ]
    }
}