Seedance 真人人像认证与素材管理使用指南

1. 文档范围

本文仅说明如何通过 Open Move 的火山兼容 OpenAPI 完成以下操作：

创建真人人像 H5 认证会话。

引导用户完成活体认证并取得真人素材组 GroupId。

向真人素材组上传图片或视频。

查询素材的异步处理结果。

创建和查询普通 AIGC 素材组。

所有接口共用同一路径，通过 Action 区分：

https://{your-domain}/openapi/volcengine/?Action={Action}&Version=2024-01-01

接口支持 POST 和 GET。推荐使用 POST 并通过 JSON 请求体传参，本文示例均使用 POST。

CreateAssetGroup 创建的是普通 AIGC 素材组，不能创建真人素材组。真人素材组只能在用户完成 CreateVisualValidateSession 发起的活体认证后，由 GetVisualValidateResult 返回。

2. 六个 Action

Action	用途	真人素材流程
`CreateVisualValidateSession`	创建真人人像 H5 认证会话	必需
`GetVisualValidateResult`	查询认证结果并取得真人素材组 `GroupId`	必需
`CreateAssetGroup`	创建普通 AIGC 素材组	非必需，不能代替真人认证
`GetAssetGroup`	查询或验证素材组	可选
`CreateAsset`	向指定素材组上传素材	必需
`GetAsset`	查询素材处理状态和详情	必需

只允许以上六个 Action，其他 Action 会被拒绝。

3. 完整业务流程

3.1 真人素材库

CreateVisualValidateSession
        │
        ├── BytedToken
        └── H5Link
                │
                ▼
        用户打开 H5Link
        完成真人活体认证
                │
                ▼
GetVisualValidateResult
        │
        └── GroupId（LivenessFace 真人素材组）
                │
                ├── GetAssetGroup（可选验证）
                │
                ▼
CreateAsset
        │
        └── Id（素材 ID）
                │
                ▼
GetAsset（轮询）
        │
        ├── Active：素材可用
        └── Failed：处理失败

3.2 普通 AIGC 素材组

CreateAssetGroup
        │
        └── Id（AIGC GroupId）
                │
                ├── GetAssetGroup（可选验证）
                │
                ▼
CreateAsset
        │
        └── Id（素材 ID）
                │
                ▼
GetAsset（轮询）

普通素材也可以在调用 CreateAsset 时不传 GroupId，由 Open Move 自动创建或复用普通 AIGC 素材组。上传真人素材时必须显式传入真人认证返回的 GroupId。

4. 前置条件

已在 Open Move 创建可调用素材 OpenAPI 的令牌。

令牌已生成 Access Key ID 和 Secret Access Key。

5. V4 签名与通用格式

5.1 请求头

所有请求使用火山 V4 签名认证：

Header	说明
`Authorization`	`HMAC-SHA256 Credential={AccessKeyId}/{date}/{region}/ark/request, SignedHeaders=host;x-content-sha256;x-date, Signature={signature}`
`X-Date`	UTC 时间，格式为 `yyyyMMddTHHmmssZ`，允许误差 ±15 分钟
`X-Content-Sha256`	实际请求体的 SHA256 哈希
`Host`	Open Move 服务域名
`Content-Type`	推荐使用 `application/json`

V4 签名中的固定值：

Region:  cn-beijing
Service: ark
Version: 2024-01-01

签名必须基于实际发送的请求方法、路径、查询字符串、请求头和请求体计算。请求体计算签名后不能再次序列化或修改。

5.2 成功响应

{
  "ResponseMetadata": {
    "RequestId": "string",
    "Action": "string",
    "Version": "2024-01-01",
    "Service": "ark",
    "Region": "cn-beijing"
  },
  "Result": {}
}

5.3 错误响应

{
  "ResponseMetadata": {
    "RequestId": "string",
    "Action": "string",
    "Version": "2024-01-01",
    "Service": "ark",
    "Region": "cn-beijing",
    "Error": {
      "Code": "InvalidParameter",
      "Message": "CallbackURL is required"
    }
  }
}

调用方应同时检查 HTTP 状态码和 ResponseMetadata.Error，不能仅判断是否存在 Result。

6. CreateVisualValidateSession

创建真人人像 H5 活体认证会话。

请求

{
  "CallbackURL": "https://your-app.com/face-verify/callback?order_id=order-1001"
}

参数	类型	必填	说明
`CallbackURL`	string	是	用户完成 H5 认证后，Open Move 最终将浏览器重定向到的客户地址

CallbackURL 必须是调用方自己的回调落地页。不要填写 Open Move 的内部认证回调地址。

响应

{
  "ResponseMetadata": {
    "RequestId": "20260718150513F42FF1D7034AFA2FEC89",
    "Action": "CreateVisualValidateSession",
    "Version": "2024-01-01",
    "Service": "ark",
    "Region": "cn-beijing"
  },
  "Result": {
    "BytedToken": "cv-token-20260718150513-abc123def456",
    "H5Link": "https://visual.volcengineapi.com/verify?token=cv-token-20260718150513-abc123def456",
    "CallbackURL": "https://your-app.com/face-verify/callback?order_id=order-1001"
  }
}

字段	说明
`BytedToken`	认证会话令牌，后续调用 `GetVisualValidateResult` 时使用
`H5Link`	用户完成真人活体认证的 H5 页面
`CallbackURL`	回显请求中的客户回调地址

调用方必须保存 BytedToken，并将 H5Link 提供给当前需要认证的用户。

回调行为

用户完成 H5 操作后，请求会先到达 Open Move。Open Move 处理认证结果后，再以 HTTP 302 重定向到客户传入的 CallbackURL。

客户回调地址原有查询参数会保留。回调通常包含：

参数	说明
`bytedToken`	当前认证会话令牌
`resultCode`	上游认证结果码，成功通常为 `10000`
`groupId`	认证成功时返回的真人素材组 ID

调用方应忽略不认识的查询参数。浏览器跳转可能因用户关闭页面或网络中断而未到达，因此最终状态应以 GetVisualValidateResult 的查询结果为准。

认证会话有效期为 30 分钟。超时后需要重新创建会话。

7. GetVisualValidateResult

根据 BytedToken 查询真人认证结果。认证成功后返回的 GroupId 是 LivenessFace 真人素材组 ID。

请求

{
  "BytedToken": "cv-token-20260718150513-abc123def456"
}

参数	类型	必填	说明
`BytedToken`	string	是	`CreateVisualValidateSession` 返回的令牌

认证成功响应

{
  "ResponseMetadata": {
    "RequestId": "20260718151000F42FF1D7034AFA2FEC90",
    "Action": "GetVisualValidateResult",
    "Version": "2024-01-01",
    "Service": "ark",
    "Region": "cn-beijing"
  },
  "Result": {
    "GroupId": "group-20260718150513-livenessface-xyz"
  }
}

字段	说明
`GroupId`	认证成功后创建的真人素材组 ID

轮询建议

间隔：3～5 秒。

最长等待：30 分钟。

返回非空 GroupId：认证成功，停止轮询。

ResponseMetadata.Error.Code 为 ValidatePending：认证尚未完成，等待后继续轮询。

其他 ResponseMetadata.Error：停止当前轮询或根据错误类型退避重试。

同一调用方名下如果出现重复 BytedToken，仅凭 token 无法确定唯一会话，接口会返回歧义错误，不会任意选择其中一条记录。

8. CreateAssetGroup

创建普通 AIGC 素材组。

此 Action 不能创建真人 LivenessFace 素材组，也不是上传真人素材的前置步骤。

请求

{
  "Name": "我的普通素材组",
  "Description": "用于普通 AIGC 素材",
  "GroupType": "AIGC"
}

参数	类型	必填	说明
`Name`	string	是	素材组名称
`Description`	string	否	素材组描述
`GroupType`	string	否	普通素材组使用 `AIGC`

响应

{
  "ResponseMetadata": {
    "RequestId": "20260718151200C01F49B47C0559E2122A",
    "Action": "CreateAssetGroup",
    "Version": "2024-01-01",
    "Service": "ark",
    "Region": "cn-beijing"
  },
  "Result": {
    "Id": "group-20260718151200-8phsh"
  }
}

Result.Id 是新建的普通素材组 ID。

9. GetAssetGroup

查询素材组详情。既可以查询 CreateAssetGroup 创建的普通素材组，也可以用于验证真人认证返回的 GroupId。

请求

{
  "Id": "group-20260718150513-livenessface-xyz"
}

参数	类型	必填	说明
`Id`	string	是	需要查询的素材组 ID

响应

{
  "ResponseMetadata": {
    "RequestId": "20260718151300A87E25BAEF8D44CF80D0",
    "Action": "GetAssetGroup",
    "Version": "2024-01-01",
    "Service": "ark",
    "Region": "cn-beijing"
  },
  "Result": {
    "Id": "group-20260718150513-livenessface-xyz",
    "Name": "真人素材组",
    "GroupType": "LivenessFace",
    "ProjectName": "Seedance默认",
    "CreateTime": "2026-07-18T07:10:00Z",
    "UpdateTime": "2026-07-18T07:10:00Z"
  }
}

10. CreateAsset

向素材组提交图片、视频或音频素材。该操作是异步的，返回素材 ID 后需要调用 GetAsset 查询处理结果。

上传真人素材

GroupId 必须使用 GetVisualValidateResult 返回的真人素材组 ID：

{
  "GroupId": "group-20260718150513-livenessface-xyz",
  "URL": "https://example.com/real-person-photo.jpg",
  "AssetType": "Image",
  "Name": "真人正面照片"
}

参数	类型	必填	说明
`GroupId`	string	真人素材必填	目标素材组 ID；真人素材必须传认证返回的 `GroupId`
`URL`	string	是	上游能够通过公网访问的素材 URL，推荐 HTTPS
`AssetType`	string	是	`Image`、`Video` 或 `Audio`
`Name`	string	否	素材名称

如果上传普通素材，可以传入 CreateAssetGroup 返回的 ID；也可以不传 GroupId，让 Open Move 自动创建或复用普通 AIGC 素材组。

素材的尺寸、格式、时长和 URL 可访问性最终以上游校验规则为准。

响应

{
  "ResponseMetadata": {
    "RequestId": "20260718151500BD40EA153193D54EB921",
    "Action": "CreateAsset",
    "Version": "2024-01-01",
    "Service": "ark",
    "Region": "cn-beijing"
  },
  "Result": {
    "Id": "asset-20260718151500-x8qmn"
  }
}

Result.Id 是新建的素材 ID。

11. GetAsset

查询素材详情和异步处理状态。

请求

{
  "Id": "asset-20260718151500-x8qmn"
}

参数	类型	必填	说明
`Id`	string	是	`CreateAsset` 返回的素材 ID

响应

{
  "ResponseMetadata": {
    "RequestId": "20260718151510BABDF5EA3CCE767701A7",
    "Action": "GetAsset",
    "Version": "2024-01-01",
    "Service": "ark",
    "Region": "cn-beijing"
  },
  "Result": {
    "Id": "asset-20260718151500-x8qmn",
    "Name": "真人正面照片",
    "GroupId": "group-20260718150513-livenessface-xyz",
    "AssetType": "Image",
    "Status": "Active",
    "URL": "https://ark-media-asset.tos-cn-beijing.volces.com/...",
    "ProjectName": "Seedance默认"
  }
}

常见状态：

Status	处理方式
`Processing`	继续轮询
`Active`	素材处理完成，可以使用
`Failed`	素材处理失败，停止轮询并检查素材要求

建议每 5 秒查询一次。临时预览 URL 的有效期以上游返回结果为准；过期后可重新调用 GetAsset 获取新地址。

12. 完整 Python 示例

以下示例展示真人认证、结果轮询、素材组验证、素材上传和素材轮询。示例末尾还提供了普通 AIGC 素材组的创建方式，因此覆盖全部六个 Action。

13. 常见问题

`CreateAssetGroup` 能否创建真人素材组？

不能。它只能创建普通 AIGC 素材组。真人素材组必须由用户完成 H5 活体认证后获得。

上传真人素材时可以不传 `GroupId` 吗？

不可以。上传真人素材必须显式传入 GetVisualValidateResult 返回的真人 GroupId。不传 GroupId 时，Open Move 只会自动创建或复用普通 AIGC 素材组。

是否必须等待客户 `CallbackURL` 收到跳转后再查询？

不必。打开 H5 页面后即可按 3～5 秒间隔调用 GetVisualValidateResult。客户回调适合改善用户体验，轮询接口用于确认最终结果。

是否可以只依赖客户回调中的 `groupId`？

不建议。用户可能关闭页面，浏览器跳转也可能因网络问题未完成。应使用 GetVisualValidateResult 确认最终结果。

如何判断素材已经可以用于视频生成？

持续调用 GetAsset，直到 Status 为 Active。Processing 表示仍在处理，Failed 表示处理失败。

Seedance 真人人像认证与素材管理使用指南

1. 文档范围#

2. 六个 Action#

3. 完整业务流程#

3.1 真人素材库#

3.2 普通 AIGC 素材组#

4. 前置条件#

5. V4 签名与通用格式#

5.1 请求头#

5.2 成功响应#

5.3 错误响应#

6. CreateVisualValidateSession#

请求#

响应#

回调行为#

7. GetVisualValidateResult#

请求#

认证成功响应#

轮询建议#

8. CreateAssetGroup#

请求#

响应#

9. GetAssetGroup#

请求#

响应#

10. CreateAsset#

上传真人素材#

响应#

11. GetAsset#

请求#

响应#

12. 完整 Python 示例#

13. 常见问题#

CreateAssetGroup 能否创建真人素材组？#

上传真人素材时可以不传 GroupId 吗？#

是否必须等待客户 CallbackURL 收到跳转后再查询？#

是否可以只依赖客户回调中的 groupId？#

如何判断素材已经可以用于视频生成？#