版本更新历史

API版本:1.2.8
服务器版本： 2.8.0
本地主机版本:2.9.2

内容操作描述

4.5 修改修改门禁接口

4.7 增加用户绑定门禁

4.8 增加用户解绑门禁
API版本：1.2.7
服务器端版本：2.7.0

内容	操作	描述
4.5	修改	修改门禁接口
4.7	增加	用户绑定门禁
4.8	增加	用户解绑门禁

本地主机版本：2.9.1

内容	操作	描述
2.8	增加	删除用户底库接口
2.9	增加	入库图片质量判断接口
2.10	增加	一个接口完成照片和人员注册
11.2	增加	动态 1:1 接口
11.1	修改	本地主机信息返回支持post回调

API版本：1.2.6
服务器端版本：2.0

本地主机版本：2.8.0

内容	操作	描述
4.1	修改	增加分页参数
11.1	修改	输出数据变化
11.2	删除	新固件不再支持
11.3	删除	新固件不再支持
- API版本：1.2.5
- 服务器端版本：1.5
- 本地主机版本：2.6

内容	操作	描述
9.1	删除	接口废弃，建议使用11.视频流识别
11.1	修改	删除示例程序，请访问API相关实例
- API版本：1.2.4
- 服务器端版本：1.5
- 本地主机版本：2.6

内容	操作	描述
11.2	增加
11.3	增加
- API版本：1.2.3
- 服务器端版本：1.5
- 本地主机版本：2.6

内容	操作	描述
11.1	修改描述
- API版本：1.2.2
- 服务器端版本：1.5
- 本地主机版本：2.6

内容	操作	描述
9.1	修改，并标记为过时的(Deprecated)	socketio的transport只能用websocket类型，不可以用polling
- API版本：1.2.1
- 服务器端版本：1.5
- 本地主机版本：2.6

内容	操作	描述
7.2	修改	增加分页参数
2.7	修改	返回值增加quality等
- API版本：1.2
- 服务器端版本：1.5
- 本地主机版本：2.6

内容	操作	描述
10.1 1比N识别	修改	返回值里增加了"screen"数据
- API版本：1.1
- 服务器端版本：1.4.2
- 本地主机版本：2.5

内容	操作	描述
文档格式	整理

一、服务器端API
功能	方法	接口url	接口作用
0. 错误处理
1. 登录	POST	/auth/login	1.1 登录
2. 底库管理	GET	/mobile-admin/subjects	2.1 获取所有用户列表
	GET	/mobile-admin/subjects/list/	2.2 获取用户列表（分页分类可搜索）
	POST	/subject	2.3 创建用户
	GET	/subject/[id]	2.4 获取用户信息
	PUT	/subject/[id]	2.5 更新用户信息
	DELETE	/subject/[id]	2.6 删除用户
	POST	/subject/photo	2.7上传识别照片
	DELETE	/subject/photo	2.8 删除用户底库接口
	POST	/subject/photo/check	2.9 入库图片质量判断接口
	POST	/subject/file	2.10 创建用户，支持直接上传图片
3. 用户头像	POST	/subject/avatar	3.1 上传显示头像
4. 门禁管理	GET	/system/screen	4.1 获取门禁列表
	GET	/system/screen/[id]	4.2 获取门禁信息
	GET	/system/boxes	4.3 获取所有可用本地主机
	POST	/system/screen	4.4 创建一个门禁
	PUT	/system/screen/[id]	4.5 更新门禁信息
	DELETE	/system/screen/[id]	4.6 删除门禁
	PUT	/subject/bind_camera	4.7 用户绑定门禁
	DELETE	/subject/bind_camera	4.8 用户解绑门禁
5. 历史记录	GET	/event/events	5.1 历史识别记录
6. 考勤记录	GET	/attendance/records	6.1 考勤记录
7. 年龄性别分析（Deprecated）	GET	/statistics/overview（Deprecated）	7.1 年龄性别统计
7. 年龄性别分析（Deprecated）	GET	/statistics/event（Deprecated）	7.2 年龄性别记录
8. Pad 接口	POST	/pad/login	8.1 登录
	POST	/pad/add-visitor	8.2 添加访客
	PUT	/pad/set-info	8.3 设置Pad信息
9. 识别推送（Deprecated）	socket.io	/event/	9.1 识别消息推送（Deprecated）
二、本地主机端API
功能	方法	接口url	接口作用
10. 静态识别	POST	/recognize	10.1 1比N识别
10. 静态识别	POST	/checkin	10.2 1比1认证
11. 视频流识别	websocket	ws://[本地主机ip]:9000	11.1 获取识别结果（websocket接口）
11. 视频流识别	POST	/video_verify	11.2 动态 1:1 接口
附录
三、模型定义
四、错误码定义
五、分页信息定义

标识符说明

概念	解释
code	0表示正常，其他参考错误码定义
id	数据库索引
subject	识别对象：员工，访客
avatar	subject显示的头像
photo	subject上传的识别照片
box	主机盒子
network_switch	网络开关
screen	一路识别相机

注意服务器API地址为： https://v2.koalacam.net
离线版API地址为： http://主机ip
此文档内接口除特别说明外，传入参数均为JSON格式（另外需要注意Content-Type需要为 application/json）,请自行转换格式

一、服务器端API

0. 错误处理

未登录

如果没有调用登录接口，在调用别的接口时会返回HTTP 302重定向，用这个来判断是否登录
没权限

如果登录的账户没有调用某个接口的权限，在调用这个接口时会返回HTTP 302重定向

1. 登录

1.1 登录

URL:

/auth/login
Method:

POST
描述：

登录并获取cookie，后面所有的接口都需要在请求时带入此cookie
参数：

参数类型必选描述

username str √ 邮箱

password str √ 密码

参数	类型	必选	描述
username	str	√	邮箱
password	str	√	密码

此接口需要设置user-agent为 "Koala Admin" , 否则不能登录成功
请用公司业务账户登陆，不要用admin@megvii.com账号登陆。

返回值说明：

字段	类型	说明
avatar	str	头像地址
company_id	int	公司ID
password_reseted	bool	是否保存密码
role_id	int	账号类型, 1:root, 2:管理员, 3:普通用户
username	str	用户名

返回JSON：

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

2. 底库管理

2.1 获取所有用户列表

URL:

/mobile-admin/subjects
Method:

GET
描述：

获取所有底库用户列表，包括访客
参数：

无
返回值说明：

返回的data字段是subject对象列表，subject字段含义可以参考subject模型定义
返回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 获取用户列表(分类分页可搜索)

URL:

/mobile-admin/subjects/list
Method:

GET
描述：

按参数分类获取指定的用户

参数：

参数	类型	默认值	必选	描述
category	string	空	√	'employee' - 员工; 'visitor' - 所有访客; 'vip' - VIP访客
name	string	空		要筛选的人的中文或拼音
order	string	'time'		排序的方式: 'time' - 按照创建时间倒序排序; 'name' - 按照英文和拼音的字典序排序
page	int	1		第几页
size	int	10		每页多少条数据

返回值说明：

返回的是subject对象数组，subject字段含义可以参考subject模型定义
返回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 创建用户

URL:

/subject
Method:

POST
描述：

创建一个新用户

参数:（`如果subject_type不等于0，必须要指定start_time，end_time`)

参数	类型	默认值	必选	描述
start_time	int	0		来访时间
end_time	int	0		离开时间
purpose	int	0		来访目的
birthday	int	0		生日
entry_date	int	0		入职时间
photo_ids	array	[]		识别头像列表（通过接口2.7上传识别头像），在接口[2.5. 更新用户信息]为必填参数
gender	int	男		性别{0: 未选择, 1: 男, 2: 女}
email	str	空		邮箱
phone	str	空		手机
avatar	str	空		头像图片base64编码
department	str	空		部门
title	str	空		职位
description	str	空		签名
interviewee	str	空		受访人
come_from	str	空		来访单位
job_number	str	空		工号
remark	str	空		备注
subject_type	int		√	用户类型 {0:员工, 1:访客, 2: VIP访客}
name	str		√	姓名

返回值说明：

创建的subject信息
返回JSON：

同2.4. 获取用户信息接口

2.4 获取用户信息

URL:

/subject/[id]
Method:

GET
描述：

获取单个subject信息
参数：

无
返回值说明：

返回的是data字段是一个subject对象，subject字段含义可以参考subject模型定义
返回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 更新用户信息

URL:

/subject/[id]
Method:

PUT
描述：

对用户的部分字段进行更新
参数：

(photo_ids为必填参数，形式为列表，空列表会删除用户所有图片)
参考2.3. 创建用户
返回值说明：

修改后的的subject信息
返回JSON：

同2.4 获取用户信息接口

2.6 删除用户

URL:

/subject/[id]
Method:

DELETE
描述：

删除用户
参数：

无
返回值说明：

无
返回JSON：

无

2.7 上传识别底库

URL:

/subject/photo
Method:

POST
描述：

个人识别照片上传

参数：

参数	类型	必选	描述
photo	file	√	识别照片
subject_id	int		若传入此参数，则在图片上传成功的同时更新用户的识别照片。否则需要手动将返回的id (返回值中的563) 放入接口2.3，接口2.5中的photo_ids参数里，实现更新此用户的识别头像

注意：此接口格式为 multipart/form-data 格式

返回值：

字段	类型	说明
id	int	图片的id
company_id	int	公司ID
subject_id	int	数据库索引，如果为null表示照片没有绑定subject
url	str	识别照片地址
quality	float	人脸质量

返回JSON：

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

2.8 删除用户底库接口

URL:

/subject/photo
Method:

DELETE
描述：

删除用户底库接口
参数：

参数类型必选描述

subject_id int √ 识别照片

参数	类型	必选	描述
subject_id	int	√	识别照片

注意：此接口格式为 multipart/form-data 格式

返回值：

无
返回JSON：
```
无
```

2.9 入库图片质量判断接口

URL:

/subject/photo/check
Method:

POST
描述：

入库图片质量判断接口
参数：

参数类型必选描述

photo file √ 识别照片

注意：此接口格式为 multipart/form-data 格式

返回值：

无
返回JSON：

错误情况参考错误码

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

2.10 创建用户，支持直接上传图片

URL:

/subject/file
Method:

POST
描述：

创建一个新用户

参数:（`如果subject_type不等于0，必须要指定start_time，end_time`)

参数	类型	默认值	必选	描述
start_time	int	0		来访时间
end_time	int	0		离开时间
purpose	int	0		来访目的
birthday	int	0		生日
entry_date	int	0		入职时间
photo	file			底库照片
gender	int	男		性别{0: 未选择, 1: 男, 2: 女}
email	str	空		邮箱
phone	str	空		手机
avatar	file			头像照片
department	str	空		部门
title	str	空		职位
description	str	空		签名
interviewee	str	空		受访人
come_from	str	空		来访单位
job_number	str	空		工号
remark	str	空		备注
subject_type	int		√	用户类型 {0:员工, 1:访客, 2: VIP访客}
name	str		√	姓名

注意：此接口格式为 multipart/form-data 格式

返回值说明：

创建的subject信息
返回JSON：

同2.4. 获取用户信息接口

3. 用户头像

3.1 上传头像

URL:

/subject/avatar
Method:

POST
描述：

上传个人头像
参数：

参数类型必选描述

avatar file √ 识别照片

subject_id int √ 图片上传成功的同时更新subject_id用户头像

参数	类型	必选	描述
avatar	file	√	识别照片
subject_id	int	√	图片上传成功的同时更新subject_id用户头像

注意：此接口格式为 multipart/form-data 格式

返回值：

字段类型说明

url str 识别头像地址
返回JSON：

字段	类型	说明
url	str	识别头像地址

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

4. 门禁管理

4.1 获取门禁列表

URL:

/system/screen
Method:

GET
描述：

获取门禁列表
参数：

参数类型必选描述

page int 列表的第n页，默认1

size int 列表每页的条数，默认500
返回值：

返回的data字段是门禁列表，门禁字段含义参考screen模型定义返回的page字段是分页参数, 参考分页信息定义
返回JSON：

参数	类型	必选	描述
page	int		列表的第n页，默认1
size	int		列表每页的条数，默认500

    {
        "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 获取单个门禁设置

URL:

/system/screen/[id]
Method:

GET
描述：

获取单个门禁设置
参数：

无
返回值：

门禁信息，字段含义可以参考screen模型定义
返回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 获取所有可用本地主机

URL:

/system/boxes
Method:

GET
描述：

获取所有可用本地主机
参数：

无

返回值：

字段	类型	说明
all_screens	screen列表
box_token	str	主机Token
company_id	int	公司ID
current_version	string	当前主机使用的配置版本
heartbeat	int	收到主机心跳消息的时间戳（秒）
status	str	值为‘1’表示长时间没有收到heartbeat, ‘0’正常
leaf_config	map	识别算法相关配置
dog_expiration	int	加密狗到期时间

返回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 创建一个门禁（一路识别相机）

URL:

/system/screen
Method:

POST
描述：

创建一个门禁（一路识别相机）

参数：

参数	类型	必选	描述
box_id	int	√	主机ID，通过/system/boxes接口获得，表明需要用哪台主机识别
network_switcher	string		网络开关IP
description	string		描述
camera_address	string	√	相机视频流地址
camera_position	string	√	相机位置

返回值：

无
返回JSON：

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

4.5 修改单个门禁设置

URL:

/system/screen/[id]
Method:

PUT
描述：

修改单个门禁设置

参数：

参数	类型	描述
camera_name	str	名称
camera_address	str	相机视频流地址
camera_position	str	相机位置
network_switcher	str	网络开关IP
allow_all_subjects	bool	是否允许所有人进入
allow_visitor	bool	是否允许访客进入
~~allowed_subject_ids~~	~~array of int~~	~~可进入人员ID列表~~（Deprecated）, 使用4.7，4.8来绑定解绑

注意：此接口格式为json格式

返回值：

同接口4.2
返回JSON：

同接口4.2

4.6 删除单个门禁设置

URL:

/system/screen/[id]
Method:

DELETE
描述：

删除单个门禁设置
参数：

无
返回值：

无
返回JSON：

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

4.7 用户绑定门禁

URL:

/subject/bind_camera
Method:

PUT
描述：

门禁权限设置允许部分员工通过的时候，绑定员工到该门禁
参数：

参数类型必选描述

subject_id int √ 要绑定的员工

screen_id int √ 门禁id
返回值：

无
返回JSON：

参数	类型	必选	描述
subject_id	int	√	要绑定的员工
screen_id	int	√	门禁id

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

4.8 用户解绑门禁

URL:

/subject/bind_camera
Method:

DELETE
描述：

门禁权限设置允许部分员工通过的时候，解绑和该门禁绑定的员工
参数：

参数类型必选描述

subject_id int √ 要解绑的员工

screen_id int √ 门禁id
返回值：

无
返回JSON：

参数	类型	必选	描述
subject_id	int	√	要解绑的员工
screen_id	int	√	门禁id

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

5. 历史记录

5.1 历史识别记录

URL:

/event/events
Method:

GET
描述：

历史识别记录

参数：

参数	类型	必选	描述
start	int		开始时间时间戳（秒）
end	int		结束时间时间戳（秒）
user_role	int		角色 {不传: 所有, 0: 员工(默认)， 1: 访客, 2: VIP}
user_name	str		按用户名模糊查询
screen_id	int		按门禁ID查询
subject_id	int		按用户ID精确查询
page	int	第几页默认 1
size	int		每页数量默认 10，最大1000，大于1000会使用1000

返回值：

字段	类型	说明
age	float	年龄估计，只有枪机会有此项输出，并且如果属性值在5秒内没有返回为-1
company_id	int	公司ID
confidence	float	相似度
gender	float	性别为男的概率
photo	string	抓拍照片url
quality	float	照片质量
screen	screen模型	抓拍相机
subject	subject模型	抓拍的subject对象
timestamp	int	抓拍时间戳（秒）
page	参考分页信息定义

返回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",   //抓拍照
                "quality": 0.75279,
                "screen": {   // 参考附录门禁模型定义
                    "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",  //抓拍的相机地址
                    "camera_name": "",
                    "camera_position": "tss\u5de5\u4f4d\u6d4b\u8bd5",  //抓拍的位置
                    "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                                        //抓拍设备类型 1表示相机  2表示门禁PAD
                },
                "subject": {   // 抓拍的人信息，详细请参考附录的 模型定义
                    "avatar": "https://o7rv4xhdy.qnssl.com/@/static/upload/avatar/2015-12-02/ed49064ca0eb5853f98b1c73a7a69cc1306c051a.jpg",
                    "birthday": null,
                    "come_from": "",
                    "company_id": 1,
                    "department": "Develop-PD",       //部门
                    "description": "easy come\uff0ceasy go\uff01",          //签名
                    "email": "xyb@megvii.com",
                    "end_time": 0,
                    "entry_date": null,
                    "gender": 0,
                    "id": 7021,
                    "interviewee": "",
                    "job_number": "135",           // 工号
                    "name": "\u89e3\u8a00\u658c",  //姓名
                    "password_reseted": true,
                    "phone": "15652936120",
                    "photos": [     //底库头像列表
                        {
                            "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,              // 人员类型
                    "title": "",
                    "visit_notify": null
                },
                "subject_id": 7021,               //人员ID
                "timestamp": 1464683891
            },
            ...
        ],
        "page": {
            "count": 251967,            // 总记录数
            "current": 1,               // 当前页数
            "size": 10,                 // 每页size
            "total": 25197              // 总页数
        }
    }

6. 考勤记录

6.1 考勤记录

URL:

/attendance/records
Method:

GET
描述：

考勤记录

参数：

参数	类型	默认值	描述
start_time	int	空（表示不限）	开始日期（含）时间戳（精确到天，须取该天0点的时间戳（秒），比如 2016-01-01，为 1451577600）
end_time	int	空（表示不限）	结束日期（含）时间戳（秒）
user_name	str	空（表示不限）	按用户名模糊查询
department	str	空（表示不限）	按部门模糊查询
subject_id	int	空（表示不限）	按用户ID精确查询

需要特别注意的是，考勤的分割时间点是每天的6:00, 所以如果选择 2016-01-01 至 2016-01-03 的考勤记录，考勤记录的 check_out_time 可能会出现 2016-01-04夜里的时间。

返回值：

字段	类型	说明
check_in_time	int	最早签到记录
check_out_time	int	最晚签到记录
clock_in	int	签到状态
clock_out	int	签退状态
date	int	日期的时间戳（秒）
id	int	索引ID
subject	subject模型	subject对象
worktime	str	工作时长
page	参考分页信息定义

返回JSON：

    {
        "code": 0,
        "data": [
            {
                "check_in_time": 1465178327, //最早签到记录
                "check_out_time": 1465215678, //最晚签到记录
                "clock_in": 1,
                "clock_out": 1,
                "date": 1465142400,       //日期0点的时间戳（秒）
                "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": "",    //工号
                    "name": "\u90ed\u7389\u9999", // 姓名
                    "remark": "",
                    "start_time": 0,
                    "subject_type": 0,
                    "title": ""
                },
                "worktime": "10\u5c0f\u65f622\u5206"
            }
        ],
        "page": {
            "count": 15745,      //总记录数
            "current": 1,        // 当前第几页
            "size": 1,           // 每页数量
            "total": 15745       // 总页数
        }
    }

7. 年龄性别分析（Deprecated）

7.1 年龄性别统计（Deprecated）

URL:

/statistics/overview
Method:

GET
描述：

查询登录公司某段时间内的统计数据，包括不同性别及年龄段的人数
参数：

参数类型必选描述

start_time str √ 查询时间段的开始时间

end_time str √ 查询时间段的结束时间

参数说明：时间参数的格式为："2015-11-26 11:53:00"

返回值：

字段类型说明

ages array 长度为100，每一项表示1~100岁各年龄的[男，女]人数

gender map 男、女总人数
返回JSON：

字段	类型	说明
ages	array	长度为100，每一项表示1~100岁各年龄的[男，女]人数
gender	map	男、女总人数

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

7.2 年龄性别记录（Deprecated）

URL:

/statistics/event
Method:

GET
描述：

查询某段时间内的所有具体识别记录

参数：

参数	类型	必选	描述
start_time	str	√	查询时间段的开始时间
end_time	str	√	查询时间段的结束时间
page	int		第几页（默认第1页）
size	int		一页多少条数据（默认20条）
unique	int		查询是否排重，0表示不排除，1表示排重，默认值为0
position	str		screen的位置名称（screen模型中的camera_position），如果传了这个参数，就只返回此位置的数据，如果不传这个参数，返回所有位置的数据

参数说明：时间参数的格式为："2015-11-26 11:53:00"

返回值：

字段类型说明

age float 年龄

company_id int 公司ID

gender float 男性的概率

photo str 抓拍照片

subject_id int subject ID

timestamp int 发生时间
返回JSON：

字段	类型	说明
age	float	年龄
company_id	int	公司ID
gender	float	男性的概率
photo	str	抓拍照片
subject_id	int	subject ID
timestamp	int	发生时间

    {
      "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 接口

8.1 Pad 登录

URL:

/pad/login
Method:

POST
描述：

此接口作用是注册一个门禁设备，并得到screen_token，用做后面主机上 1:1 和 1:N接口的参数
参数：

参数类型必选描述

username str √ 登录邮箱

password str √ 登录密码

pad_id str √ Pad 自己生成的唯一 ID

device_type str √ 固定值：2

参数	类型	必选	描述
username	str	√	登录邮箱
password	str	√	登录密码
pad_id	str	√	Pad 自己生成的唯一 ID
device_type	str	√	固定值：2

返回值：

字段	类型	说明
avatar	str	头像地址
boxes	list	主机列表
company_id	int	公司ID
password_reseted	bool	是否保存密码
role_id	int	账号类型
screen_token	str	一路识别相机token
username	str	用户名

boxes

字段类型说明

box_address str 主机地址

box_token str 主机Token

company_id int 公司ID
返回JSON：

字段	类型	说明
box_address	str	主机地址
box_token	str	主机Token
company_id	int	公司ID

    {
      "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 添加访客

URL:

/pad/add-visitor
Method:

POST
描述：

为当前登录公司添加访客

参数：

参数	类型	必选	描述
come_from	string		来访单位
description	string		识别时的显示签名
end_time	int		访问结束时间的时间戳（秒），默认为当前时间后2小时
interviewee	string		受访者姓名
name	string	√	访客姓名
photo	file		用于识别的底库照片
purpose	int		来访目的，含义见附录：模型定义
remark	string		备注
start_time	int		访问开始时间的时间戳（秒），默认为当前时间前 5 分钟
vip	string		是否为 VIP 访客，默认为否

返回值：

无
返回JSON：

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

8.3 设置Pad信息

URL:

/pad/set-info
Method:

PUT
描述：

为当前登录公司添加访客

参数：

参数	类型	必选	描述
pad_id	string	√	pad_id
box_token	string		当前连接的主机box_token
position	string		门禁pad的位置
network_switcher	string		开关IP地址
network_switcher_token	string		开关唯一标识（二代开关）

返回值：

无
返回JSON：

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

9. 识别推送

9.1 识别消息推送（Deprecated）

URL:

socket.io/event/
描述：

通过 socket.io 订阅消息，在有识别事件时为用户推送相关信息这个接口已废弃，请使用11.1 获取识别结果（websocket接口）获取实时识别事件

二、本地主机API

注：本地主机API的调用地址不再是 https://v2.koalacam.net，而是本地主机直接提供的接口

10. 静态识别

10.1 1比N识别

URL:

http://本地主机地址:8866/recognize
Method:

POST
描述：

在调用此接口之前需要调用 /pad/login 获得本设备的screen_token
本地主机地址为 /pad/login 接口登录时返回的主机信息中的相应字段值
参数：

参数类型必选描述

image file √ 用于识别的照片

screen_token str √ 从 /pad/login 接口获得

参数	类型	必选	描述
image	file	√	用于识别的照片
screen_token	str	√	从 /pad/login 接口获得

返回值说明：

字段	类型	说明
person	dict	识别出来的用户, confidence表示相似度，tag表示用户信息
can_door_open	bool	综合考虑门禁设置、当前时间、识别用户后是否可以开门
error	int	0:允许进入, 1:不允许访客进入, 2:来访时间未到或已过期, 3:此门只允许部分员工进入, 4:此刻门禁设置为关闭, 5:此刻门禁设置为关闭, 6:设置找不到, 7:陌生人

返回结果

    {
      "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认证

URL:

http://本地主机地址:8866/checkin
Method:

POST
描述：

本地主机地址为 /pad/login 接口登录时返回的主机信息中的相应字段值
参数：

参数类型必选描述

image file √ 用于识别的照片

person_id int √ 认证者的 ID

参数	类型	必选	描述
image	file	√	用于识别的照片
person_id	int	√	认证者的 ID

注意: person_id即为subject_id，在2.3 创建用户成功之后返回的id

返回值说明：

person_id是从照片识别出来的用户id，如果为0表示未识别出
返回结果

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

11. 视频流识别

11.1 获取识别结果（websocket接口）

URL:

ws://本地主机地址:9000/video
Method:

GET
描述：

本地主机地址为 /pad/login 接口登录时返回的主机信息中的相应字段值
参数：

参数类型必选描述

url str √ 视频流地址, 例如 rtsp://10.101.1.60/live1.sdp。这个参数必须经过url encode再传到服务器

参数	类型	必选	描述
url	str	√	视频流地址, 例如 rtsp://10.101.1.60/live1.sdp。这个参数必须经过url encode再传到服务器

注意：此请求参数为GET参数,形如: ws://192.168.1.50:9000/video?url=rtsp%3A%2F%2F192.169.1.60%2Fuser%3Dadmin%26password%3D%26channel%3D1%26stream%3D0.sdp

返回值说明：
算法会将一个人在视频中出现到离开的所有图片当做一个track，每个track有个id，同一个track的信息都代表一个人

算法处理的流程有可能有三种：

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

字段	类型	说明
screen	Screen	识别位置的信息，只有type不为gone时才会有
person	Person	和底库里相似的人，只有type为recognized时才会有
open_door	bool	是否开门，只有type为recognized时才会有
error	string	如果open_door为false，这个字段就是不能开门的原因
type	string	本条信息的类型，4种，lastface（识别中）、recognized、unrecognized、gone
data	RecognizeInfo	算法识别的底层信息，无特殊需求的话不用处理，其中track为track id。只有当type为gone的时候，这里才包含年龄性别信息。

对于2.8版之后的固件，data中值的变化:
```
status的值从字符串变成一个字典
```
'status': { 'recognize_status’:’not_determined’, 'snapshot_status': 'ongoing' } recognize_status 取值为stranger, not_determined 和 recognized，分别表示陌生人，未定和已识别。

snapshot_status 取值为为 ongoing，gone，如果为 ongoing，则程序发送对实时人脸的计算结果。如果 recognize_status 不为 not_determined，说明已经判定完毕，则程序不再发送后续的实时人脸计算结果。如果为 gone，说明该 Track 已经结束。程序会发送质量最好的人脸的计算结果。

person 中增加feature_id，目前不使用，取值固定为0

因为foliage会延迟（直到track结束）单独发送attr，所以在识别消息里取消attr字段
Person（未列出说明的字段与subject相同）

字段类型说明

src base64 image 实时抓拍的照片
返回结果

字段	类型	说明
src	base64 image	实时抓拍的照片

    {
      "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回调函数支持
在主机:8866页面设置回调地址之后，会以POST方式请求该地址，失败后最多重试三次。数据格式下:

{
    'short_group': -1, // 未使用字段
    'confidence': 59.541946, // 置信度
    'fmp_error': 0, // 是否通过fmp检测
    'group': -1, // 未使用字段
    'event_type': 0, //0表示可信
    'timestamp': 1527076819, // 识别发生时候时间戳
    'photo': 'image base64', // 图片的base64编码
    'age': 46.27829360961914, // 识别年龄
    'photo_md5': '148dae134019f2d9d11a052166f60708', // 图片md5，用于去重
    'fmp': 0, // fmp分数，未开启未0，开始为0～1的一个浮点数
    'screen_token': '59f35a', // 屏幕的token，可用于查找摄像机
    'gender': 0.9878131151199341, // 性别
    'quality': 0.9966946775093675, // 图片质量
    'subject_id': None // 陌生人为None，员工或访客为实际的subject_id
    'subject_photo_id': // 陌生人没有此项，员工或访客为对应的识别到photo id
}

11.2 动态 1:1 接口

URL:

http://本地主机地址:8866/video_verify
Method:

POST
描述：

检查视频画面中是否有图像或 Feature 中的人物。

参数：

参数	类型	描述
url	str	视频流地址, 例如 rtsp://10.101.1.60/live1.sdp。这个参数必须经过url encode再传到服务器
rect (optional)	string/JSON	`rect` 表示人脸位置，传入4个数字，格式 `100,110,120,130`（四个数字分别表示左、上、右、下）。如果传入了 `rect`，则会略过人脸检测一步，直接使用 `rect` 指定的人脸位置进行计算。
image	file	图片

返回值说明：

{
  "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 代表置信度，result.result 代表检查结果，result.recognized 代表是否与图像/Feature 中的人物匹配。face_info 代表输入图像的信息。

该接口会首先检查不早于请求时刻 time.gate_reserve 时间之前的人脸，如果这段时间内包含匹配的人脸，就直接输出；如果没有，就等待最多 time.gate_wait 时间；如果仍没有，就输出最相似的人脸。这两个时间默认配置分别是3秒和2秒，相当于检索会在5s的时间范围内进行。如果在这段时间内没有出现任何人脸，则 result.confidence 和 result.result 均不存在。

三、模型定义

底库对象subject，即用户和访客

属性	类型	说明	备注
subject_type	int	用户类型	0:员工, 1:访客, 2: VIP访客
email	string	邮箱
password_reseted	bool	是否重置过密码
name	string	姓名
pinyin	string	姓名的拼音
gender	int	性别	0-未选择，1-男，2-女
phone	str	电话
avatar	str	头像地址
department	str	部门
title	str	职位
description	str	签名
job_number	str	工号
remark	str	备注
birthday	int	生日	时间戳（秒）
entry_date	int	入职时间	时间戳（秒）
photos	list	识别照片列表
purpose	int	(访客属性) 来访目的	0: 其他, 1: 面试, 2: 商务, 3: 亲友, 4: 快递送货
interviewee	str	(访客属性) 受访人
come_from	str	(访客属性) 来访单位
start_time	int	(访客属性) 预定来访时间	时间戳（秒）
end_time	int	(访客属性) 预定离开时间	时间戳（秒）
visit_notify	bool	(访客属性) 来访是否发APP消息推送

识别照片photo

属性	类型	说明
subject_id	int	subject ID
company_id	int	公司ID
url	str	照片存储地址
quality	float	照片质量
version	int	识别算法版本
feature	str	识别算法抽取出来的特征值

门禁信息screen，即一路识别相机

属性	类型	说明	备注
id	int	screen的唯一标识
type	int	类型	1:摄像头, 2:门禁Pad, 3:前台Pad
box_address	str	相机关联的主机ip地址
box_heartbeat	int	主机心跳时间戳（秒）
box_status	str	服务器与主机连接状态	‘1’表示较长没有收到主机心跳消息，'0'正常
camera_address	str	相机ip地址
camera_position	str	相机位置描述
camera_status	str	服务器与相机连接状态	‘0’表示连接正常
network_switcher	str	网络开关ip地址
network_switcher_status	str	网络开关连接状态	‘0’表示连接正常
allow_all_subjects	bool	是否允许所有人进入
allow_visitor	bool	是否允许访客进入

四、错误码定义

错误码	说明
1000	未知错误
1001	请求方法不允许
1002	参数错误
1003	数据库错误
1004	操作不允许
1005	网络错误
1006	无效主题
1007	密码需要更改
1008	二次验证错误
1009	抽取人脸特征服务压力过大，请重试
1010	图片文件格式不正确
1011	core down
2000	用户不存在
2001	Group 不存在
2002	Group 已存在
2003	相机不存在
2004	Core 不存在
2005	用户不存在
2006	照片不存在
2007	主机不存在
2008	屏幕不存在
2009	公司不存在
2010	历史记录不存在
2011	用户名已存在
2012	公司已存在
2013	设备不存在，请刷新
2105	访客机不存在
2106	访客机已经被禁用
2107	拜访的用户不存在
2108	短信发送失败
2109	DevicdID已经被注册
2110	用户没有此访客机使用权限
2111	错误的photo_id
20011	主机已经存在
20012	主机已绑定
20013	主机未绑定
20014	主机与用户公司不符
20110	姓名已存在
20120	照片已满
20130	Excel 包含错误
20140	文件不存在
20141	文件格式错误
20150	邮箱已存在
20160	权限不足
20170	上传图片过大
20171	上传图片过小
3000	密码不正确
3001	验证码不正确
3002	两次密码不一致
3003	请登录
3004	该账号未绑定本主机
4001	获取天气信息失败
5000	未检测到人脸
5001	摄像头配置不正确
5002	不是有效的 JSON 格式
5003	名称已存在
5004	人脸质量太低
5005	人脸的亮度过低
5006	人脸的亮度过高
5007	人脸的亮度不均匀，请提供脸部光照均匀的图片
5008	人脸角度过大，请提供正脸图片
5009	人脸角度过大，请提供正脸图片
5010	人脸角度过大，请提供正脸图片
5011	人脸不清晰，请提供清晰人脸图片
5012	眼部有遮挡，请提供无遮挡的人脸图片
5013	人脸过小，请提供足够像素的人脸图片
5014	眼部有遮挡，请提供无遮挡的人脸图片
5015	请提供彩色人脸图片
5016	脸部缺失，请提供完整的人脸图片
6000	相机正在删除中
6001	密码错误次数过多
6002	由于您连续输错3次密码
6013	组织已存在
6014	组织不存在
6015	公司不在组织内
6016	用户未绑定公司

五、分页信息定义

如果某条API有分页的功能，那么返回值中的page项会有内容：

属性	类型	说明
count	int	数据总条数
current	int	返回的是第几页（从1开始计数）
size	int	每页多少条数据
count	int	总页数

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

版本更新历史

目录

一、服务器端API

0. 错误处理

未登录

没权限

1. 登录

1.1 登录

URL:

Method:

描述：

参数：

返回值说明：

返回JSON：

2. 底库管理

2.1 获取所有用户列表

URL:

Method:

描述：

参数：

返回值说明：

返回JSON：

2.2 获取用户列表(分类分页可搜索)

URL:

Method:

描述：

参数：

返回值说明：

返回JSON：

2.3 创建用户

URL:

Method:

描述：

参数:（如果subject_type不等于0，必须要指定start_time，end_time)

返回值说明：

返回JSON：

2.4 获取用户信息

URL:

Method:

描述：

参数：

返回值说明：

返回JSON：

2.5 更新用户信息

URL:

Method:

描述：

参数：

返回值说明：

返回JSON：

2.6 删除用户

URL:

Method:

描述：

参数：

返回值说明：

返回JSON：

2.7 上传识别底库

URL:

Method:

描述：

参数：

返回值：

返回JSON：

2.8 删除用户底库接口

URL:

Method:

描述：

参数：

返回值：

返回JSON：

2.9 入库图片质量判断接口

URL:

Method:

描述：

参数：

返回值：

返回JSON：

2.10 创建用户，支持直接上传图片

URL:

参数:（`如果subject_type不等于0，必须要指定start_time，end_time`)

参数:（`如果subject_type不等于0，必须要指定start_time，end_time`)