# 接口简介在H5增强版中，支持使用方基于业务方案，前置配置一套固定套餐，包括H5端/活体认证等配置参数，生成一个H5临时配置ID，并将该临时配置ID拼接到身份认证H5服务的链接url参数上，后续可以根据该临时配置ID搭配用户的认证资料在一定有效期内使用。此方案可有效减少服务端API请求报文长度，加快接口响应速度。调用此接口，由于是从服务端发起请求，使用临时秘钥/长期秘钥均可。 # 特殊说明临时配置ID(ConfigID)会在生成的一段时间后失效，有效期为15分钟，请注意定期刷新逻辑，保证传入的临时配置ID是有效的。 ## 请求说明 |名称 |内容 | |---|---| |接口地址 |[https://visual.volcengineapi.com](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,|HMAC\-SHA256：签名方法|\ | | | |SignedHeaders={SignedHeaders}, Signature= |Credential：签名凭证，其中，|\ | | | | |\-AccessKeyId是访问密钥ID，可在 [访问密钥（Access Key）](https://www.volcengine.com/docs/6291/65568) 获取；|\ | | | | |\-ShortDate是请求的短时间，使用UTC时间，精确到日。请使用格式：YYYYMMDD，例如：20180201|\ | | | | |\-Region默认为cn\-north\-1|\ | | | | |\-Service默认为cv|\ | | | | |SignedHeaders是参与签名计算的头部信息，content\-type 和 host 为必选头部|\ | | | | |Signature是签名，可在 [签名方法](https://www.volcengine.com/docs/6369/67269) 获取。|\ | | | | |注：我们提供了SDK及签名示例供您实现服务快速接入，具体可参考 [快速接入](https://www.volcengine.com/docs/6444/69729) | |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配置](https://www.volcengine.com/docs/86081/1660370?lang=zh)），获取**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 |自定义协议名称 |选填 |\-\- |需要保证show_guide=1（协议在认证首页）、ignore_homepage_agreement=false（不能隐藏协议）时才会显示协议名称 | |protocol_link |string |自定义协议链接 |选填 |\-\- |需要保证show_guide=1（协议在认证首页）、ignore_homepage_agreement=false（不能隐藏协议）时才会显示协议链接 | |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` | |ignore_homepage_agreement |bool |是否不展示h5认证页面协议 |选填，默认false |false |展示协议 | |^^|^^|^^|^^|true |不展示协议 | |ignore_bottom_text |bool |是否隐藏h5认证页面底部文案 |选填，默认false |false |展示h5认证页面底部文案 | |^^|^^|^^|^^|true |不展示h5认证页面底部文案 | **LivenessConfig** |**参数** |**类型** |**功能描述** |**是否必填** |**取值** |**说明** | |---|---|---|---|---|---| |

|

|

|

|0 |无源（根据一张基准图进行认证） |\ |ref_source

|string

|在h5_config.type为0或1或2时，该字段必须设置为1，表示有源认证。

|必填

| | |\ | | || | | |\ | | |

| | | |\ | | |在h5_config.type为3时，可以设置为0、1、2，用于区分有源、无源、只做活体检测不认证

| | | |\ | | | | | | | |^^|^^|^^|^^|1 |有源（根据身份证号和姓名进行认证） | |^^|^^|^^|^^|2 |仅做活体检测不认证（**需开通【身份认证（无源比对）】** ） | |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] | |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伪代码展示了解密一个字段过程。| | | | |\ |```Plain| | | | |\ |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认证结果查询](https://www.volcengine.com/docs/86081/1660371?lang=zh)中的source_comp_details | | |verify_req_measure_info |json |是 |计费说明，部分服务异常情况时无法返回。详细见：[H5认证结果查询](https://www.volcengine.com/docs/86081/1660371?lang=zh)最下方业务错误码中的verify_req_measure_info | | |verify_algorithm_base_resp |json |是 |子错误说明，可以进一步区分错误原因，部分服务异常情况时无法返回。详细见[H5认证结果查询](https://www.volcengine.com/docs/86081/1660371?lang=zh)最下方业务错误码中的verify_algorithm_base_resp。 | | |byted_token |string |是 |本次人脸核身的唯一token | | **（4）请求Body输入示例** ```json { "req_key":"cert_h5_config_init", "h5_config":{ "type":"0", "theme_color":"rgba(56, 123, 255, 1)", "show_guide":"1", "show_result":"1", "enable_record":"1", "redirect_url":"https://xxx" }, "liveness_config":{ "ref_source":"1", "liveness_type":"motion", "liveness_timeout":10, "motion_list":[ "0", "1", "2", "3" ], "fixed_motion_list":[ "0" ], "motion_count":2, "max_liveness_trial":10 } } ``` ### ConfigID配置示例下面会列出几种常见接入场景的配置数据格式，便于业务侧快速接入。 **示例1：** 完整的默认参数模版（推荐）。 ```typescript const postData = { h5_config: { type: '0', theme_color: 'rgba(56, 123, 255, 1)', show_guide: '1', show_result: '1', protocol_name: '', protocol_link: '', enable_record: '1', redirect_url: 'https://xxx.com', }, liveness_config: { ref_source: '1', liveness_type: 'motion', liveness_timeout: 10, motion_list: ['0', '1', '2', '3'], fixed_motion_list: [], motion_count: 2, max_liveness_trial: 10, }, ... }; ``` **示例2：** 业务侧已存有用户资料（身份照片或者身份信息），不需要使用身份认证服务提供的证件照片上传功能和身份信息输入功能。 ```typescript const postData = { h5_config: { type: '3', // 其余参数根据实际情况配置，注意必填参数 ... }, liveness_config: { // 1. 如果业务侧使用一张基准图发起认证，则配置为0 ref_source: '0', // 2. 如果业务侧使用身份证号和姓名发起认证，则配置为1 ref_source: '1', // 其余参数根据实际情况配置，注意必填参数 ... }, ... }; ``` **示例3：** 业务侧需要将认证数据存储到自定义TOS ```typescript const postData = { h5_config: { // 其余参数根据实际情况配置，注意必填参数 ... }, liveness_config: { // 其余参数根据实际情况配置，注意必填参数 ... }, // Tos参数的获取，参考火山引擎文档：https://www.volcengine.com/product/TOS tos_config: { sts_ak: '', sts_sk: '', sts_token: '', bucket: '', endpoint: '', region: '', }, ... }; ``` ## 输出说明 **（1）通用输出参数** 请参考[通用返回字段及错误码](https://www.volcengine.com/docs/6444/69728) **（2）业务输出参数** data 字段说明 |字段名 |类型 |必选/可选 |说明 |备注 | |---|---|---|---|---| |algorithm_base_resp |json |必选 |[子错误码说明](https://www.volcengine.com/docs/86081/1660363?lang=zh) | | |config_id |string |必选 |h5配置id（有效期15分钟） | | **（3）输出示例** ```json { "code":10000, "data":{ "algorithm_base_resp":{ "status_code":0, "status_message":"SUCCESS" }, "binary_data_base64":[ ] ,//binary_data_base64用不到，忽略即可 "config_id":"64490c8a-c7fa-440d-932b-901718bf0120" //有效期默认15min }, "message":"Success", "request_id":"202401311809085C5A66054DCF27C647E6", "status":10000, "time_elapsed":"28.392133ms" } ``` ## 错误码 **（1）通用错误码** 请参考[通用返回字段及错误码](https://www.volcengine.com/docs/6444/69728) **（2）业务错误码** |HttpCode |错误码 |错误消息 |描述 | |---|---|---|---| |200 |10000 |"Success" |成功 |

图像生成大模型