活体检测

优质

小牛编辑

134浏览

2023-12-01

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"

活体检测

1.接口描述

请求方式

请求 URL

2.请求参数

3.返回参数

正常响应

返回样例

4.错误码

返回样例

5.输入示例

cURL样例