/liveness/check_liveness

1.接口描述

检查用户拍摄的视频是否为活体

请求方式

POST

请求 URL

https://cloudapi.linkface.cn/liveness/check_liveness

2.请求参数

字段 类型 必需 描述
api_id string 是 API 账户
api_secret string 是 API 密钥
motions string 是 用户动作序列
complexity integer 否 活体检测通过的难易程度
liveness_data_file file 见下方注释 待检查的活体视频文件，上传本地文件进行检测时选取此参数
liveness_data_url string 见下方注释 待检查的活体视频文件的url，采用抓取网络文件方式时需选取此参数
anti_hack bool 否 开启防hack功能。开通：true，不开通：false。默认false，不开通

请求参数 liveness_data_file与liveness_data_url二选一。

目前支持 http/https 等协议的网络地址。下载限时 10s，超时后仍未下载完成则属于失败。

请求参数anti_hack参数决定是否启用防hack，如果启用防hack，调用返回结果会返回anti_hack_result，字段含义详见下文。

请求参数motions由下列动作组成的动作序列字符串。

motion 描述
BLINK 眨眼
MOUTH 张嘴
NOD 点头
YAW 摇头

例如：检测一个眨眼动作, motions为： "BLINK"； 检测眨眼和点头两个动作， motions为： "BLINK NOD"；

complexity检测的难易程度，难易程度越高被攻破概率越小。 默认为：正常模式

complexity 描述
0 简单模式
1 正常模式
2 困难模式
3 地狱模式

各个模式对应的阈值

blink mouth yaw nod allow_tracking_miss 模式
0.2 0.2 0.1 0.2 true 简单
0.2 0.2 0.1 0.2 false 正常
0.5 0.5 0.5 0.5 false 困难
0.7 0.7 0.7 0.7 false 地狱

3.返回参数

正常响应

字段 类型 说明
request_id string 本次请求的id
status string 状态，正常为 OK，其他值表示失败，详见错误码
result object 视屏活体检测的结果，详情见下表“result 中包含字段内容”
anti_hack_result object 对特征图片进行防hack检测的结果，需要设置请求参数anti_hack为true

result中包含字段内容：

字段 类型 说明
passed bool 算法综合各个动作检测结果的判定结果，通过为true，不通过为false，判断是否通过动作检测，只需要根据最外层passed判断即可
feature_image_id string 从活体视频中提取的一张特征照片，请调用liveness/liveness_image接口获取图片， 服务器仅保留该图片一小时，请及时保存图片。
motions object 详见下方motions对象中的内容

motions 对象中的内容:

字段 类型 说明
motion string 动作名称
score number 算法评分
passed bool 该动作算法检测结果

anti_hack_result 对象中的内容:

字段 类型 说明
hack_score float hack检测评分

> 备注：hack_score阈值为0.98，由行业大数据训练得到，大于0.98是hack行为，小于等于0.98是正常活人

返回样例

{
  "request_id": "TID8bf47ab6eda64476973cc5f5b6ebf57e",
  "status": "OK",
  "result": {
    "motions": [{
      "motion": "MOUTH",
      "score": 0.21820485591888428,
      "passed": true
    }],
    "passed": true,
    "feature_image_id": "xxxxxx"
  },
  "anti_hack_result": {
    "hack_score": 0.8164739608764648
  }
}

4.错误码

状态码 status 字段 说明
400 DOWNLOAD_TIMEOUT 网络地址视频获取超时
400 DOWNLOAD_ERROR 网络地址视频获取失败
400 INVALID_ARGUMENT 请求参数错误，具体原因见 reason 字段内容
400 INVALID_COMPLEXITY 复杂度入参错误
400 WRONG_LIVENESS_DATA liveness_data 出错
400 VIDEO_TIME_TOO_LONG 视频时长过长
401 UNAUTHORIZED 账号或密钥错误
401 KEY_EXPIRED 账号过期，具体情况见 reason 字段内容
403 RATE_LIMIT_EXCEEDED 调用频率超出限额
403 NO_PERMISSION 无调用权限
403 OUT_OF_QUOTA 调用次数超出限额
404 NOT_FOUND 请求路径错误
500 INTERNAL_ERROR 服务器内部错误

返回样例

{
    "status": "INVALID_ARGUMENT",
    "reason": "must specify 'liveness_data_file', 'liveness_data_url' or 'liveness_video_id' argument",
      "request_id": "TIDa892b593c0354b0e989b5db67a331607"
}

5.输入示例

  • cURL样例
curl -X POST "https://cloudapi.linkface.cn/liveness/check_liveness?api_id=ID&api_secret=SECRET" \
  -F liveness_data_file=@/PATH/TO/IMAGE \
  -F motions="BLINK MOUTH"

results matching ""

    No results matching ""