接口地址

https://visual.volcengineapi.com

请求方式

POST

Content-Type

application/json

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 放入该参数去请求目标接口。

Action

必选

String

接口名，取值：CertH5ConfigInit

Version

必选

String

版本号，取值：2022-08-31

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秒

type

string

具体的业务接入场景，当前主要有4种场景。

选填，默认0

0

正常流程：OCR上传图片识别 + 输入身份证号和姓名 + 人脸认证。

1

跳过OCR上传图片识别，直接进入输入身份证号和姓名 + 人脸认证。

2

直接进入OCR上传图片识别 + 人脸认证，跳过输入身份证号和姓名。

3

OCR上传图片识别、输入身份证号和姓名 这两个步骤都要跳过，直接进行人脸认证流程。
【注意】适用于业务已存有用户资料的场景。需要业务侧调用服务端接口（参考CertH5Token ），获取bytedToken值后拼接到URL参数上。

theme_color

string

自定义主题色

选填

--

默认颜色 rgba(56, 123, 255, 1)

show_guide

string

是否展示认证首页

选填，默认1

0

不展示

1

展示

show_result

string

是否展示认证结果页

选填，默认1

0

不展示，直接跳转到redirectUrl

1

展示认证成功和失败页

protocol_name

string

自定义协议名称

选填

--

需要保证showGuide=1时才会显示协议名称

protocol_link

string

自定义协议链接

选填

--

需要保证showGuide=1时才会显示协议链接

enable_record

string

优先使用更高效便捷的实时刷脸方案，当设备不支持该方案时的降级处理策略。

选填，默认1

0

当设备不支持实时刷脸能力时，则认定本次认证失败

1

当设备不支持实时刷脸能力时，启用备用认证方案 - 视频录制，该方案能更好的兼容低端设备。

redirect_url

string

认证完成（成功or失败）后，会将部分参数拼接到redirectUrl上并执行跳转。

必填

--

建议使用https开头的URL地址，目前也支持小程序环境下的跳转。
微信小程序的URL格式：wxmini:/pages/path1/path2?query1=xx
支付宝小程序的URL格式：apmini:/pages/path1/path2?query1=xx

ref_source

string

在type=0或1或2时，该字段必须设置为1，表示有源认证。
在type=3时，可以设置为0或者1，用于区分有源or无源认证

必填

0

无源（根据一张基准图进行认证）

1

有源（根据身份证号和姓名进行认证）

liveness_type

string

端上活体类型

必填

motion

动作活体

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]

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时，必填

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.b64decoding(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

algorithm_base_resp

json

必选

子错误码说明

config_id

string

必选

h5配置id（有效期15分钟）

200

10000

"Success"

成功