发起真人认证
/xmind-cloud-platform/openapi/volcengine?Action=CreateVisualValidateSession&Version=2024-01-01发起真人认证,返回 H5 认证链接。终端用户完成认证后建立真人分组,之后即可上传真人素材。
请求参数
Action 与 Version 通过查询参数传递,其余参数放在 JSON 请求体中。
你自己的结果通知地址,需公网可访问,仅支持 HTTP/HTTPS。不传时认证结束停留在平台结果页,不影响分组建立。
默认值:-真人分组展示名。不传时默认使用分组 ID。
默认值:-配置 CallbackURL 只决定你能否收到主动通知,不影响认证与分组建立。不传时认证结束后照样建组,只是收不到通知,需要自行轮询查询真人认证结果。
认证
所有接口使用同一套火山 V4 签名,凭证与签名方式见火山方舟素材库 API 概览。以下请求头为通用要求:
固定为 application/json。
默认值:application/json实际访问的域名和端口;包含端口时必须写入签名。
默认值:-UTC 时间,格式 yyyyMMdd'T'HHmmss'Z',例如 20261022T131900Z;与平台时间偏差不能超过 300 秒。
默认值:-原始请求体的 SHA-256 小写十六进制。
默认值:-火山 V4 HMAC-SHA256 签名。
默认值:-响应
临时令牌,30 分钟有效,用于查询认证结果。仅单资源时平铺,多资源时从 Sessions 中取。
默认值:-H5 认证链接,供终端用户打开完成认证。仅单资源时平铺,多资源时从 Sessions 中取。
默认值:-每个素材资源一条认证会话。
默认值:-会话 ID,与 BytedToken 同值。
默认值:-该资源的临时令牌,30 分钟有效。
默认值:-该资源的 H5 认证链接。
默认值:-该资源适用的模型列表。
默认值:-真人分组展示名回显,未传时为 null。
默认值:-认证链接失效时间(ISO-8601),过期后需重新调用 CreateVisualValidateSession。
默认值:-全部 H5 链接列表,顺序与 Sessions 一致。
默认值:-多资源时的取用方式
客户有多个素材资源时,Sessions 每个资源一条,必须分别打开各自的 H5Link 完成认证,BytedToken 与 H5Link 不能混用。
回调通知
配置 CallbackURL 后,认证结束时平台会以浏览器跳转(GET)的方式打开该地址,并在末尾追加以下查询参数:
| 参数 | 说明 |
|---|---|
bytedToken | 本次认证的临时令牌,可用于对账 |
status | authorized(认证通过,分组已建立)/ verifying(仍在核验中)/ failed(未通过或链接已失效) |
groupId | 认证通过时的真人分组 ID,其他状态不返回 |
message | verifying / failed 时的提示文案,按请求语言返回中文、英文或日文 |
- 是浏览器跳转(GET),不是服务端 POST,你只需要能展示结果页即可;如需保存结果,可在你的页面里再调一次查询接口。
- 你原有 URL 上的查询参数会被保留,通知参数追加在末尾。
status只是一次结果快照,建议收到后再调用一次查询真人认证结果确认最终状态。- 未配置
CallbackURL时不做跳转,认证结束后展示结果页,终端用户可回到系统查看。
ExpireAt 是链接失效的时间点。过期后需要重新调用本接口获取新链接,旧链接扫码会失败。
错误
| Code | 说明 |
|---|---|
400 | InvalidParameter:CallbackURL 格式非法 |
400 | InvalidRequest:未配置可用素材资源,请联系平台运营 |
401 | SignatureDoesNotMatch、InvalidTimestamp、XContentSha256Mismatch、MissingParameter.Authorization 等签名或时间相关错误 |
403 | AccessDenied 凭证被禁用或无权限;ExpiredToken 凭证已过期 |
429 | TooManyRequests 请求过于频繁 |