素材库 Assets V3（原生 Seedance V3）

原生 Seedance V3（doubao-seedance-* 系列）配套的素材库：先创建分组、上传参考素材，再在视频生成时引用。素材按客户强制隔离——每个客户只能看到/操作自己的分组与素材（平台归属表强制校验）。

素材库有两套（按模型系列区分）

• 本页：原生 Seedance V3（doubao-seedance-*）的素材库，路径 /v3/asset-groups、/v3/assets；
• Seedance_sup（seedance-2-0 系列）的素材库，路径 /v1/assets——见素材库（Seedance_sup）。
• 两套素材不能互相引用。

鉴权

所有请求均需携带 API Key（与视频接口同一套）：

Authorization: Bearer $YOUR_API_KEY

核心概念

• 分组（asset-group）：素材的容器，创建后返回 groupId（如 group-20260802183721-1ceb5f）；
• 素材（asset）：一条参考图/参考视频，用公网 URL 引用（上游服务端自行拉取），返回 id（如 asset-20260802183721-n4kcy）；
• 素材必须归属于某个分组；分组/素材 ID 全局唯一，归属关系由平台登记。

接口总览

操作	方法与路径	说明
创建分组	POST $URL/v3/asset-groups	body {"name":"..."}
分组列表	GET $URL/v3/asset-groups	仅本客户分组
上传素材	POST $URL/v3/assets	header group_id + body {"url":"..."}
素材列表	GET $URL/v3/assets	仅本客户素材
素材详情	POST $URL/v3/assets/detail	header group_id + body {"assetId":"..."}
删除素材	DELETE $URL/v3/assets/{assetId}	header group_id
删除分组	DELETE $URL/v3/asset-groups/{groupId}	组下有素材时不可删

1. 创建分组 POST /v3/asset-groups

请求示例

POST $URL/v3/asset-groups
Content-Type: application/json

{ "name": "我的素材分组" }

响应字段

字段	类型	说明
code	integer	状态码（200 表示成功）
msg	string	提示信息
data.groupId	string	新建分组 ID
data.name	string	分组名称

响应示例

{ "code": 200, "msg": "操作成功", "data": { "groupId": "group-xxx", "name": "我的素材分组" } }

上游抖动

创建分组偶发返回 409 数据库中已存在该记录（上游间歇抖动，约一半概率）——重试同一请求即可成功。分组名全局唯一，同名重复创建会返回 500 同名分组已存在，请换名。

2. 分组列表 GET /v3/asset-groups

请求示例

GET $URL/v3/asset-groups

响应字段

字段	类型	说明
code	integer	状态码
data.items	array	分组列表
data.items[].groupId	string	分组 ID
data.items[].name	string	分组名称
data.items[].createTime	integer	创建时间（毫秒时间戳）

响应示例

{ "code": 200, "data": { "items": [ { "groupId": "group-xxx", "name": "我的素材分组", "createTime": 1785667041000 } ] } }

列表由平台基于归属登记表提供（上游无列表接口），天然按客户隔离；createTime 为毫秒时间戳。

3. 上传素材 POST /v3/assets

请求示例

POST $URL/v3/assets
Content-Type: application/json
group_id: {groupId}          ← 必须：素材所属分组（真实分组 ID）

{ "url": "https://example.com/ref.png" }

响应字段

字段	类型	说明
code	integer	状态码
data.id	string	素材 ID
data.url	string	素材 URL
data.assetType	string	Image / Video
data.status	string	Processing / 其他
data.groupId	string	所属分组 ID

响应示例

{ "code": 200, "data": { "id": "asset-xxx", "url": "https://...", "assetType": "Image", "status": "Processing", "groupId": "group-xxx" } }

字段说明

group_id 放 Header（上游契约）；body 字段名是下划线 group_id，驼峰 groupId 无效。素材刚上传为 Processing（上游抓取 URL 中），处理完成前不可删除，稍后重试即可。

4. 素材列表 GET /v3/assets

响应字段

字段	类型	说明
code	integer	状态码
data.items	array	素材列表
data.items[].assetId	string	素材 ID
data.items[].name	string	素材名称
data.items[].url	string	素材 URL
data.items[].groupId	string	所属分组 ID
data.items[].status	string	Processing 等
data.items[].createTime	integer	创建时间（毫秒时间戳）

响应示例

{ "code": 200, "data": { "items": [ { "assetId": "asset-xxx", "name": "", "url": "https://...", "groupId": "group-xxx", "status": "Processing", "createTime": 1785667041000 } ] } }

5. 素材详情 POST /v3/assets/detail

POST $URL/v3/assets/detail
Content-Type: application/json
group_id: {groupId}          ← 素材所属分组

{ "assetId": "asset-xxx" }

返回素材完整信息（含最新 status）。

6. 删除素材 DELETE /v3/assets/{assetId}

DELETE $URL/v3/assets/{assetId}
group_id: {groupId}          ← 素材所属分组

• Processing 中的素材删除会返回 500 素材正在上传、审核或被视频任务使用，请稍后重试删除——等处理完成再删；
• 删除成功后归属记录同步清除，重复删除返回 403。

7. 删除分组 DELETE /v3/asset-groups/{groupId}

DELETE $URL/v3/asset-groups/{groupId}

• 组下仍有素材时不可删除（500 素材组下仍有素材，无法删除），先删素材；
• 删除成功后归属记录同步清除。

在视频生成中引用素材

拿到素材 URL 后，放入原生 Seedance V3 任务的 content[]（image_url / video_url 类型）即可引用：

{
  "model": "doubao-seedance-2.0",
  "content": [
    { "type": "text", "text": "让这张照片里的人物做出挥手动作" },
    { "type": "image_url", "image_url": { "url": "https://example.com/ref.png" } }
  ],
  "resolution": "720p",
  "duration": 5
}

隔离与错误码

素材库由平台网关做归属强制校验：创建分组/上传素材成功后登记，删除/详情前校验必须是本客户登记的资源，越权一律 403。

HTTP	code / message	含义 / 处理
403	forbidden	越权：不是本客户的分组/素材（或未登记）
400	group_id_required	上传素材未指定 group_id
500	素材URL不能为空	上传素材缺 url
500	分组名称不能为空	创建分组缺 name
500	同名分组已存在	分组名全局唯一，换名
500	group_id不能为空	删除素材/详情缺 header group_id
500	素材正在上传... / 素材组下仍有素材...	状态限制，稍后或先删素材
404	Invalid URL 等	请确认路径拼写（/v3/assets*，非 /v1/assets）