版本更新历史
- API版本:1.2.8
- 服务器版本: 2.8.0
-
本地主机版本:2.9.2
内容 操作 描述 4.5 修改 修改门禁接口 4.7 增加 用户绑定门禁 4.8 增加 用户解绑门禁 -
API版本:1.2.7
- 服务器端版本:2.7.0
-
本地主机版本: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 年龄性别统计 |
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识别 |
POST | /checkin | 10.2 1比1认证 | |
11. 视频流识别 | websocket | ws://[本地主机ip]:9000 | 11.1 获取识别结果(websocket接口) |
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 √ 密码
此接口需要 设置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 获取用户信息
-
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.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 √ 识别照片
注意:此接口格式为 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:
3. 用户头像
3.1 上传头像
-
URL:
/subject/avatar
-
Method:
POST
-
描述:
上传个人头像
-
参数:
参数 类型 必选 描述 avatar file √ 识别照片 subject_id int √ 图片上传成功的同时更新subject_id用户头像
注意:此接口格式为 multipart/form-data 格式
-
返回值:
字段 类型 说明 url str 识别头像地址 -
返回JSON:
{ "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:
{ "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_idsarray of int可进入人员ID列表(Deprecated), 使用4.7,4.8来绑定解绑
注意:此接口格式为json格式
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:
{ "code": 0, "data": {}, "page": {} }
4.8 用户解绑门禁
-
URL:
/subject/bind_camera
-
Method:
DELETE
-
描述:
门禁权限设置允许部分员工通过的时候,解绑和该门禁绑定的员工
-
参数:
参数 类型 必选 描述 subject_id int √ 要解绑的员工 screen_id int √ 门禁id -
返回值:
无
-
返回JSON:
{ "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:
{ "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:
{ "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 -
返回值:
字段 类型 说明 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:
{ "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 接口获得 -
返回值说明:
字段 类型 说明 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
注意: 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再传到服务器
注意:此请求参数为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 实时抓拍的照片 -
返回结果
{ "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访客 |
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 } }