跳转到主要内容
POST
/
api
/
v1
/
client
/
job
/
visual-validate-session
创建真人 H5 认证会话
curl --request POST \
  --url https://api.crun.ai/api/v1/client/job/visual-validate-session \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "callback_url": "https://example.com/callback/seedance-visual-validation"
}
'
{
  "code": 200,
  "message": "success",
  "data": {
    "BytedToken": "202603311449168C23BA26**************",
    "H5Link": "https://visual.volcengine.com/validate?...&bytedToken=202603311449168C23BA26**************&lng=zh",
    "CallbackURL": "https://example.com/callback/seedance-visual-validation"
  }
}

​
概览

当您需要将真人肖像素材上传到 Seedance 私域素材组时，请使用此流程。真人认证会创建一个绑定单个真实人脸的 Asset Group ID。获取 GroupId 后，调用 Seedance 素材上传 API 并传入 group_id ，即可把该真人对应的图片、视频或音频素材上传到同一个素材组。

​
流程

  1. 调用 POST /api/v1/client/job/visual-validate-session，传入您的 callback_url。
  2. 将返回的 H5Link 打开给终端用户，让用户完成真人人脸验证。
  3. 验证结束后，H5 页面会跳转到您的 callback_url，并在 URL 参数中携带 bytedToken、resultCode 等验证结果。
  4. 当 resultCode 为 10000 时，调用 GET /api/v1/client/job/visual-validate-result，传入 byted_token 获取 GroupId。
  5. 调用 Seedance 素材上传 API，将返回的 GroupId 作为 group_id 传入。之后的上传流程与普通素材上传一致。
  6. 通过 Seedance 素材信息 API 轮询素材状态，直到 Status 变为 Active，再在 Seedance 生成请求中使用返回的 AssetId。
H5 真人认证链接有效期为 120 秒。如果验证失败或链接过期，需要重新创建认证会话。
可通过在 H5Link 后缀追加或修改 lng 参数指定页面语言。目前支持简体中文 zh、英文 en 和繁体中文 zh-Hant，默认值为 zh。

​
步骤 1：创建认证会话

调用此接口创建火山 H5 真人认证链接。

​
请求体

​
callback_url
string
必填
终端用户完成 H5 认证页面后打开的回调 URL。验证结果参数会追加到该回调地址后。

​
请求示例

{
  "callback_url": "https://example.com/callback/seedance-visual-validation"
}

​
响应示例

{
  "code": 200,
  "message": "success",
  "data": {
    "BytedToken": "202603311449168C23BA26**************",
    "H5Link": "https://visual.volcengine.com/validate?...&bytedToken=202603311449168C23BA26**************&lng=zh",
    "CallbackURL": "https://example.com/callback/seedance-visual-validation"
  }
}

​
回调参数

用户完成验证后，H5 页面会跳转到您的回调地址。成功验证的回调通常如下： 
https://example.com/callback/seedance-visual-validation?bytedToken=********&resultCode=10000&algorithmBaseRespCode=0&reqMeasureInfoValue=1&verify_type=real_time
参数说明
bytedToken本次认证的唯一凭证。查询认证结果时作为 byted_token 传入。
resultCode认证结果。10000 表示认证通过。
algorithmBaseRespCode服务端子错误码。建议在 resultCode 表示服务端错误时检查该字段。
verify_type认证类型，当前固定为 real_time。

​
步骤 2：获取认证结果

当回调显示认证通过后，调用此接口获取该真人对应的 GroupId。

​
查询参数

​
byted_token
string
必填
创建认证会话接口返回的 BytedToken，或回调 URL 中收到的 bytedToken。

​
请求示例

curl -X GET "https://api.crun.ai/api/v1/client/job/visual-validate-result?byted_token=202603311449168C23BA26**************" \
  -H "X-API-KEY: YOUR_API_KEY"

​
响应示例

{
  "code": 200,
  "message": "success",
  "data": {
    "GroupId": "group-20260331145705-*****"
  }
}

​
步骤 3：上传素材到素材组

上传素材时，将返回的 GroupId 作为 group_id 传入： 
{
  "name": "fashion-model-front",
  "asset_type": "Image",
  "asset_url": "https://example.com/assets/fashion-model-front.jpg",
  "group_id": "group-20260331145705-*****"
}
每个真人 Asset Group 唯一绑定一个真实人脸。素材上传到该组时，上游服务会将上传素材中的人脸与真人认证采集的基准人脸进行一致性比对。如果不是同一人，或素材中检测到多个人脸，入库可能失败。

​
相关资源

素材上传

上传图片、视频和音频素材，也可传入 group_id 上传真人素材

素材信息

查询上传状态，并等待素材变为可用

授权

​
x-api-key
string
header
必填

所有接口均需通过 API Key 进行认证。

获取 API Key：

  1. 访问 API Key 管理页面 获取你的 API Key

使用方式： 在请求头中添加：

x-api-key: YOUR_API_KEY

注意事项：

  • 请妥善保管你的 API Key，不要泄露给他人
  • 如果怀疑 API Key 已泄露，请立即在管理页面中重置

请求体

application/json
​
callback_url
string<uri>
必填

终端用户完成 H5 认证后打开的回调 URL。验证结果参数会追加到该地址后，例如 bytedToken 和 resultCode。

示例:

"https://example.com/callback/seedance-visual-validation"

响应

认证会话创建成功

​
code
enum<integer>

响应状态码

  • 200：成功，请求已成功处理
  • 401：未授权，缺少认证信息或认证无效
  • 402：额度不足，账户额度不足以完成本次操作
  • 404：资源不存在，请求的资源或接口不存在
  • 422：参数校验错误，请求参数未通过校验
  • 429：请求过于频繁，已超出当前资源的调用限制
  • 455：服务不可用，系统当前正在维护中
  • 500：服务器错误，处理请求时发生了意外错误
  • 501：生成失败，内容生成任务执行失败
  • 505：功能已禁用，请求的功能当前不可用
可用选项:
200,
401,
402,
404,
422,
429,
455,
500,
501,
505
​
message
string

响应消息；失败时为错误说明

示例:

"success"

​
data
object