版本更新历史

  • API版本:1.2.9
  • 服务器版本: 2.9.0

  • 本地主机版本: 2.9.3

    内容 操作 描述
    - 修改 新增黄名单,subject_type类型
    - 修改 更新错误码

  • 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, 3，必须要指定start_time，end_time), 如果传入参数subject_type=3时, 请先在门禁设置页面开启黄名单功能。
    参数 类型 默认值 必选 描述
    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访客, 3: 黄名单}
    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 √ 识别照片

注意：此接口格式为 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, 3，必须要指定start_time，end_time), 如果传入参数subject_type=3时, 请先在门禁设置页面开启黄名单功能。
    参数 类型 默认值 必选 描述
    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访客, 3: 黄名单}
    name str √ 姓名

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

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_ids array 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）

二、本地主机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访客, 3: 黄名单
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
1012 禁止使用删除操作
1013 不支持的SEARCH MODEL: %s
2000 用户不存在
2001 Group 不存在
2002 Group 已存在
2003 相机不存在
2004 Core 不存在
2005 用户不存在
2006 照片不存在
2007 主机不存在
2008 屏幕不存在
2009 公司不存在
2010 历史记录不存在
2011 用户名已存在
2012 公司已存在
2013 设备不存在，请刷新
2014 该设备已经登录其它公司
2105 访客机不存在
2106 访客机已经被禁用
2107 拜访的用户不存在
2108 短信发送失败
2109 DevicdID已经被注册
2110 用户没有此访客机使用权限
2111 错误的photo_id
20011 主机已经存在
20012 主机已绑定
20013 主机未绑定
20014 主机与用户公司不符
20015 该主机已绑定%s路相机，已达最高限制，无法继续绑定
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
        }
    }