接口简介

业务在完成认证后，可以通过服务端调用此接口获取活体认证相关数据。此数据有效期为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=	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
result_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	必选	认证类型。返回值为real_time（实时认证）, pre_record（降级录制），unknown（极端情况下无法识别具体认证类型时）

示例

请求示例

输出示例

错误码

通用错误码

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

业务错误码

子错误码及计费说明

此处列举了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	输入认证字段查询不到结果
10000	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为计费。

图像生成大模型