Seedance 素材库

Seedance 官方一致接入配套独立的素材库体系，素材按客户隔离：每个客户只能创建/查看/更新/删除自己的素材组与素材。通过统一素材入口调用（与火山官方管控面调用形态一致），本页全部素材 Action 均可用。视频生成任务接口见 Seedance 官方一致接入（生成视频）。

鉴权

本页所有接口均支持两种鉴权方式，任选其一：

• Bearer（默认）：Authorization: Bearer $YOUR_API_KEY，与任务接口同一个平台令牌；

端点

• 素材 / 真人认证 RPC（统一入口，推荐）：POST $URL/?Action=<Action>&Version=2024-01-01 —— 与火山官方管控面调用形态一致（Action 打在域名根路径），按令牌分组自动路由线路

素材组

RPC 请求可携带可选的 ProjectName 字段（透传上游，须符合账号权限；不传使用默认项目）。

Action	参数
CreateAssetGroup	Name（≤64 字符）、Description（≤300 字符）、GroupType（AIGC；LivenessFace 组由真人认证产生）
GetAssetGroup	Id*
ListAssetGroups	见下方「列表参数」
UpdateAssetGroup	Id*、Name、Description
DeleteAssetGroup	Id*

素材

Action	参数
CreateAsset	GroupId（本人素材组 ID）、URL（公网可达）、AssetType*（Image / Video / Audio）、Name（≤64 字符，仅用于列表搜索）、Moderation（审核设置）
GetAsset	Id*
ListAssets	见下方「列表参数」（Filter 另支持 Statuses：Processing / Active / Failed）
UpdateAsset	Id、Name
DeleteAsset	Id*

CreateAsset 为异步处理：返回 Id 后轮询 GetAsset，Status=Active 才可用于任务引用。GetAsset / ListAssets 返回的字段包括 Id、Name、URL（引用地址，约 12 小时有效）、AssetType、GroupId、Status、Error（Code / Message）、CreateTime、UpdateTime。

列表参数（ListAssetGroups / ListAssets）

Filter 必填（可为 {}），支持 GroupIds（按组过滤）、GroupType（AIGC / LivenessFace）、Name（模糊搜索）。

分页两种方式任选其一：

• 页码式：PageNumber（从 1 起）+ PageSize（1–100），响应含 TotalCount；
• 游标式：MaxResults（1–100），后续请求携带上次返回的 NextToken 保持相同查询条件续页；响应中不再返回 NextToken 即表示遍历结束。

排序：SortBy（CreateTime / UpdateTime，默认 CreateTime）、SortOrder（Asc / Desc，默认 Desc）。

素材格式要求

• 图片：jpeg / png / webp / bmp / tiff / gif / heic / heif，宽高 300–6000px，宽高比 0.4–2.5，单张 <30MB；
• 视频：mp4 / mov，480p–4K，时长 1.8–30.2 秒，单个 <200MB；
• 音频：wav / mp3，时长 1.8–30.2 秒，单个 <15MB。

上传的素材会被转存，URL 不可达会返回 InvalidParameter.DownloadFailed。

示例

# 创建素材组
curl "$URL/?Action=CreateAssetGroup&Version=2024-01-01" \
  -H "Authorization: Bearer $YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "Name": "我的素材组", "GroupType": "AIGC" }'

# 上传素材
curl "$URL/?Action=CreateAsset&Version=2024-01-01" \
  -H "Authorization: Bearer $YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "GroupId": "group-xxxx", "URL": "https://example.com/photo.jpg", "AssetType": "Image", "Name": "参考图" }'

# 查询素材（取最新引用 URL）
curl "$URL/?Action=GetAsset&Version=2024-01-01" \
  -H "Authorization: Bearer $YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "Id": "asset-xxxx" }'

响应为 { "ResponseMetadata": {...}, "Result": {...} } 信封；错误信息在 ResponseMetadata.Error（Code / Message）。

响应示例

创建类（CreateAssetGroup / CreateAsset）：

{
  "ResponseMetadata": {
    "RequestId": "202610181426133025978808268d9d6buuMLLoX",
    "Action": "CreateAssetGroup",
    "Version": "2024-01-01",
    "Service": "ark",
    "Region": "cn-beijing"
  },
  "Result": { "Id": "group-20260101120000-xxxxx" }
}

查询类（GetAsset）：

{
  "ResponseMetadata": { "RequestId": "...", "Action": "GetAsset", "Version": "2024-01-01", "Service": "ark", "Region": "cn-beijing" },
  "Result": {
    "Id": "asset-20260101120000-xxxxx",
    "Name": "参考图",
    "URL": "https://.../signed-url（约 12 小时有效）",
    "AssetType": "Image",
    "GroupId": "group-20260101120000-xxxxx",
    "Status": "Active",
    "CreateTime": "2026-01-01T12:00:00+08:00",
    "UpdateTime": "2026-01-01T12:01:00+08:00"
  }
}

列表类（ListAssets，页码式含 TotalCount；游标式含 NextToken 不含 TotalCount）：

{
  "ResponseMetadata": { "RequestId": "...", "Action": "ListAssets", "Version": "2024-01-01", "Service": "ark", "Region": "cn-beijing" },
  "Result": {
    "Items": [ { "Id": "asset-...", "Status": "Active", "AssetType": "Image", "GroupId": "group-..." } ],
    "TotalCount": 12,
    "PageNumber": 1,
    "PageSize": 10
  }
}

错误：

{
  "ResponseMetadata": {
    "RequestId": "...",
    "Error": { "Code": "InvalidParameter.DownloadFailed", "Message": "Failed to download media from the provided URL." }
  }
}

常见问题

Q: 素材上传报 DownloadFailed / HeightTooSmall？

素材 URL 必须公网可直连（会实时抓取校验），图片宽高需在 300–6000px 之间。

Q: 删除素材/分组返回「稍后重试」（409）？

素材刚上传完（处理中/审核中）或正被视频任务引用时不可删除，上游会拒绝并提示稍后重试——平台如实透传为 409，等待片刻重试即可；删除分组前需先清空组内素材。

Q: 素材什么时候能用于生成？

CreateAsset 返回 Id 后素材处于处理中，轮询 GetAsset 到 Status=Active 才可在任务的 content 里引用其 URL。