Release History API version 1.2.7 Version on server 2.7.0 Version - - PDF document

Release History



API version：1.2.7



Version on server：2.7.0



Version on local host：2.9.1 Section Type Description 2.8 Add Interface for deleting user database 2.9 Add Interface for judging quality of loading images 2.10 Add Interface for finishing photo taking and user registration 11.2 Add Interface for dynamic 1:1 comparison 11.1 Modify Support POST callback for return values of local host information



API version：1.2.6



Version on server：2.0



Version on local host：2.8.0 Section Type Description 4.1 Modify Add paging parameters 11.1 Modify Modify output data 11.2 Delete Not supported in new firmware anymore 11.3 Delete Not supported in new firmware anymore



API version: 1.2.5



Version on server: 1.5



Version on local host: 2.6

Section Type Description 9.1 Delete Deprecate interface and suggest using 11. video streaming recognition 11.1 Modify Delete sample programs, please access API related samples http://techsupport.megvii.com/hc/kb/section/105584/



API version: 1.2.4



Version on server: 1.5



Version on local host: 2.6 Section Type Description 11.2 Add The section is newly added 11.3 Add The section is newly added



API version: 1.2.3



Version on server: 1.5



Version on local host: 2.6 Section Type Description 11.1 Modify Description is updated



API version: 1.2.2



Version on server: 1.5



Version on local host: 2.6 Section Type Description 9.1 Modify and mark as Deprecated Transport of socketio can only use websocket type, polling cannot be used



API version：1.2.1



Version on server：1.5



Version on local host：2.6 Section Type Description 7.2 Modify Add paging parameters 2.7 Modify Add ‘quality’ and other data in return values



API version: 1.2



Version on server: 1.5



Version on local host: 2.6 Section Type Description 10.1, 1:N recognition Modify Add “screen” in return values



API version: 1.1



Version on server: 1.4.2



Version on local host: 2.5 Section Type Description Document Format Modify Document format cleanup

Index

I．Server API Function Method Interface url Interface function

• 0. Error

handling

• 1. Login

POST /auth/login 1.1 Login

I．Server API Function Method Interface url Interface function

• 2. User

Database Management GET /mobile-admin/subjects 2.1 Get all user lists GET /mobile- admin/subjects/list/ 2.2 Get user list (support get by pages or categories) POST /subject 2.3 Create User GET /subject/[id] 2.4 Get User Information PUT /subject/[id] 2.5 Update User Information DELETE /subject/[id] 2.6 Delete User POST /subject/photo 2.7 Upload recognition photo DELETE /subject/photo 2.8 Delete user database POST /subject/photo/check 2.9 Quality check for uploaded photos POST /subject/file 2.10 Create User (support uploading images directly)

• 3. User Avatar

Management POST /subject/avatar 3.1 Uploading and displaying user avatar

• 4. Access

Control Management GET /system/screen 4.1 Get access control list GET /system/screen/[id] 4.2 Get access control information GET /system/boxes 4.3 Get all available local hosts POST /system/screen 4.4 Create access control setting PUT /system/screen/[id] 4.5 Update access control setting DELETE /system/screen/[id] 4.6 Delete access control setting

I．Server API Function Method Interface url Interface function

• 5. Historical

record GET /event/events 5.1 Historical recognition record

• 6. Attendance

record GET /attendance/records 6.1 Attendance record

• 7. Age and

gender analysis （Deprecated） GET /statistics/overview （Deprecated） 7.1 Age and gender statistics GET /statistics/event （Deprecated） 7.2 Age and gender record

• 8. Pad interface

POST /pad/login 8.1 Login POST /pad/add-visitor 8.2 Add visitor PUT /pad/set-info 8.3 Set Pad information

• 9. Recognition

push （Deprecated） socket.io /event/ 9.1 Recognition message push （Deprecated）

• II. Local host API

Function Method Interface url Interface function

• 10. Static

recognition POST /recognize 10.1 1:N recognition POST /checkin 10.2 1:1 authentication

• 11. Video

streaming recognition websocket ws://[本地主机 ip]:9000 11.1 Get recognition result (websocket interface) POST /video_verify 11.2 Dynamic 1:1 interface Appendix

I．Server API Function Method Interface url Interface function

• III. Model definition
• IV. Error code definition
• V. Paging information definitions



Identifier clarification Identifier Clarification code 0 indicates normal, other codes can reference error code definition id Database index subject Recognition objects: staff, visitor avatar Avatar photo of the “subject” photo Recognition photo uploaded for the “subject” box Host box network_switch Network switch screen One channel of Facial Recognition camera



Note: API address is: http://<host ip> Unless otherwise specified, the parameters of all interfaces are in JSON format in this document. Additionally, format Content-Type should be converted into application/json.

• I. Server API
• 0. Error handling

 Not login

HTTP 302 redirect will be returned when calling other interfaces if the login interface was not called, which can be used to check whether login or not.

 No permission

If a logged-in account has no permission to call one interface, HTTP 302 redirect will be returned when calling the interface.

• 1. Login

1.1 Login

 URL:

/auth/login

 Method:

POST

 Description：

Login and acquire a cookie, then all interfaces should pass the cookie in when the interfaces are called.

 Parameters:

Parameters Type Required Description username str √ Email password str √ Password

This interface should set user-agent as “Koala Admin”, otherwise login cannot be successful.  Return value description:

Field Type Specification avatar str Avatar address company_id int Company ID password_reseted bool Save password or not role_id int Account type: 1. Root, 2. Administrator, 3. User username str Username

 Return JSON： { "code": 0, "data": { "avatar": null, "company_id": 1, "id": 2, "password_reseted": true, "role_id": 2, "username": "user@megvii.com" }, "page": {} }

• 2. User Database Management

2.1 Get all user lists

 URL:

/mobile-admin/subjects

 Method:

GET

 Description:

Get list of all users in user database, visitors are included.

 Parameter:

None

 Return value description:

Returned data field is a subject object list, the meaning of subject field can be referred to “Definition

• f subject” part in “III. Model definition”.

 Return JSON: { "code": 0, "data": [ { "avatar": "", "come_from": "", "company_id": 1, "department": "", "description": "", "email": "dyg@megvii.com", "end_time": 0, "gender": 0, "id": 4, "interviewee": "", "name": "dfds", "password_reseted": false, "phone": "", "photo_ids": [ 4 ], "photos": [ { "company_id": 1, "id": 4, "subject_id": 4, "url": "/static/upload/photo/2015-10-13/3ee5d084439065548440749c334957e3fdaa0132.jpg" } ], "purpose": 0, "start_time": 0, "subject_type": 0, "title": "" } ],

}

2.2 Get user list (support get by pages or categories)

 URL:

/mobile-admin/subjects/list

 Method:

GET

 Description：

Get specific user information according to given parameters.

 Parameter：

Parameter Type Default Required Description category string None √ staff; visitor; VIP visitor name string None Chinese name or Pinyin of users waiting for screening

• rder

string 'time' Ordering method: ‘time’ – ordering by reverse chronological order according to creation time; ‘name’ – ordering by English or Pinyin dictionary order page int 1 Page size int 10 Pagesize int

 Return value description:

A subject object array is returned, the meaning of the subject field can be referred to “Definition of subject” part in “III. Model definition”.

 Return JSON：

{ "code": 0, "data": [ { "avatar": "", "come_from": "", "company_id": 1, "department": "", "description": "", "email": "dyg@megvii.com", "end_time": 0, "gender": 0, "id": 4, "interviewee": "", "name": "dfds", "password_reseted": false, "phone": "", "photo_ids": [ 4 ], "photos": [ { "company_id": 1, "id": 4, "subject_id": 4, "url": "/static/upload/photo/2015-10-13/3ee5d084439065548440749c334957e3fdaa0132.jpg" } ], "purpose": 0, "start_time": 0, "subject_type": 0, "title": "" } ], "page": { "count": 757, "current": 1, "size": 10, "total": 76 } } }

2.3 Create User



URL: /subject



Method: POST



Description： Create a new user



Parameter: (if subject_type is not equal to 0, start_time and end_time must be specified) Parameter Type Default Required Description start_time int Access time end_time int End access time purpose int Access purpose birthday int Birthday entry_date int Entry date photo_ids array [] List of recognition photos (by using interface 2.7 Upload recognition photo). This parameter is mandatory for [2.5 Update user information] gender int Male Gender {0: unselected, 1: male, 2: female} email str Null Email phone str Null Mobile phone avatar str Null Avatar image in Base64 department str Null Department title str Null Title description str Null Signature interviewee str Null Interviewee

Parameter Type Default Required Description come_from str Null Visitor company job_number str Null Job number remark str Null Remark subject_type int √ User type {0: staff, 1: visitor, 2: VIP visitor} name str √ Name

 Return value description:

Created subject information

 Return JSON:

The same as in “2.4. Get user information”

2.4 Get User Information

 URL:

/subject/[id]

 Method:

GET

 Description:

Get individual subject information

 Parameter:

None

 Return value description:

Returned data field is a subject object, the meaning of the subject field can be referred to “Definition

• f subject” part in “III. Model definition”.

 Return JSON: { "code": 0, "data": { "avatar": "", "birthday": null, "come_from": "", "company_id": 2, "department": "\u6280\u672f\u90e8", "description": "\u68a6\u60f3\uff0c\u5c31\u662f\u8fd9\u4e48\u4efb\u6027\uff01", "email": "xyz@sina.com", "end_time": null, "entry_date": null, "gender": 1, "id": 19633, "interviewee": "", "job_number": "104", "name": "\u8d75\u516d", "password_reseted": false, "phone": "13788890284", "photos": [], "purpose": 0, "remark": "\u6211\u662f\u540e\u7aef", "start_time": null, "subject_type": 0, "title": "\u5de5\u7a0b\u5e08", "visit_notify": false }, }

2.5 Update User Information

 URL:

/subject/[id]

 Method:

PUT

 Description:

Update part of user fields

 Parameter:

(photo_ids is a mandatory parameter, the form of this parameter is list, empty list can lead all user images be deleted.). Refer to section “2.3 Create user”.

 Return value description:

Modified subject information

 Return JSON:

The same as in “2.4 Get user information”.

2.6 Delete user

 URL:

/subject/[id]

 Method:

DELETE

 Description:

Delete user

 Parameter:

None

 Return value description:

None

 Return JSON:

None

2.7 Upload recognition user database

 URL:

/subject/photo

 Method:

POST

 Description:

Upload individual recognition photo

 Parameter:

Parameter Type Required Description photo file √ Recognition photo subject_id int If this parameter is posted, user recognition photos are updated simultaneously when photo is uploaded successfully. Otherwise, the photo id (return value 563) in the returned values should be manually put in the parameter photo_ids in both interface 2.3 and interface 2.5 for updating the user recognition photo.

Note: the format of interface 2.7 is multipart/form-data.  Return value:

Field Type Specification id int Photo id company_id int Company ID subject_id int Database index, if subject_id is null means photos are not bound to subjects. url str Recognition photo address

Field Type Specification quality float Face quality

 Return JSON: { "code": 0, "data": { "company_id": 2, "id": 563, "subject_id": null, "url": "/static/upload/photo/2015-10-22/78d86cadaad1e1a8f43c87ae3adeafb560e96ee3.jpg" }, "page": {} }

2.8 Delete user database

 URL:

/subject/photo

 Method:

DELETE

 Description:

The interface is used to delete user database.

 Parameter:

Parameter Type Required Description subject_id int √ Recognition photo

Notice: the format of interface 2.8 is multipart/form-data.  Return value:

None

 Return JSON:

None

2.9 Quality check for uploaded photos

 URL:

/subject/photo/check

 Method:

POST

 Description:

The interface is used to do quality check for uploaded photos.

 Parameter:

Parameter Type Required Description photo file √ Recognition photo

Note: the format of interface 2.9 is multipart/form-data.  Return value:

None

 Return JSON:

Error status codes for reference

{ "code": 0, "data": {}, "page": {} }

2.10 Create User (support uploading images directly)



URL:

/subject/file



Method: POST



Description: Create a new user.



Parameter: (if subject_type is not equal to 0, start_time and end_time must be specified) Parameter Type Default Required Description start_time int Visiting time end_time int Leaving time purpose int Visit purpose birthday int Birthday entry_date int Entry date photo file User database photo gender int male Gender {0: unselected, 1: male, 2: female} email str Null Email phone str Null Mobile photo avatar file Avatar photo department str Null Department title str Null Title description str Null Signature interviewee str Null Interviewee come_from str Null Visitor company

Parameter Type Default Required Description job_number str Null Job number remark str Null Remark subject_type int √ User type {0: staff, 1: visitor, 2: VIP visitor} name str √ Name

Note: the format of interface 2.10 is multipart/form-data.  Return value description:

The information of newly created subject.

 Return JSON:

The same as in “2.4 Get user information”.

• 3. User Avatar Management

3.1 Uploading and displaying user avatar

 URL:

/subject/avatar

 Method:

POST

 Description:

Upload user avatar photo.

 Parameter:

Parameter Type Required Description avatar file √ User avatar photo subject_id int √ When the photo is uploaded successfully, the User avatar photo is updated simultaneously for the user specified by this “subject_id”.

Note: the format of interface 3.1 is multipart/form-data.  Return value:

Field Type Specification url str The URL of avatar photo

 Return JSON: { "code": 0, "data": { "url": "/static/upload/photo/2015-10-22/78d86cadaad1e1a8f43c87ae3adeafb560e96ee3.jpg" }, "page": {} }

• 4. Access Control Management

4.1 Get access control list

 URL:

/system/screen

 Method:

GET

 Description:

Get access control list.

 Parameter:

Parameter Type Required Description page int Page n of the list, default value is 1 size int Number of items per page in the list, default value is 500

 Return value:

The filed “data” in the returned value is an access control list, the meaning of the access control filed can be referred to “Definition of screen” part in “III. Model definition”, the returned page field is a paging parameter which be referred to “V. Paging information definition”.

 Return JSON: { "code": 0, "data": [ { "allow_all_subjects": true, "allow_visitor": true, "allowed_subject_ids": [], "box_address": "10.101.3.222", "box_heartbeat": 1498808488, "box_status": "0", "box_token": "1111111", "camera_address": "rtsp://10.101.0.1/live1.sdp", "camera_name": "", "camera_position": "zzz", "camera_status": "-1", "description": null, "id": 3258, "network_switcher": "", "network_switcher_status": null, "network_switcher_token": null, "screen_token": "2222222", "server_time": 1498808000.321123, "type": 1 }, { "allow_all_subjects": true, ......

} ], "page": { "count": 2, "current": 1, "size": 10, "total": 1 } }

4.2 Get single access control setting

 URL:

/system/screen/[id]

 Method:

GET

 Description:

Get single access control setting

 Parameter:

None

 Return value:

Access control information, field meaning can be referred to “Definition of screen” part in “III. Model definition”.

 Return JSON: { "code": 0, "data": { "allow_all_subjects": true, "allow_visitor": true, "box_address": null, "box_heartbeat": null, "box_status": "1", "box_token": null, "camera_address": null,

"camera_name": null, "camera_position": "neo test", "camera_status": null, "description": null, "id": 102, "network_switcher": "http:", "network_switcher_status": "2", "network_switcher_token": "2wee", "screen_token": "Guard_10:2a:b3:4f:d7:f3", "type": 2 }, "page": {} }

4.3 Get all available local hosts



URL: /system/boxes



Method: GET



Description: Get all available local hosts



Parameter: None



Return value: Field Type Specification all_screens screen list box_token str Host Token company_id int Company ID current_version string Configuration version used by current host heartbeat int Timestamp (second) of receiving host heartbeat information

Field Type Specification status str 1 indicates heartbeat information has not been received for a long time, 0 indicates normal leaf_config map Recognition algorithm related configuration dog_expiration int softdog expiration time



Return JSON:

{ "all_screens": [ { "allow_all_subjects": true, "allow_visitor": true, "box_address": "10.101.2.10", "box_heartbeat": 1467884088, "box_status": "0", "box_token": "c4589b6d-29a6-4e26-a91e-8e317a193104", "camera_address": "rtsp://10.201.105.38/live1.sdp1", "camera_name": "", "camera_position": "\u95e8\u53e3", "camera_status": "0", "description": null, "id": 161, "network_switcher": "", "network_switcher_status": null, "network_switcher_token": null, "screen_token": "9c8e8bc4-7371-4a4d-9fd7-9e89cade245d", "type": 1 } ], "box_address": "127.0.0.1", "box_token": "duyufei-test", "company_id": 2, "current_version": null, "dog_expiration": "", "heartbeat": 0, "id": 8, "leaf_config": { "-quality": 0.75, "-threshold": 78, "-unthreshold": 62, "-video.facemin": 50 }, "model": 3,

"status": "1" }

4.4 Create access control



URL: /system/screen



Method: POST



Description: Create access control (one channel of Facial Recognition camera)



Parameter: Parameter Type Required Description box_id int √ Host ID, this parameter can be acquired by /system/boxes interface and indicates which host is required to use for recognition network_switcher string Network switch IP description string description camera_address string √ Camera video streaming address camera_position string √ Camera position



Return value: None



Return JSON:

{ "code": 0, "data": {}, "page": {} }

4.5 Modify single access control setting



URL: /system/screen/[id]



Method: PUT



Description: Modify single access control setting



Parameter: Parameter Type Required Description camera_name str Name camera_address str Camera video streaming address camera_position str Camera position network_switcher str Network switch IP allow_all_subjects bool Whether all person are allowed to access allow_visitor bool Whether visitors are allowed to access allowed_subject_ids array of int Accessible person ID list

Note: the format of interface 4.5 is json. 

Return value: The same as in section 4.2



Return JSON: The same as in section 4.2

4.6 Delete single access control setting



URL: /system/screen/[id]



Method:

DELETE



Description: Delete single access control setting



Parameter: None



Return value: None



Return JSON:

{ "code": 0, "data": {}, "page": {} }

• 5. Historical record

5.1 Historical recognition record



URL: /event/events



Method: GET



Description: This interface is to get historical recognition record



Parameter: Parameter Type Required Description start int Start time timestamp (second) end int End time timestamp (second)

Parameter Type Required Description user_role int role {if omitted: all users, 0: staff (default), 1: visitor, 2: VIP} user_name str Fuzzy query according to user name screen_id int Query according to access control ID subject_id int Precise query according to user ID page int Page number default value is 1 size int Items per page: default 10, maximum is 1000, 1000 will be used if the value is bigger than 1000



Return value: Field Type Specification age float Estimated Age: this attribute is only support for bullet camera. Return -1 if the no value returned within 5 seconds. company_id int Company ID confidence float Similarity gender float Probability of gender is male photo string Snapshot photo url quality float Photo quality screen Refer to “Definition of screen” Snapshot camera subject Refer to “Definition of subject” Snapshot subject object

Field Type Specification timestamp int Snapshot timestamp (second) page Refer to “Paging information definition”



Return JSON:

{ "code": 0, "data": [ { "age": 35.7292, "company_id": 1, "confidence": 87.4096, "gender": 0.999992, "group": 80, "id": 2581617, "photo": "https://o7rv4xhdy.qnssl.com/@/static/upload/event/2016-05- 31/452cb86b9e81add249451837637ab020482229ab.jpg", //snapshot "quality": 0.75279, "screen": { // reference to appendix access control model definition "allow_all_subjects": true, "allow_visitor": true, "box_address": "10.201.105.162", "box_heartbeat": 1464683851, "box_status": "0", "box_token": "5c31ba4b-f9c5-4b3f-bb21-fd632b73b690", "camera_address": "rtsp://10.201.105.51/live1.sdp", // address of camera used for snapshot "camera_name": "", "camera_position": "tss\u5de5\u4f4d\u6d4b\u8bd5", //snapshot position "camera_status": "0", "description": null, "id": 706, "network_switcher": "", "network_switcher_status": null, "network_switcher_token": null, "screen_token": "55e6fb9d-5153-43e2-9829-1dba83e6810f", "type": 1 //snapshot equipment type: 1. Camera, 2. Access control PAD }, "subject": { // snapshot person information, please reference appendix model definition in detail. "avatar": "https://o7rv4xhdy.qnssl.com/@/static/upload/avatar/2015-12- 02/ed49064ca0eb5853f98b1c73a7a69cc1306c051a.jpg", "birthday": null, "come_from": "",

"company_id": 1, "department": "Develop-PD", //department "description": "easy come\uff0ceasy go\uff01", //signature "email": "xyb@megvii.com", "end_time": 0, "entry_date": null, "gender": 0, "id": 7021, "interviewee": "", "job_number": "135", // Job number "name": "\u89e3\u8a00\u658c", //Name "password_reseted": true, "phone": "15652936120", "photos": [ //underlying database avatar list { "company_id": 1, "id": 16491, "quality": 0.940321, "subject_id": 7021, "url": "https://o7rv4xhdy.qnssl.com/@/static/upload/photo/2015-11- 12/bb1758c460abf63ec00bee908cf8e187f87b6547.jpg", "version": 2 } ], "purpose": 0, "remark": "", "start_time": 0, "subject_type": 0, // person type "title": "", "visit_notify": null }, "subject_id": 7021, //person ID "timestamp": 1464683891 }, ... ], "page": { "count": 251967, // total record number "current": 1, // current page number "size": 10, //size per page "total": 25197 // total pages } }

• 6. Attendance record

6.1 Attendance record



URL: /attendance/records



Method: GET



Description: Attendance record



Parameter: Parameter Type Default Required Description start_time int Null (no limitation) Timestamp of Start Time (accurate to the day, the timestamp of midnight should be used, e.g. 2016- 01-01 is 1451577600） end_time int Null (no limitation) Timestamp of End time (second) user_name str Null (no limitation) Fuzzy query according to user name department str Null (no limitation) Fuzzy query according to department subject_id int Null (no limitation) Precise query according to user ID Note: time division point for attendance record is 06:00am, therefore, if you choose the attendance record between 2016-01-01 and 2016-01-03, night time of 2016-01-04 will be shown in the check_out_time.



Return value:

Field Type Specification check_in_time int The earliest check-in record check_out_time int The latest check-in record clock_in int Check-in status clock_out int Check-out status date int Date timestamp (second) id int Index ID subject Refer to “Definition of subject” Subject object worktime str Working hours page Refer to “Paging information definition”



Return JSON:

{ "code": 0, "data": [ { "check_in_time": 1465178327, // The earliest check-in record "check_out_time": 1465215678, // The latest check-in record "clock_in": 1, "clock_out": 1, "date": 1465142400, //timestamp (second) of midnight of date "id": 2260067, "subject": { "avatar": "https://o7rv4xhdy.qnssl.com/@/static/upload/photo/2016-06- 03/21a32f098a064fb088f3ef16c6fb80830abc1d79.jpg", "birthday": null, "department": "", "description": "", "end_time": 0, "entry_date": null, "id": 49774, "job_number": "", //Job number "name": "\u90ed\u7389\u9999", // name "remark": "",

"start_time": 0, "subject_type": 0, "title": "" }, "worktime": "10\u5c0f\u65f622\u5206" } ], "page": { "count": 15745, // total record number "current": 1, // current page "size": 1, // size per page "total": 15745 // total pages } }

• 7. Age and gender analysis（Deprecated）

7.1 Age and gender statistics（Deprecated）



URL: /statistics/overview



Method: GET



Description: Query the login statistics data during a period of time for a company, which include number of people of different genders and different age groups.



Parameter: Parameter Type Required Description start_time str √ Start time of query time quantum end_time str √ End time of query time quantum Parameter specification: the format of time parameter is: “2015-11-26 11:53:00”.



Return value:

Field Type Specification ages array Length is 100, each item indicates number of male or female between age 1 and 100. gender map Total number of male or female.



Return JSON:

{ "code": 0, "data": { "ages": [ [0, 0], [1, 2], ... ], "gender": { "female": 0, "male": 0 } }, "page": {} }

7.2 Age and gender record（Deprecated）



URL: /statistics/event



Method: GET



Description: Query all specific recognition record during a period of time.



Parameter: Parameter Type Required Description start_time str √ Start time of query time quantum end_time str √ End time of query time quantum

Parameter Type Required Description page int Page number (default is page 1) size int Pagesize int (default is 20) unique int Whether the query remove duplicate, 0 indicates retaining duplicates, 1 indicates removing duplicates, default is 0. position str Screen position name which is camera_position in screen model, if this parameter is passed, only this position data are returned, if not, all position data are returned. Parameter specification: the format of time parameter is: “2015-11-26 11:53:00”.



Return value: Field Type Specification age float Age company_id int Company ID gender float Male probability photo str Snapshot photo subject_id int subject ID timestamp int Occurrence time



Return JSON:

{ "code": 0, "data": [ { "age": 24.1945, "company_id": 1, "gender": 1.0, "id": 2150, "photo": "/static/event/screen/2015-11-20/3cf9efdcd461ee1f584d678c19aff692a38371a3.jpg", "subject_id": null,

"timestamp": 1448019496 }, ... ], "page": { "count": 563, "current": 1, "size": 20, "total": 29 } }

• 8. Pad interface

8.1 Pad login



URL: /pad/login



Method: POST



Description: This interface is used for registering access control equipment, and obtaining screen_token which will be used as a parameter in interfaces 1:1 and 1:N in the host.



Parameter: Parameter Type Required Description username str √ Login email password str √ Login password pad_id str √ Unique ID generated by Pad device_type str √ Fixed value: 2



Return value:

Field Type Specification avatar str Avatar address boxes list Host list company_id int Company ID password_reseted bool Save the password or not role_id int Account type screen_token str One channel recognition camera token username str User name



boxes Field Type Specification box_address str Host address box_token str Host Token company_id int Company ID



Return JSON:

{ "code": 0, "data": { "avatar": null, "boxes": [ { "box_address": "10.201.102.3", "box_token": "token", "company_id": 1, "id": 1 } ], "company_id": 1, "id": 2, "password_reseted": false,

"role_id": 2, "screen_token": "29HSPI3412PwrZUM", "username": "a" }, "page": {} }

8.2 Add visitor



URL: /pad/add-visitor



Method: POST



Description: Add visitors for the current login company.



Parameter: Parameter Type Required Specification come_from string Visitor company description string Displayed signature during recognition end_time int Timestamp (second) of end time of visit, default is 2 hours after current time. interviewee string Interviewee name name string √ Visitor name photo file User database photo used for recognition purpose int Purpose of visit which can reference appendix: model definition. remark string remark start_time int Timestamp (second) of start time of visit, default is 5 minutes before current time.

Parameter Type Required Specification vip string VIP visitor or not, default is no.



Return value: None



Return JSON:

{ "code": 0, "data": {}, "page": {} }

8.3 Set pad information



URL: /pad/set-info



Method: PUT



Description: This interface is used to configure PAD information.



Parameter: Parameter Type Required Description pad_id string √ pad_id box_token string Current connected host box_token position string Position of access control pad network_switcher string Switch IP network_switcher_token string Unique switch identifier (the second generation switch)



Return value:

None



Return JSON:

{ "code": 0, "data": {}, "page": {} }

• 9. Recognition push

9.1 Recognition message push (Deprecated)



URL: socket.io/event/



Description: Subscribe by socket.io, push related message to users when recognition events happened. This interface is deprecated, please use 11.1 Get recognition result (websocket interface) to get real-time recognition events.

• II. Local host API

Notice: the calling address of the local host API is not https://v2.koalacam.net but interfaces provided by the local hosts.

• 10. Static recognition

10.1 1:N recognition

 URL:

http://local host address:8866/recognize

 Method:

POST

 Description:

Before calling this interface, /pad/login should be called to obtain screen_token of the equipment. Local host address is the corresponding field value in the host information returned when /pad/login interface login.

 Parameter:

Parameter Type Required Description image file √ Photo used for recognition screen_token str √ Obtained form/pad/login interface

 Return value description:

Field Type Specification person dict Recognized users, confidence indicates similarity, tag indicates user information. can_door_open bool Open the door or not according to comprehensively considering access control setting, current time and user recognition results. error int 0: allowed, 1: not allowed, 2: visiting time is not reached or expired, 3: only allowed for authorized staffs, 4: access control setting is set as closed at this moment, 5: access control setting is set as closed at this moment, 6:settings not found, 7: stranger

 Return result { "person": { "confidence": 96.52632, "tag": "{\"subject_type\": 0, \"start_time\": 0, \"name\": \"A\u4e01\u4e9a\u5149\", \"title\": \"\", \"department\": \"\", \"end_time\": 0, \"description\": \"hahah\", \"id\": 175, \"avatar\": \"/static/upload/photo/2015-10- 22/b7a6916b663129c4078a089307da3f8893c22652.jpg\"}", "id": "175" }, "can_door_open": true, "error": 0 }

10.2 1:1 authentication

 URL:

http://local host address:8866/checkin

 Method:

POST

 Description:

Local host address is the corresponding field value in the host information returned from /pad/login interface.

 Parameter:

Parameter Type Required Description image file √ Photo used for recognition person_id int √ Authenticator ID Notice: person_id is subject_id which is returned after 2.3 Create user is successful.

 Return value description:

person_id is user id recognized by photo recognition, if return value is 0 indicates the user has not been recognized.

 Return result { "code": 0, "data": { "person_id": 1 }, "page": {} }

• 11. Video streaming recognition

11.1 Get recognition result (websocket interface)

 URL:

ws://loca host address:9000/video

 Method:

GET

 Description:

Local host address is the corresponding field value in the host information returned from /pad/login interface.

 Parameter:

Parameter Type Required Description url str √ Video streaming address, such as rtsp://10.101.1.60/live1.sdp, before transferred to the server, url encode must be done for this parameter. Note: this request parameter is GET parameter like ws://192.168.1.50:9000/video?url=rtsp%3A%2F%2F192.169.1.60%2Fuser%3Dadmin%26password %3D%26channel%3D1%26stream%3D0.sdp

 Return value description: 

When a person appears in the video stream, until his/her leaving, all captured images for this person will be marked as one track by the algorithm, each track will be assigned with one id, the same track indicates the same one person.



Three are three possible flows for the algorithm processing:

• recognizing...recognizing...gone
• recognizing...recognizing...recognized，gone
• recognizing...recognizing...unrecognized，gone

Field Type Specification screen Screen Information of recognition position, exists when type is not gone.

Field Type Specification person Person The person similar to the user photo database, exists when type is recognized.

• pen_door

bool Open the door or not, exists when type is recognized. error string If open_door is false, this field indicates the reason why the door is not open. type string Four types of this information: lastface (recognizing), recognized, unrecognized, gone data RecognizeInfo Underlying information of the algorithm, this attribute doesn’t need to be processed if there is no special requirement, wherein track is track id. Only when type is gone, age and gender information are included in this field.



Value change in data, for firmware after version 2.8:

 The value of status changes from string to a dictionary. 'status': { 'recognize_status’:’not_determined’, 'snapshot_status': 'ongoing' } the value of recognize_status is

assigned as stranger, not_determined and recognized respectively, which indicate stranger, undetermined and recognized. The value of snapshot_status is assigned as ongoing and gone. If ongoing is assigned, the program sends a real-time face calculation result. If recognize_status is not assigned not_determined, then judgment is finished, the program will not send the subsequent real-time face calculation result. If gone is assigned, then Track is finished, and the program will sent the face calculation result with the best quality. feature_id is added in person, not used at present and the value is fixed to 0. Foliage will individually send attr delayed after the track is finished, therefore, attr field is cancelled in recognition messages.



Person（unlisted and unspecified fields are the same as that of subject） Field Type Specification src base64 image Real-time snapshot photos

 Return result

{ "data": { "status": { 'recognize_status’:'recognized', 'snapshot_status': 'ongoing' }, "track": 0, "timestamp": 1474454214, "face": { "image": "", "rect": { "top": 207, "right": 913, "bottom": 775, "left": 345 } }, "person": { "feature_id": 0, "confidence": 79.35476, "tag": "{\"subject_type\": 0, \"description\": \"\", \"start_time\": 0, \"birthday\": null, \"id\": 103821, \"remark\": \"\", \"name\": \"\\u5218\\u5b9a\\u5cf0\", \"title\": \"\", \"job_number\": \"\", \"entry_date\": null, \"end_time\": 0, \"department\": \"\", \"avatar\": \"http://10.201.105.140:8867/static/upload/photo/2016-09- 21/12345f1ea4fff5df02edadffa37c82308bde0e63.jpg\"}", "id": "103821" }, "quality": 0.7678973 }, "screen": { "camera_address": "rtsp://10.101.1.66/live1.sdp", "allowed_subject_ids": [], "network_switcher_status": "0", "box_token": "66666666-f988-4fc9-8a67-6a4c4220dd8a", "description": "", "box_heartbeat": 1474454143, "network_switcher": "10.201.105.47", "camera_name": "", "camera_status": "0", "allow_visitor": true, "screen_token": "55VkFeQOHzgoIMQe", "network_switcher_token": null, "box_status": "0", "allow_all_subjects": true, "type": 1, "id": 243, "camera_position": "\u4e0a\u65b9\u540a\u88c5", "box_address": "10.201.105.140" }, "person": {

"src": "data:image/jpeg;base64...", "remark": "", "subject_type": 0, "description": "", "title": "", "timestamp": 1474454214, "start_time": 0, "avatar": "http://10.201.105.140:8867/static/upload/photo/2016-09- 21/12345f1ea4fff5df02edadffa37c82308bde0e63.jpg", "job_number": "", "birthday": null, "entry_date": null, "department": "", "end_time": 0, "id": 103821, "name": "\u5218\u5b9a\u5cf0" }, "error": "\u5141\u8bb8\u8fdb\u5165", "open_door": true, "type": "recognized" }  POST callback function support

After setting callback address on hos:8866 page, this address will be request in POST method, try three times at most if the request failed. The data format is as following:

{ 'short_group': -1, // unused field 'confidence': 59.541946, // confidence 'fmp_error': 0, // whether fmp detection is passed 'group': -1, // unused field 'event_type': 0, //0 indicates reliable 'timestamp': 1527076819, // timestamp of start time of recognition 'photo': 'image base64', // image base64 'age': 46.27829360961914, // gender recognition 'photo_md5': '148dae134019f2d9d11a052166f60708', //image md5, used for removing duplicates 'fmp': 0, // fmp fraction, 0 indicates unused，started with a floating number between 0 and 1. 'screen_token': '59f35a', // screen token, used for finding camera 'gender': 0.9878131151199341, // gender 'quality': 0.9966946775093675, // image quality 'subject_id': None // stranger is None, employee or visitor is an actual subject_id value 'subject_photo_id': // this item does not exist when the photo is from a strange, if photo is from an employee or a visitor, this item is corresponding recognized photo id }

11.2 Dynamic 1:1 interface

 URL:

http://local host address:8866/video_verify

 Method:

POST

 Description:

Check whether the face in the video matches with the person of provided Image or Feature.

 Parameter:

Parameter Type Description url str Video streaming address, such as rtsp://10.101.1.60/live1.sdp this parameter must be processed by url encode before transferred to the server. rect (optional) string/JSON rect indicates face position, post 4 numbers with format like 100,110,120,130, which indicates left, up, right, down

• respectively. If this rect parameter is posted, face detection will

be skipped, the face position specified by rect will be used directly for locating the face position. image file Provided image for comparison

 Return value description: { "face_info": { "rect": { "left": 197, "top": 454, "right": 752, "bottom": 1009 }, } "result": { "confidence": 92.330423, "result": { "track": 7, "quality": 0.975,

"rect": { "left": 688, "top": 394, "right": 1028, "bottom": 734 }, "image": "Base64 encoded JPEG image" }, "recognized": true }, }

result.confidence represents for confidence, result.result represents for check result, result.recognized represents for whether the person in image/Feature can be matched. face_info represents for the face position in the image. This interface will firstly check the face appears no early than time.gate_reserve, if matched face found in this period of time, the interface will return result directly; Otherwise, wait for at most the time of time.gate_wait; if still no matched face found, return the face with the highest similarity score. The default value of the two parameters is 3 seconds and 2 seconds respectively, which means the face searching will be performed within 5 seconds. If no face appears within 5 seconds, result.confidence and result.result will not be returned.

• III. Model definition

Definition of subject: user or visitor Property Type Specification Remark subject_type int User type 0: staff, 1: visitor, 2: VIP visitor email string Email password_reseted bool Whether the password has been reset name string Name pinyin string Pinyin of name gender int Gender 0-unselected, 1-male, 2-female phone str Phone

Property Type Specification Remark avatar str Avatar address department str Department title str Title description str Signature job_number str Job number remark str Remark birthday int Birthday Timestamp (second) entry_date int Entry date Timestamp (second) photos list Recognition photo list purpose int (visitor property) purpose of visit 0: others, 1: interview, 2: business, 3: relatives and friends, 4: courier delivery interviewee str (visitor property) interviewee come_from str (visitor property) visitor company start_time int (visitor property) scheduled visit start time Timestamp (second) end_time int (visitor property) scheduled visit end time Timestamp (second) visit_notify bool (visitor property) whether APP notification is pushed for visit Definition of recognition photo

Property Type Specification subject_id int subject ID company_id int Company ID url str Photo storage address quality float Photo quality version int Recognition algorithm version feature str Features extracted by algorithm Definition of screen: access control information, which is one channel of Facial Recognition camera Property Type Specification Remark id int Unique identification

• f screen

type int type 1: camera, 2: access control Pad, 3: front desk Pad box_address str Ip of the host connected with camera box_heartbeat int Host heatbeat timestamp (second) box_status str Connection status between server and host ‘1’ indicates the host heartbeat message has not been received for a long time, and ‘0’ indicates status is normal. camera_address str Camera ip camera_position str Camera position description

Property Type Specification Remark camera_status str Connection status between server and camera ‘0’ indicates connection is normal network_switcher str Network switch ip network_switcher_status str Network switch connection statue ‘0’ indicates connection is normal allow_all_subjects bool Whether everybody is allowed to access allow_visitor bool Whether visitors are allowed to access

• IV. Error code definition

Error code Specification 1000 Unknown error 1001 Request method is not permitted 1002 Parameter error 1003 Database error 1004 Operation not permitted 1005 Network error 1006 Invalid theme 1007 The password needs to be changed

Error code Specification 1008 Secondary validation error 1009 Server pressure problem because of the facial feature extraction, please try again 1010 Picture file format is not correct 1011 core down 2000 Invalid username 2001 Group does not exist 2002 Group already exists 2003 Camera does not exist 2004 Core dose not exist 2005 Invalid username 2006 Invalid photo 2007 Invalid host 2008 Invalid screen 2009 Invalid company 2010 Invalid historical record 2011 User name already exists 2012 Company already exists 2013 Invalid equipment, please refresh. 2105 Visitor machine does not exist

Error code Specification 2106 Visitor machine is disabled. 2107 Interviewee does not exist. 2108 Short message service (SMS) failure 2109 DevicdID has already be registered 2110 The user has no permission on this visitor machine. 2111 photo_id error 20011 Host already exists 20012 Host bound 20013 Host unbound 20014 Host and user company are inconsistent 20110 Name already exists 20120 Photo storage is full 20130 Excel erroneous 20140 Invalid file 20141 File format error 20150 Email already exists 20160 Insufficient privileges 20170 Upload pictures too large 20171 Upload pictures too small

Error code Specification 3000 Incorrect password 3001 The verification code is not correct 3002 The two passwords do not match 3003 Please login 3004 This account is not bound to the host 4001 Failed to obtain weather information 5000 No face detected 5001 Incorrect camera configuration 5002 Invalid JSON format 5003 Name already exists 5004 Face quality is too low 5005 Face brightness is too low 5006 Face brightness is too high 5007 Face brightness is uneven, Please provide pictures with even face brightness. 5008 Excessive face angle, please provide frontal face picture. 5009 Excessive face angle, please provide frontal face picture. 5010 Excessive face angle, please provide frontal face picture. 5011 Face is not clear, please provide clear face picture. 5012 The eyes are covered, please provide uncovered face picture.

Error code Specification 5013 Face is too small, please provide face picture with enough pixels. 5014 The eyes are covered, please provide uncovered face picture. 5015 Please provide color face pictures. 5016 Facial incompleteness, please provide full face picture. 6000 The camera is being deleted. 6001 Too many password errors 6002 Because you have entered the wrong password 3 times continuously. 6013 Organization already exists. 6014 Invalid organization. 6015 The company is not in the organization. 6016 The user is not bound to the company

• V. Paging information definition

If one API has paging function, the page filed of the return values will have content: Property Type Specification count int Total number of pieces of data current int Which page is returned (counting from 1) size int How many pieces of data per page

Property Type Specification count int Total pages

{ "page":{ "count": 757, "current": 1, "size": 10, "total": 76 } }