Seedance 素材库用户使用说明

本文介绍如何通过火山方舟兼容接口管理 Seedance 素材，并在火山兼容的视频任务接口中引用已审核素材。素材库管理统一使用 /volcengine/ark Action 接口；视频生成使用 /api/v3/contents/generations/tasks 接口。

使用前准备

请先确认：

已在控制台“素材库 > API 凭证”创建系统 API 凭证，并保存 AccessKey 和 SecretKey。SecretKey 只在创建或重置时显示一次。

已开通可用的 Seedance 视频模型。

上传的素材 URL 和真人认证回调地址均可被平台服务端公网访问。

系统签发的 AccessKey/SecretKey 仅用于本系统的素材库兼容接口，不能填写火山云账号的真实 AK/SK，也不能用于火山云官方域名。

接口与鉴权

素材库接口

所有素材库 Action 都调用固定入口：

签名覆盖 HTTP 方法、固定路径 /volcengine/ark、排序后的查询参数、已签名请求头和原始 JSON 请求体。签名时使用的请求体、路径、查询参数和请求头必须与实际发送内容完全一致。服务端允许请求时间与服务器时间相差最多 15 分钟。

视频任务接口

创建和查询视频任务使用用户令牌：

素材库接口的系统 AK/SK 与视频任务接口的用户令牌用途不同，请分别保存和使用。

使用流程

1. 普通人脸以及非人像图片、视频、音频：CreateAssetGroup 创建 AIGC 素材组
   公众人物、演员、网红、主播等高辨识度或有商业使用风险的人脸：CreateVisualValidateSession 创建认证会话，扫码后取得 GroupId
2. CreateAsset 上传图片、视频或音频
3. 使用 GetAsset、ListAssets 轮询状态，直到 Status=Active
4. 在视频任务的 image_url.url、video_url.url 或 audio_url.url 中引用 asset://<Asset Id>
5. 任务完成后按需使用 GetAsset、ListAssets、DeleteAsset 或 DeleteAssetGroup 管理资源

普通人脸以及非人像图片、视频和音频使用普通 AIGC 素材组。公众人物、演员、网红、主播等具有较高辨识度或商业使用风险的人脸素材，应先确认授权并使用真人认证流程。

第一步：创建素材组

普通素材组

普通人脸以及非人像图片、视频和音频先调用 CreateAssetGroup，GroupType 只能填写 AIGC：

{
  "Name": "商品素材",
  "Description": "商品图片、视频和音频",
  "GroupType": "AIGC",
  "ProjectName": "default"
}

Name 必填，最长 64 个字符；Description 最长 300 个字符；未填写 ProjectName 时使用 default。响应 Result.Id 是后续 CreateAsset 的 GroupId。

真人认证素材组

公众人物、演员、网红、主播等具有较高辨识度或商业使用风险的人脸素材，先调用 CreateVisualValidateSession：

{
  "CallbackURL": "https://client.example.com/asset-callback",
  "Name": "本人授权素材",
  "Description": "用于短视频生成"
}

接口返回 BytedToken 和认证链接。本人打开链接或扫码完成认证后，系统以 303 跳转到 CallbackURL，并追加 bytedToken、resultCode；认证成功时还会追加 groupId。收到回调后，使用 GetVisualValidateResult 查询最终结果：

{
  "BytedToken": "<BytedToken>"
}

只有响应中的 GroupId 可用时，才能继续上传真人素材。认证必须由本人完成，素材内容应与认证本人一致。

第二步：上传素材

使用第一步返回的 GroupId 调用 CreateAsset：

{
  "GroupId": "<GroupId>",
  "URL": "https://example.com/material.jpg",
  "AssetType": "Image",
  "Name": "正面特写"
}

AssetType 支持 Image、Video、Audio。URL 必须能被平台服务端访问。接口返回的 Result.Id 是素材 ID，后续查询、更新、删除和视频请求中的 asset:// URI 都使用该本地 ID。

建议使用主体清晰、无遮挡、清晰度足够的素材，避免多人合照、严重遮挡和过度美颜。真人目录中的素材应与认证本人一致。

第三步：查询素材状态

创建后素材通常处于 Processing，需要轮询 GetAsset 或 ListAssets：

{
  "Id": "<Asset Id>"
}

素材状态含义：

状态	含义	是否可引用
`Processing`	处理中或审核中	否
`Active`	已通过并可用	是
`Failed`	处理失败、拒绝或需要重新认证/上传	否

只有 Status=Active 时，才能在视频任务中引用素材。ListAssetGroups 和 ListAssets 支持分页查询和筛选。

第四步：使用素材生成视频

素材状态为 Active 后，在火山兼容视频任务中引用 asset://<Asset Id>：

{
  "model": "doubao-seedance-2-0-260128",
  "content": [
    {
      "type": "text",
      "text": "图片1中的男孩露出自然微笑，镜头缓慢推进，背景为明亮的室内空间。"
    },
    {
      "type": "image_url",
      "image_url": {
        "url": "asset://<Asset Id>"
      },
      "role": "reference_image"
    }
  ],
  "ratio": "9:16",
  "resolution": "720p",
  "duration": 5,
  "generate_audio": true,
  "watermark": false
}

使用规则：

Prompt 中按素材出现顺序使用“图片1”“图片2”“视频1”等描述。

不要在 Prompt 文本中直接填写素材 ID。

多个素材同时使用时，确认它们属于当前用户且状态均为 Active。

可在 image_url.url、video_url.url 或 audio_url.url 中使用对应的 asset://<Asset Id>。

创建任务后，可使用 GET /api/v3/contents/generations/tasks/{task_id} 查询任务状态。

查询、更新和删除

支持的素材库 Action 包括：

ListAssetGroups：分页查询素材组。

ListAssets：分页查询素材。

GetAssetGroup、GetAsset：查询单个素材组或素材。

UpdateAssetGroup、UpdateAsset：更新素材组或素材名称。

DeleteAsset、DeleteAssetGroup：删除素材或素材组。

删除示例：

{
  "Id": "<Asset Id>"
}

删除素材组会同时删除组内素材；删除后对应的 asset:// URI 不能继续用于视频生成，操作不可恢复。

常见错误

HTTP 状态	错误码	处理建议
400	`InvalidAction`、`InvalidVersion`、`InvalidParameter`	检查 Action、Version 和请求字段
400	`UnsupportedCapability`	检查是否配置了可用的真人认证能力
401	`Unauthorized`	检查 AK/SK、签名、摘要、路径、查询参数和请求时间
403	`Forbidden`	检查凭证、用户状态和 IP 白名单
404	`ResourceNotFound`	确认资源属于当前凭证对应的用户
500	`InternalError`	稍后重试并保留 RequestId 供排查

完整字段、签名计算示例和响应结构见《火山官方素材库兼容接口使用说明》及 Apifox 的“视频（Videos）/Seedance素材库/火山方舟官方兼容接口”。

Seedance素材库用户使用说明

Seedance 素材库用户使用说明#

使用前准备#

接口与鉴权#

素材库接口#

视频任务接口#

使用流程#

第一步：创建素材组#

普通素材组#

真人认证素材组#

第二步：上传素材#

第三步：查询素材状态#

第四步：使用素材生成视频#

查询、更新和删除#

常见错误#