Seedance 素材库

Seedance 素材库接口文档：素材组管理、素材上传与查询、分页方式，以及在视频生成中通过素材 URI 引用素材。

素材库用于预先上传图片、视频或音频，并在 Seedance 视频生成请求中通过素材 URI（asset://<asset_id>）引用。上传为异步处理：先创建素材并取得素材 Id，再轮询素材状态，只有 Status 为 Active 的素材才能用于生成。

本接口与火山引擎方舟素材库（Assets）API 请求/响应格式完全兼容，可直接参考官方 SDK 的调用方式，区别仅在于：

鉴权：使用平台 API Key（Bearer Token），无需 AK/SK 签名
基础地址：https://token.aiznt.com
隔离方式：素材按 API Key 所属用户隔离，只能查询和使用当前用户上传的素材

接口一览

所有接口通过统一的 Action 形式调用：

POST https://token.aiznt.com/?Action=<接口名>&Version=2024-01-01
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

Action	说明
`CreateAssetGroup`	创建素材组
`ListAssetGroups`	查询素材组列表
`GetAssetGroup`	查询单个素材组
`UpdateAssetGroup`	更新素材组信息
`DeleteAssetGroup`	删除素材组
`CreateAsset`	上传素材
`ListAssets`	查询素材列表
`GetAsset`	查询单个素材
`UpdateAsset`	更新素材信息
`DeleteAsset`	删除素材

Version 固定为 2024-01-01。请求体为 JSON，响应统一包裹在 ResponseMetadata + Result 结构中（见响应与错误）。

资源结构

Asset Group（素材组）：素材的分组容器，可将同一人物或同一批素材放入同一素材组管理。上传素材前必须先创建素材组。
Asset（素材）：单个素材文件（图片、视频或音频），属于某个素材组，是可直接用于 Seedance 2.0 / 2.5 推理的资产。

ProjectName（项目名称）用于资源隔离，所有接口均可选填，默认为 default。同一素材的创建、查询、使用必须保持 ProjectName 一致，建议不填（统一使用 default）。

素材规格

类型	格式	大小	其他限制
图片（`Image`）	jpeg、png、webp、bmp、tiff、gif、heic、heif	小于 30 MB	宽高均为 300–6000 px（不含边界）；宽高比大于 0.4 且小于 2.5
视频（`Video`）	mp4、mov	不超过 200 MB	时长 2–30 秒；宽高 300–6000 px；宽高比 0.4–2.5；总像素数 407696–8295044；帧率 24–60 FPS
音频（`Audio`）	wav、mp3	不超过 15 MB	时长 2–30 秒

素材 URL 必须是服务端可公开访问的 HTTP/HTTPS 地址，下载上限 200 MB。每次请求上传一个素材文件。

素材组接口

创建素材组

Action=CreateAssetGroup

字段	类型	必填	说明
`Name`	string	是	素材组名称，最长 64 个字符
`Description`	string	否	素材组描述，最长 300 个字符
`GroupType`	string	否	`AIGC`（默认）或 `LivenessFace`，不区分大小写
`ProjectName`	string	否	项目名称，默认 `default`

curl -X POST "https://token.aiznt.com/?Action=CreateAssetGroup&Version=2024-01-01" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "Name": "figure_group_1",
    "Description": "虚拟人物素材组"
  }'

{
  "ResponseMetadata": {
    "RequestId": "20260915103000abcdef",
    "Action": "CreateAssetGroup",
    "Version": "2024-01-01",
    "Service": "ark",
    "Region": "cn-beijing"
  },
  "Result": {
    "Id": "group-20260915103000-a1b2c"
  }
}

查询素材组列表

Action=ListAssetGroups

字段	类型	必填	说明
`Filter`	object	是	筛选条件
`Filter.GroupType`	string	是	`AIGC` 或 `LivenessFace`
`Filter.Name`	string	否	按素材组名称模糊搜索，最长 64 个字符
`Filter.GroupIds`	array<string>	否	按素材组 ID 精确筛选
`SortBy`	string	否	`CreateTime`（默认）或 `UpdateTime`
`SortOrder`	string	否	`Desc`（默认）或 `Asc`
`ProjectName`	string	否	项目名称，默认 `default`
分页参数	—	否	`MaxResults` + `NextToken`，或 `PageNumber` + `PageSize`，见分页说明

curl -X POST "https://token.aiznt.com/?Action=ListAssetGroups&Version=2024-01-01" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "Filter": {"GroupType": "AIGC", "Name": "figure"},
    "MaxResults": 10,
    "SortBy": "CreateTime",
    "SortOrder": "Desc"
  }'

{
  "ResponseMetadata": {"RequestId": "...", "Action": "ListAssetGroups", "Version": "2024-01-01", "Service": "ark", "Region": "cn-beijing"},
  "Result": {
    "Items": [
      {
        "Id": "group-20260915103000-a1b2c",
        "Name": "figure_group_1",
        "Description": "虚拟人物素材组",
        "GroupType": "AIGC",
        "ProjectName": "default",
        "CreateTime": "2026-09-15T10:30:00Z",
        "UpdateTime": "2026-09-15T10:30:00Z"
      }
    ],
    "NextToken": "eyJWZXJzaW9uIjox..."
  }
}

返回 NextToken 表示还有更多结果，将其原样传入下一次请求即可翻页。

查询单个素材组

Action=GetAssetGroup

字段	类型	必填	说明
`Id`	string	是	素材组 ID
`ProjectName`	string	否	项目名称，默认 `default`

Result 返回单个素材组对象，字段同上。

更新素材组

Action=UpdateAssetGroup

字段	类型	必填	说明
`Id`	string	是	素材组 ID
`Name`	string	否	新名称，不能为空，最长 64 个字符
`Description`	string	否	新描述，最长 300 个字符
`ProjectName`	string	否	项目名称，默认 `default`

仅更新传入的字段。成功时 Result 返回 {"Id": "<素材组 ID>"}。

删除素材组

Action=DeleteAssetGroup

字段	类型	必填	说明
`Id`	string	是	素材组 ID
`ProjectName`	string	否	项目名称，默认 `default`

成功时 Result 为空对象。删除后组内素材不再可用，且操作不可恢复，请谨慎调用。

素材接口

上传素材

Action=CreateAsset

上传为异步接口，系统处理可能排队，不承诺上传时间 SLA；视频素材处理耗时更长。返回素材 ID 仅表示任务已创建，需轮询 GetAsset 确认 Status 变为 Active 后才可用于生成。

字段	类型	必填	说明
`GroupId`	string	是	素材组 ID，需先调用 `CreateAssetGroup` 创建
`URL`	string	是	可公开访问的 HTTP/HTTPS 素材地址
`AssetType`	string	是	`Image`、`Video` 或 `Audio`，不区分大小写
`Name`	string	是	素材名称，最长 64 个字符；仅用于列表检索，不会带入模型推理
`ProjectName`	string	否	项目名称，默认 `default`，需与素材组所在项目一致

curl -X POST "https://token.aiznt.com/?Action=CreateAsset&Version=2024-01-01" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "GroupId": "group-20260915103000-a1b2c",
    "URL": "https://example.com/reference.png",
    "AssetType": "Image",
    "Name": "角色参考图"
  }'

{
  "ResponseMetadata": {"RequestId": "...", "Action": "CreateAsset", "Version": "2024-01-01", "Service": "ark", "Region": "cn-beijing"},
  "Result": {
    "Id": "asset-20260915103100-d3e4f"
  }
}

查询单个素材

Action=GetAsset

字段	类型	必填	说明
`Id`	string	是	素材 ID（裸 ID，不带 `asset://` 前缀）
`ProjectName`	string	否	项目名称，默认 `default`

curl -X POST "https://token.aiznt.com/?Action=GetAsset&Version=2024-01-01" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"Id": "asset-20260915103100-d3e4f"}'

{
  "ResponseMetadata": {"RequestId": "...", "Action": "GetAsset", "Version": "2024-01-01", "Service": "ark", "Region": "cn-beijing"},
  "Result": {
    "Id": "asset-20260915103100-d3e4f",
    "Name": "角色参考图",
    "GroupId": "group-20260915103000-a1b2c",
    "ProjectName": "default",
    "AssetType": "Image",
    "Status": "Active",
    "Moderation": {"Strategy": "Default"},
    "URL": "https://example.com/reference.png",
    "CreateTime": "2026-09-15T10:31:00Z",
    "UpdateTime": "2026-09-15T10:31:04Z",
    "LastInferenceTime": "2026-09-15T11:02:00Z"
  }
}

素材对象字段：

字段	类型	说明
`Id`	string	素材 ID
`Name`	string	素材名称
`GroupId`	string	所属素材组 ID
`ProjectName`	string	所属项目名称
`AssetType`	string	`Image`、`Video` 或 `Audio`
`Status`	string	`Processing`：处理中；`Active`：可用于生成；`Failed`：处理失败
`Moderation.Strategy`	string	审核策略，当前为 `Default`
`URL`	string	上传时提供的原始素材地址
`CreateTime` / `UpdateTime`	string	创建/更新时间，UTC RFC 3339 格式
`LastInferenceTime`	string	最近一次用于提交视频生成任务的时间，仅使用后返回
`Error.Code` / `Error.Message`	string	处理失败时的错误码与说明，仅失败时返回

查询素材列表

Action=ListAssets

字段	类型	必填	说明
`Filter`	object	是	筛选条件
`Filter.GroupType`	string	是	`AIGC` 或 `LivenessFace`
`Filter.GroupIds`	array<string>	否	按素材组 ID 精确筛选
`Filter.Name`	string	否	按素材名称模糊搜索，最长 64 个字符
`Filter.Statuses`	array<string>	否	按状态筛选：`Active`、`Processing`、`Failed`
`SortBy`	string	否	`CreateTime`（默认）、`UpdateTime` 或 `GroupId`
`SortOrder`	string	否	`Desc`（默认）或 `Asc`
`ProjectName`	string	否	项目名称，默认 `default`
分页参数	—	否	`MaxResults` + `NextToken`，或 `PageNumber` + `PageSize`，见分页说明

curl -X POST "https://token.aiznt.com/?Action=ListAssets&Version=2024-01-01" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "Filter": {
      "GroupType": "AIGC",
      "GroupIds": ["group-20260915103000-a1b2c"],
      "Statuses": ["Active"]
    },
    "MaxResults": 20,
    "SortBy": "CreateTime",
    "SortOrder": "Desc"
  }'

Result.Items 为素材对象数组（字段同 GetAsset），Result.NextToken 用于翻页。

更新素材

Action=UpdateAsset

字段	类型	必填	说明
`Id`	string	是	素材 ID
`Name`	string	否	新名称，最长 64 个字符
`ProjectName`	string	否	项目名称，默认 `default`

成功时 Result 返回 {"Id": "<素材 ID>"}。

删除素材

Action=DeleteAsset

字段	类型	必填	说明
`Id`	string	是	素材 ID
`ProjectName`	string	否	项目名称，默认 `default`

成功时 Result 为空对象。删除不可恢复；建议定期通过 GetAsset 或 ListAssets 查看 LastInferenceTime，主动删除不再使用的素材。

分页说明

ListAssets 与 ListAssetGroups 支持两种分页方式，不能混用：

方式	参数	说明
Token 分页（默认）	`MaxResults` + `NextToken`	`MaxResults` 每页数量，1–100，默认 10；响应中的 `NextToken` 原样传入下一页请求
页码分页	`PageNumber` + `PageSize`	必须同时提供；`PageNumber` 从 1 开始，`PageSize` 1–100，且 `PageNumber × PageSize` 不超过 10000

页码分页的响应额外返回 PageNumber、PageSize 和 TotalCount（符合条件总数）；Token 分页仅在还有更多结果时返回 NextToken。

NextToken 与筛选条件、排序方式绑定，翻页时请保持其他参数不变，否则 Token 校验会失败。

使用素材生成视频

在视频生成接口的 content 中，将素材 ID 拼成 asset://<asset_id> 放入对应模态的 image_url.url、video_url.url 或 audio_url.url 字段。普通 HTTP/HTTPS URL 仍可照常混用。

{
  "model": "doubao-seedance-2-0-260128",
  "content": [
    {
      "type": "text",
      "text": "图片1里的女孩身着图片2中的服装，正在整理柜台上的物品，以音频1作为背景音乐。"
    },
    {
      "type": "image_url",
      "role": "reference_image",
      "image_url": {"url": "asset://asset-20260915103100-d3e4f"}
    },
    {
      "type": "image_url",
      "role": "reference_image",
      "image_url": {"url": "asset://asset-20260915103200-f5a6b"}
    },
    {
      "type": "audio_url",
      "role": "reference_audio",
      "audio_url": {"url": "asset://asset-20260915103300-c7d8e"}
    }
  ],
  "generate_audio": true,
  "ratio": "16:9",
  "duration": 11
}

注意事项：

平台会在调用上游模型前，将当前用户已激活的素材 URI 解析为实际素材地址。素材不存在、不属于当前用户、尚未处理成功（非 Active）或素材类型与模态不匹配时，请求会失败。
提示词中请使用“图片1”“视频1”“音频1”指代素材，序号按请求体中同类型素材的出现顺序从 1 开始；不要在提示词中直接写素材 ID。
素材 URI 必须带 asset:// 前缀，不能直接传裸素材 ID。

简易查询接口

除 Action 形式外，平台还提供以下 REST 别名，便于快速查询：

方法	路径	说明
POST	`/api/assets/upload`	等同于 `CreateAsset`（参数与响应格式相同）
GET	`/api/assets/{asset_id}`	查询单个素材，直接返回素材对象（无 `ResponseMetadata` 包裹）
GET	`/api/assets`	查询素材列表，支持 `name`、`status`、`limit`（默认 20，最大 100）、`offset` 查询参数

curl "https://token.aiznt.com/api/assets?status=Active&limit=20&offset=0" \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "items": [
    {
      "Id": "asset-20260915103100-d3e4f",
      "Name": "角色参考图",
      "GroupId": "group-20260915103000-a1b2c",
      "ProjectName": "default",
      "AssetType": "Image",
      "Status": "Active",
      "Moderation": {"Strategy": "Default"},
      "URL": "https://example.com/reference.png",
      "CreateTime": "2026-09-15T10:31:00Z",
      "UpdateTime": "2026-09-15T10:31:04Z"
    }
  ],
  "data": ["同上"],
  "total": 1
}

items 与 data 内容相同，读取任意一个即可；total 为符合筛选条件的素材总数，列表按创建时间倒序排列。

响应与错误

所有 Action 接口的响应统一为以下结构：

{
  "ResponseMetadata": {
    "RequestId": "请求 ID",
    "Action": "接口名",
    "Version": "2024-01-01",
    "Service": "ark",
    "Region": "cn-beijing",
    "Error": {"Code": "错误码", "Message": "错误说明"}
  },
  "Result": {}
}

成功时无 Error 字段，Result 携带业务数据；失败时 HTTP 状态码为非 200，Result 缺省，Error 描述错误。常见错误码：

错误码	HTTP 状态码	说明
`MissingParameter.*`	400	缺少必填参数，如 `MissingParameter.GroupId`
`InvalidParameter.*`	400	参数非法，如 `InvalidParameter.Version`、`InvalidParameter.AssetType`
`InvalidAction`	400	不支持的 Action
`InvalidRequest`	400	请求体不是合法 JSON
`ResourceNotFound`	404	素材或素材组不存在
`InternalError`	500	服务内部错误

素材异步处理失败时，GetAsset 返回的 Status 为 Failed，Error.Code 常见取值：AssetURLUnavailable（素材地址无法下载）、AssetTooLarge（超过 200 MB 下载上限）、InvalidAsset（不符合素材规格）、AssetTypeMismatch（AssetType 与实际文件类型不符）。

常见问题

素材上传成功后，为什么无法用于生成视频？

素材处理是异步的，需轮询 GetAsset 确认 Status 为 Active。若创建和查询时传入了不同的 ProjectName，也会查询不到素材；不填时默认为 default，建议统一不填。

提示词中如何指代素材？

使用“素材类型 + 序号”格式，如“图片1”“视频1”“音频1”，序号为该素材在请求体中同类素材里的顺序（从 1 开始）。不要在提示词中直接使用素材 ID。

素材有容量或限流限制吗？

素材按 API Key 所属用户隔离和管理。接口调用遵循平台全局限流策略，超出限制会返回限流错误，请控制调用频率并做好重试。

Seedance 素材库

本页目录