跳到主要内容

发起真人认证

POST/xmind-cloud-platform/openapi/volcengine?Action=CreateVisualValidateSession&Version=2024-01-01

发起真人认证,返回 H5 认证链接。终端用户完成认证后建立真人分组,之后即可上传真人素材。

请求参数​

Action 与 Version 通过查询参数传递,其余参数放在 JSON 请求体中。

CallbackURLstring可选

你自己的结果通知地址,需公网可访问,仅支持 HTTP/HTTPS。不传时认证结束停留在平台结果页,不影响分组建立。

默认值:-
GroupNamestring可选

真人分组展示名。不传时默认使用分组 ID。

默认值:-
CallbackURL 只影响通知,不影响认证与建组

配置 CallbackURL 只决定你能否收到主动通知,不影响认证与分组建立。不传时认证结束后照样建组,只是收不到通知,需要自行轮询查询真人认证结果。

认证​

所有接口使用同一套火山 V4 签名,凭证与签名方式见火山方舟素材库 API 概览。以下请求头为通用要求:

Content-Typestring必填

固定为 application/json。

默认值:application/json
Hoststring必填

实际访问的域名和端口;包含端口时必须写入签名。

默认值:-
X-Datestring必填

UTC 时间,格式 yyyyMMdd'T'HHmmss'Z',例如 20261022T131900Z;与平台时间偏差不能超过 300 秒。

默认值:-
X-Content-Sha256string必填

原始请求体的 SHA-256 小写十六进制。

默认值:-
Authorizationstring必填

火山 V4 HMAC-SHA256 签名。

默认值:-

响应​

Result.BytedTokenstring可选

临时令牌,30 分钟有效,用于查询认证结果。仅单资源时平铺,多资源时从 Sessions 中取。

默认值:-
Result.H5Linkstring可选

H5 认证链接,供终端用户打开完成认证。仅单资源时平铺,多资源时从 Sessions 中取。

默认值:-
Result.Sessionsarray<object>可选

每个素材资源一条认证会话。

默认值:-
Result.Sessions[].Idstring可选

会话 ID,与 BytedToken 同值。

默认值:-
Result.Sessions[].BytedTokenstring可选

该资源的临时令牌,30 分钟有效。

默认值:-
Result.Sessions[].H5Linkstring可选

该资源的 H5 认证链接。

默认值:-
Result.Sessions[].ModelIdsarray<string>可选

该资源适用的模型列表。

默认值:-
Result.Sessions[].GroupNamestring可选

真人分组展示名回显,未传时为 null。

默认值:-
Result.Sessions[].ExpireAtstring可选

认证链接失效时间(ISO-8601),过期后需重新调用 CreateVisualValidateSession。

默认值:-
Result.H5Linksarray<string>可选

全部 H5 链接列表,顺序与 Sessions 一致。

默认值:-

多资源时的取用方式​

客户有多个素材资源时,Sessions 每个资源一条,必须分别打开各自的 H5Link 完成认证,BytedToken 与 H5Link 不能混用。

回调通知​

配置 CallbackURL 后,认证结束时平台会以浏览器跳转(GET)的方式打开该地址,并在末尾追加以下查询参数:

参数说明
bytedToken本次认证的临时令牌,可用于对账
statusauthorized(认证通过,分组已建立)/ verifying(仍在核验中)/ failed(未通过或链接已失效)
groupId认证通过时的真人分组 ID,其他状态不返回
messageverifying / failed 时的提示文案,按请求语言返回中文、英文或日文
  • 是浏览器跳转(GET),不是服务端 POST,你只需要能展示结果页即可;如需保存结果,可在你的页面里再调一次查询接口。
  • 你原有 URL 上的查询参数会被保留,通知参数追加在末尾。
  • status 只是一次结果快照,建议收到后再调用一次查询真人认证结果确认最终状态。
  • 未配置 CallbackURL 时不做跳转,认证结束后展示结果页,终端用户可回到系统查看。
认证链接 30 分钟内有效

ExpireAt 是链接失效的时间点。过期后需要重新调用本接口获取新链接,旧链接扫码会失败。

错误​

Code说明
400InvalidParameter:CallbackURL 格式非法
400InvalidRequest:未配置可用素材资源,请联系平台运营
401SignatureDoesNotMatch、InvalidTimestamp、XContentSha256Mismatch、MissingParameter.Authorization 等签名或时间相关错误
403AccessDenied 凭证被禁用或无权限;ExpiredToken 凭证已过期
429TooManyRequests 请求过于频繁

相关​