接口简介

在H5增强版中，支持使用方基于业务方案，前置配置一套固定套餐，包括H5端/活体认证等配置参数，生成一个H5临时配置ID，并将该临时配置ID拼接到身份认证H5服务的链接url参数上，后续可以根据该临时配置ID搭配用户的认证资料在一定有效期内使用。此方案可有效减少服务端API请求报文长度，加快接口响应速度。

调用此接口，由于是从服务端发起请求，使用临时秘钥/长期秘钥均可。

特殊说明

临时配置ID(ConfigID)会在生成的一段时间后失效，有效期为15分钟，请注意定期刷新逻辑，保证传入的临时配置ID是有效的。

请求说明

名称	内容
接口地址	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	接口名，取值：CertH5ConfigInit
Version	必选	String	版本号，取值：2022-08-31

（3）Body请求参数

业务请求参数

字段名	类型	必选/可选	说明	备注
req_key	String	必选	此处请填写固定值cert_h5_config_init
h5_config	H5Config	必选	h5页面相关配置
liveness_config	LivenessConfig	必选	活体认证相关配置
tos_config	TOSConfig	可选	自定义tos相关配置
callback_info	CallBackInfo	可选	回调相关配置
expire_duration	int	可选	单位，秒。范围需在[60, 7200]之间；可不传，不传默认值为900秒

H5Config

参数	类型	功能描述	是否必填	取值	说明
type	string	具体的业务接入场景，当前主要有4种场景。	选填，默认0	0	正常流程：OCR上传图片识别 + 输入身份证号和姓名 + 人脸认证。
						1	跳过OCR上传图片识别，直接进入输入身份证号和姓名 + 人脸认证。
						2	直接进入OCR上传图片识别 + 人脸认证，跳过输入身份证号和姓名。
						3	OCR上传图片识别、输入身份证号和姓名这两个步骤都要跳过，直接进行人脸认证流程。【注意】适用于业务已存有用户资料或者只做活体不认证的场景。需要业务侧调用服务端接口（参考H5Token配置），获取bytedToken值后拼接到URL参数上。
theme_color	string	自定义主题色	选填	--	默认颜色 rgba(56, 123, 255, 1)
show_guide	string	是否展示认证首页	选填，默认1	0	不展示
show_guide	string	是否展示认证首页	选填，默认1			1	展示
show_result	string	是否展示认证结果页	选填，默认1	0	不展示，直接跳转到redirectUrl
show_result	string	是否展示认证结果页	选填，默认1			1	展示认证成功和失败页
protocol_name	string	自定义协议名称	选填	--	需要保证show_guide=1（协议在认证首页）、ignore_homepage_agreement=false（不能隐藏协议）时才会显示协议名称
protocol_link	string	自定义协议链接	选填	--	需要保证show_guide=1（协议在认证首页）、ignore_homepage_agreement=false（不能隐藏协议）时才会显示协议链接
enable_record	string	优先使用更高效便捷的实时刷脸方案，当设备不支持该方案时的降级处理策略。	选填，默认1	0	当设备不支持实时刷脸能力时，则认定本次认证失败
enable_record	string	优先使用更高效便捷的实时刷脸方案，当设备不支持该方案时的降级处理策略。	选填，默认1			1	当设备不支持实时刷脸能力时，启用备用认证方案 - 视频录制，该方案能更好的兼容低端设备。
redirect_url	string	认证完成（成功or失败）后，会将部分参数拼接到redirectUrl上并执行跳转。	必填	--	建议使用https开头的URL地址，目前也支持小程序环境下的跳转。微信小程序的URL格式：wxmini:/pages/path1/path2?query1=xx 支付宝小程序的URL格式：apmini:/pages/path1/path2?query1=xx
ignore_homepage_agreement	bool	是否不展示h5认证页面协议	选填，默认false	false	展示协议
ignore_homepage_agreement	bool	是否不展示h5认证页面协议	选填，默认false			true	不展示协议
ignore_bottom_text	bool	是否隐藏h5认证页面底部文案	选填，默认false	false	展示h5认证页面底部文案
ignore_bottom_text	bool	是否隐藏h5认证页面底部文案	选填，默认false			true	不展示h5认证页面底部文案

LivenessConfig

参数	类型	功能描述	是否必填	取值	说明
ref_source	string	在h5_config.type为0或1或2时，该字段必须设置为1，表示有源认证。在h5_config.type为3时，可以设置为0、1、2，用于区分有源、无源、只做活体检测不认证	必填	0	无源（根据一张基准图进行认证）
						1	有源（根据身份证号和姓名进行认证）
						2	仅做活体检测不认证（需开通【身份认证（无源比对）】）
liveness_type	string	端上活体类型	必填	motion	动作活体
liveness_type	string	端上活体类型	必填			reflection	炫彩活体
liveness_timeout	number	端上活体超时时间（单位：秒）	选填，默认10	--	可选范围： [5, 60]
motion_list	string[]	可被下发的动作列表	选填	--	可选动作： 0：眨眼 1：张嘴 2：点头 3：摇头
fixed_motion_list	string[]	固定一定需要下发的动作列表	选填	--	取值同motion_list (要属于motion_list子集)
motion_count	number	选中的动作个数	选填，默认2	--	可选范围：[1, 4] (要≤motion_list数量)
max_liveness_trial	number	端上活体最大尝试次数	选填，默认10	--	可选范围：[1, 100]
reflection_mode	number	炫彩校验模式	当liveness_type填reflection时可选填，默认0	--	可选模式：0:默认 1: 严格

TOSConfig

参数	类型	功能描述	是否必填	取值	说明
sts_ak	string	TOS使用的STS AK	选填	--	如果需要将认证数据存储到自定义TOS时，必填
sts_sk	string	TOS使用的STS SK	选填	--	如果需要将认证数据存储到自定义TOS时，必填
sts_token	string	TOS使用的STS Token	选填	--	如果需要将认证数据存储到自定义TOS时，必填
bucket	string	TOS使用的Bucket	选填	--	如果需要将认证数据存储到自定义TOS时，必填
endpoint	string	TOS使用的Endpoint	选填	--	如果需要将认证数据存储到自定义TOS时，必填
region	string	TOS使用的Region	选填	--	如果需要将认证数据存储到自定义TOS时，必填

CallBackInfo

字段名	类型	必选/可选	说明	备注
switch	bool	选填	如需主动推送结果的回调，请填入true	默认false
block	bool	选填	如需阻塞式回调，请填入true	默认false
url	string	选填	回调的目标位置	默认为空串，且仅当非空串时才尝试回调
client_name	string	必选	回调接收客户的唯一代号，用于回调信息的加密	使用回调功能的接入方必须注册，获取代号以及对应的密钥
回调说明：当回调开关为true时，在callback_info中提供的url会收到HTTP POST的回调信息，为application/json格式，各字段如下，重要字段皆使用AES-CBC对称加密，使用该功能的接入方应联系我们获取唯一秘钥。回调信息解密：回调报文的body为json编码序列，除了result字段，其余字段均使用AES-CBC对称加密算法，使用的秘钥为128位，秘钥(key)和初始化向量(iv)一致，解密后的数据最后一字节存储了填充字节数，解密后的数据去掉填充字节数为有效部分，取有效部分即为原始json序列，以下python伪代码展示了解密一个字段过程。 from Crypto.Cipher import AES import base64 # key为秘钥, iv为初始化向量, content为回调HTTP报文的body内容 cipher = AES.new(key, AES.MODE_CBC, iv) src_cmp_details = json.loads(content)["source_comp_details"] ciphertext = base64.b64decode(src_cmp_details) text = cipher.decrypt(ciphertext) valid_len = text[-1] ret = text[:len(text)-valid_len] # ret为source_comp_details的明文结果
回调参数如下：
字段名	类型	是否加密	说明
result	bool	否	认证结果
source_comp_details	json	是	认证的分数和阈值。详细见：H5认证结果查询中的source_comp_details
verify_req_measure_info	json	是	计费说明，部分服务异常情况时无法返回。详细见：H5认证结果查询最下方业务错误码中的verify_req_measure_info
verify_algorithm_base_resp	json	是	子错误说明，可以进一步区分错误原因，部分服务异常情况时无法返回。详细见H5认证结果查询最下方业务错误码中的verify_algorithm_base_resp。
byted_token	string	是	本次人脸核身的唯一token

（4）请求Body输入示例

ConfigID配置示例

下面会列出几种常见接入场景的配置数据格式，便于业务侧快速接入。

示例1：完整的默认参数模版（推荐）。

示例2：业务侧已存有用户资料（身份照片或者身份信息），不需要使用身份认证服务提供的证件照片上传功能和身份信息输入功能。

示例3：业务侧需要将认证数据存储到自定义TOS

输出说明

（1）通用输出参数

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

（2）业务输出参数

data 字段说明

字段名	类型	必选/可选	说明	备注
algorithm_base_resp	json	必选	子错误码说明
config_id	string	必选	h5配置id（有效期15分钟）

（3）输出示例

错误码

（1）通用错误码

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

（2）业务错误码

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

图像生成大模型