You need to enable JavaScript to run this app.
导航
LivenessQueryPro接口
最近更新时间:2025.04.28 12:21:24首次发布时间:2025.04.28 12:21:24
我的收藏
有用
有用
无用
无用

接口简介

业务在使用活体sdk完成认证后,可以通过服务端调用此接口获取活体认证相关数据。此数据有效期为1小时。由于存储为异步行为,因此会有秒级延迟,若获取不到结果请重试。

限制条件

  1. QPS不得超过10。如有确切需求需要扩容QPS,请联系我们。

请求说明

名称

内容

接口地址

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

可选

默认为false,填写true时Query接口将不会返回图片与视频

omit_image_data

bool

可选

默认为false,填写true时Query接口不会返回图片

该参数优先级低于omit_data参数

omit_video_data

bool

可选

默认为false,填写true时Query接口不会返回视频

该参数优先级低于omit_data参数

输出说明

(1)通用输出参数
请参考通用返回字段及错误码
(2)业务输出参数
data 字段说明

字段名

类型

必选/可选

说明

备注

is_attack

bool

必选

本次活体是否为攻击

has_finish_motion_liveness

bool

必选

是否完成端上活体比对

注意,本字段在极端情况下可能受端上网络波动等影响导致上报失败,从而导致本结果不准确

risk_result

json

必选

风控接口返回结果的json编码字符串,详细内容见下文

images

json

可选

客户端采集的人脸图

请求中填写omit_datatrue时不返回

video

string

可选

客户端采集的视频数据

请求中填写omit_datatrue时不返回

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

必选

人脸综合得分,用于评估图片中人脸质量的综合分数

0-100之间,50以上质量较高

face_clarity

float64

必选

人脸清晰度

0-53以上比较清晰

brightness

float64

必选

人脸亮度

0-1,小于0.08可判定为昏暗

exposure

float64

必选

人脸区域曝光度

通常为0,大于0.6可判定为有过曝光现象

pose_pitch

float64

必选

俯仰角,代表人脸的上下偏移程度,一般指人在点头时变化的角度

pose_yaw

float64

必选

偏航角,代表人脸左右偏移的程度,一般指人在摇头时变化的角度

pose_roll

float64

必选

旋转角,代表人歪头时变化的角度

mouth_occlude

float64

必选

嘴巴遮挡程度,得分越高遮挡越严重

0-1

left_eye_occlude

float64

必选

左眼遮挡程度,得分越高遮挡越严重

0-1

right_eye_occlude

float64

必选

右眼遮挡程度,得分越高遮挡越严重

0-1

have_cap

float64

必选

是否佩戴帽子,得分越高概率越大

0-1

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"

成功