You need to enable JavaScript to run this app.
导航
身份认证
  • 文档首页
    • /身份认证/接入文档/身份认证（增强版）/服务端API接入/QueryPro接口
QueryPro接口
最近更新时间：2025.01.09 14:58:46首次发布时间：2023.04.10 16:53:22
我的收藏

接口简介

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

限制条件

无

请求说明

名称

内容

接口地址

https://visual.volcengineapi.com

请求方式

POST

Content-Type

application/json

请求参数
（1）header请求参数
公共请求参数

名称

类型

是否必填

示例值

描述

X-Date

String

是

20201103T104027Z

使用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_key

string

必选

此处请填写cert_pro_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参数

include_idcard_data

bool

可选

默认为false，填写true时且本次认证为有源时，返回本次认证涉及的身份证相关信息的字段verify_idcard_info

该参数优先级低于omit_data参数

输出说明

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

字段名

类型

必选/可选

说明

备注

result

bool

必选

是否核验通过

risk_result

json string

必选

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

images

json

可选

客户端采集的人脸图

请求中填写omit_data为true时不返回

video

string

可选

客户端采集的视频数据

请求中填写omit_data为true时不返回

source_comp_details

json

必选

比对相关信息

tos_data

json

可选

客户在Token接口传入Tos信息时，会返回此字段

verify_algorithm_base_resp

json

可选

子错误说明，可以进一步区分错误原因，部分服务异常情况时无法返回。详细见错误码和计费中的algorithm_base_resp

verify_req_measure_info

json

可选

计费说明，部分服务异常情况时无法返回。详细见：错误码和计费中的req_measure_info

verify_idcard_info

json

可选

身份证相关信息，仅在有源认证时返回

risk_result说明

字段名

类型

必选/可选

说明

备注

score

int

必选

风控分数

取值见风控分数与返回码

tags

array of string

必选

风险归因列表

取值见风控分数与返回码

images说明

字段名

类型

必选/可选

说明

备注

image_best

string

必选

人脸图的base64

image_env

string

必选

环境图的base64

source_comp_details说明

字段名

类型

必选/可选

说明

备注

score

float64

必选

比对分数

thresholds

json

必选

比对分数阈值

image_face_detail

json string

必选

人脸图质量得分的json编码字符串（特殊情况下返回可能为空），具体内容见下文

image_env_detail

json string

必选

环境图质量得分的json编码字符串（特殊情况下返回可能为空）

alive

bool

必选

活体算法是否通过

活体认证成功为true，无论认证是否失败

thresholds说明

字段名

类型

必选/可选

说明

备注

1e-3

float64

必选

0.1%置信度阈值

1e-4

float64

必选

0.01%置信度阈值

此值为判断是否通过的标准

1e-5

float64

必选

0.001%置信度阈值

1e-6

float64

必选

0.0001%置信度阈值

image_face_detail说明
人脸图质量得分

字段名

类型

必选/可选

说明

备注

comprehensive_score

float64

必选

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

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

face_clarity

float64

必选

人脸清晰度

0-5，3以上比较清晰

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_detail说明
环境图质量得分，各项内容同image_face_detail
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

verify_idcard_info说明

字段名

类型

必选/可选

说明

备注

idcard_name

string

必选

身份证姓名

idcard_no

string

必选

身份证号

face_photo_base64

string

可选

身份证人像面图片文件base64编码值

需要在进行认证前完成身份证OCR流程(部分服务异常情况时可能无法返回)

national_emblem_photo_base64

string

可选

身份证国徽面图片文件base64编码值

需要在进行认证前完成身份证OCR流程(部分服务异常情况时可能无法返回)

（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

错误码

错误消息

描述

200

10000

"Success"

成功