You need to enable JavaScript to run this app.
导航

QueryPro接口

最近更新时间2023.12.20 11:51:20

首次发布时间2023.04.10 16:53:22

接口简介

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

限制条件

请求说明

名称内容
接口地址https://visual.volcengineapi.com
请求方式POST
Content-Typeapplication/json

请求参数
(1)header请求参数
公共请求参数

名称类型是否必填示例值描述
X-DateString20201103T104027Z使用UTC标准时间,日期精确到秒,格式:YYYYMMDD'T'HHMMSS'Z'。

Authorization

String

HMAC-SHA256 Credential={AccessKeyId}/{ShortDate}/{Region}/{Service}/request,
SignedHeaders={SignedHeaders}, Signature={Signature}

HMAC-SHA256:签名方法
Credential:签名凭证,其中,
-AccessKeyId是访问密钥ID,可在 访问密钥(Access Key) 获取;
-ShortDate是请求的短时间,使用UTC时间,精确到日。请使用格式:YYYYMMDD,例如:20180201
-Region默认为cn-north-1
-Service默认为cv
SignedHeaders是参与签名计算的头部信息,content-type 和 host 为必选头部
Signature是签名,可在 签名方法 获取。
注:我们提供了SDK及签名示例供您实现服务快速接入,具体可参考 快速接入

X-Security-Token

String

指安全令牌服务(Security Token Service,STS) 颁发的临时安全凭证中的SessionToken:
1.用户 / Service 访问自己的资源则可以使用 AK/SK 直接访问(长期 Token),无需填写该参数。
2.用户 / Service 通过扮演角色去调用接口时需要使用 STS。具体流程:先调用 AssumeRole 获得短期 token, 然后将该 Token 放入该参数去请求目标接口。

(2)Query请求参数
业务请求参数

参数可选/必选类型说明
Action必选String接口名,取值:CertVerifyQuery
Version必选String版本号,取值:2022-08-31

(3)Body请求参数
业务请求参数

字段名类型必选/可选说明备注
req_keystring必选此处请填写cert_pro_verify_query
byted_tokenstring必选通过Token接口获取的byted_token
omit_databool可选默认为false,填写true时Query接口将不会返回图片与视频
omit_image_databool可选默认为false,填写true时Query接口不会返回图片该参数优先级低于omit_data参数
omit_video_databool可选默认为false,填写true时Query接口不会返回视频该参数优先级低于omit_data参数

输出说明

(1)通用输出参数
请参考通用返回字段及错误码

(2)业务输出参数
data 字段说明

字段名类型必选/可选说明备注
resultbool必选是否核验通过
risk_resultjson string必选风控接口返回结果的json编码字符串,详细内容见下文
imagesjson可选客户端采集的人脸图请求中填写omit_datatrue时不返回
videostring可选客户端采集的视频数据请求中填写omit_datatrue时不返回
source_comp_detailsjson必选比对相关信息
tos_datajson可选客户在Token接口传入Tos信息时,会返回此字段
verify_algorithm_base_respjson可选子错误说明,可以进一步区分错误原因,部分服务异常情况时无法返回。详细见错误码和计费中的algorithm_base_resp
verify_req_measure_infojson可选计费说明,部分服务异常情况时无法返回。详细见:错误码和计费中的req_measure_info

risk_result说明

字段名类型必选/可选说明备注
scoreint必选风控分数取值见风控分数与返回码
tagsarray of string必选风险归因列表取值见风控分数与返回码

images说明

字段名类型必选/可选说明备注
image_beststring必选人脸图的base64
image_envstring必选环境图的base64

source_comp_details说明

字段名类型必选/可选说明备注
scorefloat64必选比对分数
thresholdsjson必选比对分数阈值
image_face_detailjson string必选人脸图质量得分的json编码字符串(特殊情况下返回可能为空),具体内容见下文
image_env_detailjson string必选环境图质量得分的json编码字符串(特殊情况下返回可能为空)
alivebool必选活体算法是否通过活体认证成功为true,无论认证是否失败

thresholds说明

字段名类型必选/可选说明备注
1e-3float64必选0.1%置信度阈值
1e-4float64必选0.01%置信度阈值此值为判断是否通过的标准
1e-5float64必选0.001%置信度阈值
1e-6float64必选0.0001%置信度阈值

image_face_detail说明
人脸图质量得分

字段名类型必选/可选说明备注
comprehensive_scorefloat64必选人脸综合得分,用于评估图片中人脸质量的综合分数0-100之间,50以上质量较高
face_clarityfloat64必选人脸清晰度0-53以上比较清晰
brightnessfloat64必选人脸亮度0-1,小于0.08可判定为昏暗
exposurefloat64必选人脸区域曝光度通常为0,大于0.6可判定为有过曝光现象
pose_pitchfloat64必选俯仰角,代表人脸的上下偏移程度,一般指人在点头时变化的角度
pose_yawfloat64必选偏航角,代表人脸左右偏移的程度,一般指人在摇头时变化的角度
pose_rollfloat64必选旋转角,代表人歪头时变化的角度
mouth_occludefloat64必选嘴巴遮挡程度,得分越高遮挡越严重0-1
left_eye_occludefloat64必选左眼遮挡程度,得分越高遮挡越严重0-1
right_eye_occludefloat64必选右眼遮挡程度,得分越高遮挡越严重0-1
have_capfloat64必选是否佩戴帽子,得分越高概率越大0-1

image_env_detail说明
环境图质量得分,各项内容同image_face_detail

tos_data说明

字段名类型必选/可选说明备注
bucketstring必选Tos Bucket
image_env_keystring必选环境图tos key
image_best_keystring必选人脸图tos key
video_keystring必选视频tos key
cert_data_keystring必选认证信息tos key

(3)输出示例

{
    "code":10000,
    "data":{
        "result": false,
        "risk_result": '{"score":0,"tags":[]}',
        "images": {
            "image_best": "",
            "image_env": ""
        },
        "video": "",
	      "source_comp_details": {
		        "alive": true,
		        "image_env_detail":
		        '{"comprehensive_score":72.7593973238521,"face_clarity":3.6389399293661118,"exposure":0,"brightness":0.9492753623188406,"pose_pitch":-0.53,"pose_yaw":0.405,"pose_roll":0.388,"mouth_occlude":0.000026744861315819435,"left_eye_occlude":0.000018301761883776635,"right_eye_occlude":0.0026939630042761564,"have_cap":0.00002657439654285554}',
		        'image_face_detail':
		        '{"comprehensive_score":72.7593973238521,"face_clarity":3.6389399293661118,"exposure":0,"brightness":0.9492753623188406,"pose_pitch":-0.53,"pose_yaw":0.405,"pose_roll":0.388,"mouth_occlude":0.000026744861315819435,"left_eye_occlude":0.000018301761883776635,"right_eye_occlude":0.0026939630042761564,"have_cap":0.00002657439654285554}',
		        "score": 87.69,
		        "thresholds": {
		            "1e-3": 60,
		            "1e-4": 70,
		            "1e-5": 80,
		            "1e-6": 90
		        }
		    },
        "tos_data": {
            "bucket": "",
            "image_env_key": "",
            "image_best_key": "",
            "video_key": "",
            "cert_data_key": ""
        },
        "verify_algorithm_base_resp": {
            "status_code": 0,
            "status_message": ""
        },
        "verify_req_measure_info": {
            "measure_type": "query_num",
            "value": 0
        }
    },
    "message":"Success",
    "request_id":"6838889517957515275",
    "time_elapsed":"41.897331ms"
}

错误码

(1)通用错误码
请参考通用返回字段及错误码

(2)业务错误码

HttpCode错误码错误消息描述
20010000"Success"成功