You need to enable JavaScript to run this app.
导航
身份认证
  • 文档首页
    • /身份认证/接入文档/身份认证（增强版）/H5接入/H5认证结果查询
H5认证结果查询
最近更新时间：2024.08.21 17:16:10首次发布时间：2024.02.23 18:19:31
我的收藏

接口简介

业务在完成认证后，可以通过服务端调用此接口获取活体认证相关数据。此数据有效期为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参数

include_rtc_data

bool

可选

默认为false，填写true时，返回本次认证涉及的RTC相关信息的字段verify_rtc_info

输出说明

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

字段名

类型

必选/可选

说明

备注

result

bool

必选

是否核验通过

images

json

可选

客户端采集的人脸图

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

video

string

可选

客户端采集的视频数据

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

source_comp_details

json

必选

比对相关信息

tos_data

json

可选

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

verify_algorithm_base_resp

json

可选

子错误说明，可以进一步区分错误原因，部分服务异常情况时无法返回。详细见：最下方业务错误码

verify_req_measure_info

json

可选

计费说明，部分服务异常情况时无法返回。详细见：最下方业务错误码

verify_idcard_info

json

可选

认证中涉及的身份证信息

verify_rtc_info

json

可选

认证中涉及的RTC相关信息

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编码值

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

national_emblem_photo_base64

string

可选

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

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

ocr_result_detail

json

可选

OCR相关字段

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

ocr_result_detail说明

字段名

类型

必选/可选

说明

备注

face_side_detail

json

可选

人像页OCR相关字段详情(部分服务异常情况时可能无法返回)

national_emblem_side_detail

json

可选

国徽页OCR相关字段详情(部分服务异常情况时可能无法返回)

face_side_detail说明

字段名

类型

必选/可选

说明

备注

id_number

string

必选

身份证号

name

string

必选

姓名

gender

string

必选

性别

address

string

必选

住址

birth_date

string

必选

出生日期

ethnic

string

必选

民族

national_emblem_side_detail说明

字段名

类型

必选/可选

说明

备注

authority

string

必选

签发机关

valid_period

string

必选

证件有效期

verify_rtc_info说明

字段名

类型

必选/可选

说明

备注

verify_type

string

必选

RTC认证类型。返回值为real_time（实时认证）, pre_record（降级录制），unknown（极端情况下无法识别具体认证类型时）

示例

请求示例

{
    "byted_token": "20240424145340CA5B2C40A4C98FE738XB",
    "include_idcard_data": true,
    "include_rtc_data": true,
    "omit_data": false,
    "omit_image_data": false,
    "omit_video_data": false,
    "req_key": "cert_pro_verify_query"
}

输出示例

{
    "code": 10000,
    "data": {
        "algorithm_base_resp": {
            "status_code": 0,
            "status_message": "SUCCESS"
        }, //可忽略
        "binary_data_base64": [
        ], //可忽略
        "images": [
            "image_best": "/9xxx"  //图片Base64
            "image_env": "/9xxx"   //环境图Base64
        ],
        "req_measure_info": {
            "measure_type": "query_num",
            "value": 0
        }, //可忽略
        "result": true,
        "risk_result": "{\"score\":0,\"tags\":null}", //可忽略
        "source_comp_details": {
            "alive": true,
            "image_env_detail": "{\"comprehensive_score\":80.69880055599236,\"face_clarity\":4.093706846928597,\"exposure\":0,\"brightness\":0.9877300613496932,\"pose_pitch\":-5.845,\"pose_yaw\":0.584,\"pose_roll\":3.291,\"mouth_occlude\":0.00004795013228431344,\"left_eye_occlude\":0.0012884314637631178,\"right_eye_occlude\":0.0016522518126294017,\"have_cap\":0.0007020820630714297}",
            "image_face_detail": "{\"comprehensive_score\":67.95798439695636,\"face_clarity\":3.4177289070844648,\"exposure\":0,\"brightness\":0.974025974025974,\"pose_pitch\":-5.047,\"pose_yaw\":0.335,\"pose_roll\":0.793,\"mouth_occlude\":0.000008950854862632696,\"left_eye_occlude\":0.0002042907872237265,\"right_eye_occlude\":0.001838002004660666,\"have_cap\":0.04160449653863907}",
            "risk_result": "{\"score\":0,\"tags\":null}",
            "score": 88.595,
            "thresholds": {
                "1e-3": 60,
                "1e-4": 70,
                "1e-5": 80,
                "1e-6": 90
            }
        },
        "tos_data": {
            "bucket": "",
            "image_best_key": "",
            "image_env_key": "",
            "result_data_key": "",
            "video_key": ""
        },
        "verify_algorithm_base_resp": {
            "status_code": 0,
            "status_message": ""
        },
        "verify_idcard_info": {
            "idcard_name": "xxx",
            "idcard_no": "11111111111111111"
        },
        "verify_req_measure_info": {
            "measure_type": "query_num",
            "value": 1
        },
        "verify_rtc_info": {
            "verify_type": "real_time"
        },
        "video": "AAAA...."   // 视频Base64
    },
    "message": "Success",
    "request_id": "20240424145506DFF5298E8D3C93ECB5D0",
    "status": 10000,
    "time_elapsed": "8.070665ms"
}

错误码

通用错误码

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

业务错误码

子错误码及计费说明

此处列举了verify_algorithm_base_resp的字段结构和不同取值含义，同时也标注了哪些错误码会被实际计费。
对于计费，如果不关注细节，也可以直接参考req_measure_info字段查看计费信息。
字段结构

字段名

类型

必选/可选

说明

备注

verify_algorithm_base_resp

json

必选

子错误说明。

verify_algorithm_base_resp

字段名

类型

必选/可选

说明

备注

status_code

int

必选

子错误码

status_message

string

必选

子错误描述

子错误码

错误码(code)

认证子错误码(verify_algorithm_base_resp)

认证子错误说明

是否计费

10000

0

认证一致

是

50500

100000

服务内部错误

50501

100001

数据源内部错误

10000

201201

缺少输入参数或输入参数为空

10000

201202

输入参数不合法

10000

201301

输入图片为空

10000

201302

输入图片解码失败

10000

201304

输入图片无法处理

10000

203101

输入图片未检测到人脸

10000

210101

输入认证字段不合格（空、不合法等）

10000

210102

输入认证字段查询不到结果

21010310000

210201

身份证号为空

10000

210202

身份证号无效或不符合规范

10000

210203

姓名为空

10000

210204

姓名不符合规则

10000

210205

身份证查询无结果

10000

210207

认证不一致，姓名与身份证号不匹配

10000

210301

人脸图格式不支持

是

10000

210302

人脸图质量不合格/已损坏

是

10000

210303

人脸图大小过小

是

10000

210304

人脸图为空

10000

210305

人脸图中未检测到人脸

10000

210306

人脸图中存在多个人脸

10000

210307

人脸图特征提取失败

10000

210308

数据源库中的底图质量不合格

是

10000

210309

数据源库中无该身份信息对应的底图

是

10000

210310

人脸图尺寸过大

10000

210311

人脸图不匹配

是

10000

210312

服务端动作活体匹配不通过

10000

210313

认证不一致，疑似本人

是

10000

210314

认证不一致，待对比图像建模失败

是

10000

210701

人脸图质量分数过低

10000

210702

人脸图活体分数过低

10000

210703

人脸图比对分数过低

10000

210704

传入的token参数有误或已过期

10000

210705

动作活体重试次数超过上限

10000

210706

基准图质量过低

10000

210707

基准图不合格

10000

210708

基准图没有人脸

10000

210709

获取基准图失败

10000

210710

获取人脸图失败

计费(verify_req_measure_info)说明

标识此请求是否计费。
字段结构

字段名

类型

必选/可选

说明

备注

verify_req_measure_info

json

必选

计费说明。

verify_req_measure_info

字段名

类型

必选/可选

说明

备注

measure_type

string

必选

取值固定为"query_num"

value

int

必选

取值为0或1。0为不计费，1为计费。