接口简介

业务已存有用户认证资料的情况下，可以通过服务端直接调用Token接口将用户资料进行上传，不进行端上OCR/手动输入。支持有源比对场景上传身份证+姓名；无源比对场景上传基准图。此接口同时支持进行端上动作活体的相关参数配置。

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

限制条件

QPS不得超过10。如有确切需求需要扩容QPS，请联系我们。

请求说明

名称	内容
接口地址	https://visual.volcengineapi.com?Action=CertToken&Version=2022-08-31
请求方式	POST
Content-Type	application/json

请求参数

公共请求参数请参考调用方法

Body请求参数

基础参数：

字段名	类型	必选	说明
req_key	string	必选	此处请填写cert_pro_token
ref_source	string	必选	比对类型	可选类型： 0：无源比对 1：有源比对 2 ：仅做活体检测不认证（需开通【身份认证（无源比对）】）
sts_token	string	必选	通过STS接口获取的临时token

用户认证资料参数：

有源比对下：

字段名	类型	必选/可选	说明	备注
idcard_name	string	有源比对时必选	身份证姓名
idcard_no	string	有源比对时必选	身份证号

无源比对下：

字段名	类型	必选/可选	说明	备注
ref_image	string	无源比对下必选	输入图片的base64数组，在无源比对时需要传入1张用户的基准图，有源比对无需传入

活体/安全配置相关：

字段名	类型	必选/可选	说明	备注
liveness_timeout	int	可选	端上活体超时时长	可选范围： [5, 60]，默认：10
max_liveness_trial	int	可选	端上活体最大尝试次数	可选范围：[1, 100]，默认：10
risk_liveness_type	json	可选	依据风险等级的活体类型，下文会详细解释其结构
risk_motion_count	json	可选	依据风险等级下发的动作数量，下文会详细解释其结构
risk_motion_list	json	可选	依据风险等级的可下发动作列表，下文会详细解释其结构
risk_fixed_motion_list	json	可选	依据风险等级的固定要下发的动作列表，下文会详细解释其结构
reflection_mode	int	可选	炫彩校验模式，当risk_liveness_type命中reflection动作类型时生效	可选模式：0:默认 1: 严格

自定义存储/回调配置相关：

字段名	类型	必选/可选	说明	备注
tos_info	json	可选	TOS即火山引擎对象存储，在需要将认证数据存储到自身业务TOS时必传
callback_info	json	可选	回调配置信息

除此以外，你还可以提前将相对固定的参数传入生成一个配置ID，以传入配置ID的形式代替某些固定参数

字段名	类型	必选/可选	说明	备注
config_id	string	可选	固定配置ID，固定配置的说明与使用方式请参考Config接口

数据结构说明：

tos_info

字段名	类型	必选/可选	说明	备注
sts_ak	string	必选	通过STS接口获取的临时AK，在需要将认证数据存储到自身业务TOS时必传
sts_sk	string	必选	通过STS接口获取的临时AK，在需要将认证数据存储到自身业务TOS时必传
sts_token	string	必选	通过STS接口获取的临时AK，在需要将认证数据存储到自身业务TOS时必传
bucket	string	必选	TOS Bucket
endpoint	string	必选	TOS Endpoint
region	string	必选	TOS Region

risk_liveness_type

字段名	类型	必选/可选	说明	备注
free	string	必选	设备无风险时的动作类型	默认motion，可选类型： motion（默认）：动作活体 reflection：炫彩活体（仅在使用SDK时生效） still：静默活体（仅在使用SDK时生效）
low	string	必选	设备低风险时的动作类型	默认motion，可选类型同上
medium	string	必选	设备中风险时的动作类型	默认motion，可选类型同上
high	string	必选	设备高风险时的动作类型	默认reflection，可选类型同上

risk_motion_count

字段名	类型	必选/可选	说明	备注
free	int	必选	设备无风险时下发动作数量	默认2，可选范围：[1, 4]
low	int	必选	设备低风险时下发动作数量	默认2，可选范围同上
medium	int	必选	设备中风险时下发动作数量	默认3，可选范围同上
high	int	必选	设备高风险时下发动作数量	默认4，可选范围同上

risk_motion_list

字段名	类型	必选/可选	说明	备注
free	array of string	必选	设备无风险时可下发动作列表	默认全部可下发，可选动作： 0：眨眼 1：张嘴 2：点头 3：摇头
low	array of string	必选	设备低风险时可下发动作列表	默认全部可下发，可选值同上
medium	array of string	必选	设备中风险时可下发动作列表	默认全部可下发，可选值同上
high	array of string	必选	设备高风险时可下发动作列表	默认全部可下发，可选值同上

risk_fixed_motion_list

字段名	类型	必选/可选	说明	备注
free	array of string	必选	设备无风险时固定下发的动作列表	默认为空，可选动作同risk_motion_list中动作
low	array of string	必选	设备低风险时固定下发的动作列表	默认为空，可选值同上
medium	array of string	必选	设备中风险时固定下发的动作列表	默认为空，可选值同上
high	array of string	必选	设备高风险时固定下发的动作列表	默认为空，可选值同上

callback_info

字段名	类型	必选/可选	说明	备注
switch	bool	必选	如需主动推送结果的回调，请填入true	默认false
block	bool	必选	如需阻塞式回调，请填入true	默认false
url	string	必选	回调的目标位置	默认为空串，且仅当非空串时才尝试回调
client_name	string	必选	回调接收客户的唯一代号，用于回调信息的加密	使用回调功能的接入方必须注册，获取代号以及对应的秘钥

Body示例

以下为body示例，已脱去敏感参数

回调说明

当回调开关为true时，在callback_info中提供的url会收到HTTP POST的回调信息，为application/json格式，各字段如下，重要字段皆使用AES-CBC对称加密，使用该功能的接入方应联系我们获取唯一秘钥。

回调信息解密：回调报文的body为json编码序列，除了result字段，其余字段均使用AES-CBC对称加密算法，使用的秘钥为128位，秘钥(key)和初始化向量(iv)一致，解密后的数据最后一字节存储了填充字节数，解密后的数据去掉填充字节数为有效部分，取有效部分即为原始json序列，以下python伪代码展示了解密一个字段过程。

字段名	类型	是否加密	说明	备注
result	bool	否	认证结果
source_comp_details	json	是	认证的分数和阈值。详细见：Query接口中的source_comp_details
verify_req_measure_info	json	是	计费说明，部分服务异常情况时无法返回。详细见：错误码和计费中的req_measure_info
verify_algorithm_base_resp	json	是	子错误说明，可以进一步区分错误原因，部分服务异常情况时无法返回。详细见错误码和计费中的algorithm_base_resp。
byted_token	string	是	本次人脸核身的唯一token

输出说明

（1）通用输出参数

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

（2）业务输出参数

data 字段说明

字段名	类型	必选/可选	说明	备注
byted_token	string	必选	本次人脸核身的唯一token
client_config	string	必选	客户端SDK需要用到的配置信息，请直接透传给端上。

（3）输出示例

错误码

（1）通用错误码

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

（2）业务错误码

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

图像生成大模型