业务在使用活体sdk完成认证后,可以通过服务端调用此接口获取活体认证相关数据。此数据有效期为1小时。由于存储为异步行为,因此会有秒级延迟,若获取不到结果请重试。
名称 | 内容 |
---|---|
接口地址 | https://visual.volcengineapi.com?Action=CertLivenessVerifyQuery&Version=2022-08-31 |
请求方式 | POST |
Content-Type | application/json |
公共请求参数请参考调用方法
Body请求参数
业务请求参数
字段名 | 类型 | 必选/可选 | 说明 | 备注 |
---|---|---|---|---|
req_key | string | 必选 | 此处请填写cert_pro_liveness_verify_query | |
byted_token | string | 必选 | 通过Token接口获取的byted_token | |
omit_data | bool | 可选 | 默认为 | |
omit_image_data | bool | 可选 | 默认为 | 该参数优先级低于 |
omit_video_data | bool | 可选 | 默认为 | 该参数优先级低于 |
(1)通用输出参数
请参考通用返回字段及错误码
(2)业务输出参数
data 字段说明
字段名 | 类型 | 必选/可选 | 说明 | 备注 |
---|---|---|---|---|
is_attack | bool | 必选 | 本次活体是否为攻击 | |
has_finish_motion_liveness | bool | 必选 | 是否完成端上活体比对 | 注意,本字段在极端情况下可能受端上网络波动等影响导致上报失败,从而导致本结果不准确 |
risk_result | json | 必选 | 风控接口返回结果的json编码字符串,详细内容见下文 | |
images | json | 可选 | 客户端采集的人脸图 | 请求中填写 |
video | string | 可选 | 客户端采集的视频数据 | 请求中填写 |
images_quality_info | json | 必选 | 人脸质量相关信息 | |
tos_data | json | 可选 | 客户在Token接口传入Tos信息时,会返回此字段 | |
verify_algorithm_base_resp | json | 可选 | 子错误说明,可以进一步区分错误原因,部分服务异常情况时无法返回。详细见错误码和计费中的algorithm_base_resp | |
verify_req_measure_info | json | 可选 | 计费说明,部分服务异常情况时无法返回。详细见:错误码和计费中的req_measure_info |
risk_result说明
字段名 | 类型 | 必选/可选 | 说明 | 备注 |
---|---|---|---|---|
score | int | 必选 | 风控分数 | 取值见风控分数与返回码 |
tags | array of string | 必选 | 风险归因列表 | 取值见风控分数与返回码 |
images说明
字段名 | 类型 | 必选/可选 | 说明 | 备注 |
---|---|---|---|---|
image_best | string | 必选 | 人脸图的base64 | |
image_env | string | 必选 | 环境图的base64 |
image_quality_info说明
字段名 | 类型 | 必选/可选 | 说明 | 备注 |
---|---|---|---|---|
image_best | json | 必选 | 人脸图质量得分的json编码字符串(特殊情况下返回可能为空),具体内容见下文人脸图质量得分字段 | |
image_env | json | 必选 | 环境图质量得分的json编码字符串(特殊情况下返回可能为空) |
image_best说明
人脸图质量得分
字段名 | 类型 | 必选/可选 | 说明 | 备注 |
---|---|---|---|---|
comprehensive_score | float64 | 必选 | 人脸综合得分,用于评估图片中人脸质量的综合分数 |
|
face_clarity | float64 | 必选 | 人脸清晰度 |
|
brightness | float64 | 必选 | 人脸亮度 |
|
exposure | float64 | 必选 | 人脸区域曝光度 | 通常为 |
pose_pitch | float64 | 必选 | 俯仰角,代表人脸的上下偏移程度,一般指人在点头时变化的角度 | |
pose_yaw | float64 | 必选 | 偏航角,代表人脸左右偏移的程度,一般指人在摇头时变化的角度 | |
pose_roll | float64 | 必选 | 旋转角,代表人歪头时变化的角度 | |
mouth_occlude | float64 | 必选 | 嘴巴遮挡程度,得分越高遮挡越严重 |
|
left_eye_occlude | float64 | 必选 | 左眼遮挡程度,得分越高遮挡越严重 |
|
right_eye_occlude | float64 | 必选 | 右眼遮挡程度,得分越高遮挡越严重 |
|
have_cap | float64 | 必选 | 是否佩戴帽子,得分越高概率越大 |
|
image_env说明
环境图质量得分,各项内容同image_best
tos_data说明
字段名 | 类型 | 必选/可选 | 说明 | 备注 |
---|---|---|---|---|
bucket | string | 必选 | Tos Bucket | |
image_env_key | string | 必选 | 环境图tos key | |
image_best_key | string | 必选 | 人脸图tos key | |
video_key | string | 必选 | 视频tos key | |
cert_data_key | string | 必选 | 认证信息tos key |
(3)输出示例
{ "code": 10000, "data": { "algorithm_base_resp": { "status_code": 0, "status_message": "SUCCESS" }, "binary_data_base64": [], "has_finish_motion_liveness": true, "images": { "image_best": "xxx", "image_env": "xxx" }, "images_quality_info": { "image_best": "xxx", "image_env": "xxx" }, "is_attack": true, "risk_result": "{\"score\":900,\"tags\":[\"14003\",\"14013\"]}", "tos_data": { "bucket": "", "image_best_key": "", "image_env_key": "", "result_data_key": "", "video_key": "" }, "verify_algorithm_base_resp": { "status_code": 210713, "status_message": "detected using device with high risk" }, "verify_req_measure_info": { "measure_type": "query_num", "value": 1 }, "video": "xxx" }, "message": "Success", "request_id": "202xxxxxxxxx", "status": 10000, "time_elapsed": "134.640624ms" }
(1)通用错误码
请参考通用返回字段及错误码
(2)业务错误码
HttpCode | 错误码 | 错误消息 | 描述 |
---|---|---|---|
200 | 10000 | "Success" | 成功 |