素材库 Assets（Seedance_sup）

素材库用于上传并管理人像类素材（虚拟人像、真人人像等），是数字人视频、定制化形象生成等场景的前置能力。所有素材操作通过统一端点 /v1/assets 完成，与视频接口共用同一套 API Key 鉴权。

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

本页：Seedance_sup（seedance-2-0 系列）配套的素材库，路径 /v1/assets，素材引用格式 asset://asset-xxx；
原生 Seedance V3（doubao-seedance-*）配套的素材库，路径 /v3/asset-groups、/v3/assets——见原生 Seedance V3 素材库。
两套素材不能互相引用（asset:// 绑定创建它的上游）。

我们的对外接口是统一且稳定的契约：您调用的路径、参数、返回结构都保持一致，后续升级无需改动您的代码。

两种素材库

`kind`	名称	说明
`virtual`	虚拟人像库	直接上传虚拟形象 / 素材图片、视频，无需真人核验
`real`	真人人像库	需先通过真人核验流程，再上传真人素材

鉴权

所有请求都需要在 Header 携带您的 API Key，与视频接口完全一致：

http

Authorization: Bearer $YOUR_API_KEY

资源对象 `asset`（响应字段）

上传成功后返回的资源结构如下，后续查询 / 列表返回的元素也使用同一结构：

字段	类型	说明
`asset_id`	string	素材文件 ID，形如 `ast_xxx`，可用于路径参数
`asset_uri`	string	素材引用 URI，形如 `asset://asset-xxx`，在视频生成时引用此值
`asset_kind`	string	`virtual` 或 `real`
`asset_type`	string	`image` 或 `video`
`name`	string	素材名称
`status`	string	素材状态（`active` / `failed` / `deleted` 等）
`url`	string	素材访问地址（如有）
`size_bytes`	int	文件大小（字节）
`delete_after`	int	自动过期时间戳（0 表示不过期）
`duration_seconds`	float	视频时长（秒），图片为 0
`provider`	string	素材来源标识

接口总览

操作	方法与路径	适用范围
上传素材	`POST $URL/v1/assets`	virtual / real
素材列表	`GET $URL/v1/assets`	基于当前账户隔离视图
查询单个	`GET $URL/v1/assets/{asset_id}`	virtual / real
更新素材	`PATCH $URL/v1/assets/{asset_id}`	仅 virtual
删除素材	`DELETE $URL/v1/assets/{asset_id}`	virtual / real
重试生成	`POST $URL/v1/assets/{asset_id}/retry`	仅 virtual（失败态）
创建 liveness 会话	`POST $URL/v1/assets/liveness/sessions`	real
确认 liveness	`POST $URL/v1/assets/liveness/sessions/{id}/confirm`	real
授权 liveness	`POST $URL/v1/assets/liveness/sessions/{id}/accept`	real
最近一次授权	`GET $URL/v1/assets/liveness/sessions/latest`	real

路径参数 {asset_id} 的两种传法

以下两种值均可作为路径参数（等价）：

文件 ID：ast_xxx（上传响应的 asset_id 字段）
URI 派生 ID：asset-xxx（即 asset_uri 去掉 asset:// 前缀）

注意：不要把完整的 asset://asset-xxx 直接拼进 URL 路径（// 会导致 404），请先去掉 asset:// 前缀。

1. 上传素材 `POST /v1/assets`

上传素材到指定素材库。kind 与 asset_type 通过 Query 参数传递，文件内容通过请求体传输。

Query 参数

参数	必填	说明
`kind`	否	`virtual`（默认）或 `real`
`asset_type`	是	`image` 或 `video`
`name`	否	素材名称，便于后续识别
`session_id`	real 必填	真人人像库需先创建 liveness 会话并传入其 `session_id`

请求体：原始二进制（设置 Content-Type: image/* 或 video/* 并携带 X-Filename 头），或 multipart/form-data 的 file 字段。两种均可。

虚拟人像库（二进制上传）

bash

curl $URL/v1/assets?kind=virtual&asset_type=image&name=avatar.png \
  -H "Authorization: Bearer $YOUR_API_KEY" \
  -H "Content-Type: image/png" \
  -H "X-Filename: avatar.png" \
  --data-binary @avatar.png

虚拟人像库（表单上传）

bash

curl $URL/v1/assets?kind=virtual&asset_type=image&name=avatar.png \
  -H "Authorization: Bearer $YOUR_API_KEY" \
  -F "file=@avatar.png"

真人人像库（需 session_id）

bash

curl "$URL/v1/assets?kind=real&asset_type=image&session_id=lvfs_xxx&name=real.png" \
  -H "Authorization: Bearer $YOUR_API_KEY" \
  -F "file=@real.png"

响应示例

json

{
  "asset_id": "ast_abc123def456",
  "asset_uri": "asset://asset-20260728-abc12",
  "asset_kind": "virtual",
  "asset_type": "image",
  "name": "avatar.png",
  "status": "active",
  "url": "https://...",
  "size_bytes": 123456,
  "delete_after": 0,
  "duration_seconds": 0,
  "provider": "—"
}

素材规格

上传的素材需符合规格要求（尺寸、格式、内容等）。若返回类似「图片规格不受支持」的业务错误，请按提示更换素材后重试。错误会原样透传，详见下方「错误码」。

2. 素材列表 `GET /v1/assets`

列表基于当前账户的隔离视图返回，不会看到其他账户的素材。

Query 参数

参数	必填	说明
`kind`	否	按素材库筛选 `virtual` / `real`
`asset_type`	否	按类型筛选 `image` / `video`
`status`	否	按状态筛选
`search`	否	按名称模糊搜索
`sort_by`	否	`created_at` / `name` / `size_bytes`
`sort_order`	否	`asc` / `desc`（默认 `desc`）
`page`	否	页码，从 1 开始（默认 1）
`page_size`	否	每页数量，1–100（默认 20）

bash

curl "$URL/v1/assets?kind=virtual&asset_type=image&page=1&page_size=20" \
  -H "Authorization: Bearer $YOUR_API_KEY"

响应示例

json

{
  "assets": [
    {
      "asset_id": "ast_abc123def456",
      "asset_uri": "asset://asset-20260728-abc12",
      "asset_kind": "virtual",
      "asset_type": "image",
      "name": "avatar.png",
      "status": "active",
      "url": "https://...",
      "size_bytes": 123456,
      "delete_after": 0,
      "duration_seconds": 0,
      "provider": "—"
    }
  ],
  "pagination": { "page": 1, "page_size": 20, "total": 1 },
  "group": { "exists": true }
}

3. 查询单个素材 `GET /v1/assets/{asset_id}`

先校验素材归属（不属于当前账户返回 404），再返回素材详情。

refresh=true 时会刷新最新状态（如 status、url、delete_after）。

bash

curl $URL/v1/assets/asset-20260728-abc12?refresh=true \
  -H "Authorization: Bearer $YOUR_API_KEY"

4. 更新素材 `PATCH /v1/assets/{asset_id}`

仅 virtual 素材支持。对 real 素材调用返回 405 method_not_allowed。

请求体透传，可更新 name / description / pinned 等字段。

bash

curl -X PATCH $URL/v1/assets/asset-20260728-abc12 \
  -H "Authorization: Bearer $YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "new_name.png" }'

5. 删除素材 `DELETE /v1/assets/{asset_id}`

先校验归属，再请求删除，本地标记为 deleted（软删除，保留记录）。删除后该 asset_uri 不可再用于新任务。

bash

curl -X DELETE $URL/v1/assets/asset-20260728-abc12 \
  -H "Authorization: Bearer $YOUR_API_KEY"

6. 重试生成 `POST /v1/assets/{asset_id}/retry`

仅 virtual 素材支持，且通常仅当状态为 failed 时有效。对 real 素材调用返回 405。

bash

curl -X POST $URL/v1/assets/asset-20260728-abc12/retry \
  -H "Authorization: Bearer $YOUR_API_KEY"

7. 真人人像库 liveness 流程

real 素材需要先完成真人核验（liveness）。整体流程如下：

创建会话 POST /v1/assets/liveness/sessions → 返回 session_id 与 h5_link。
用户核验：将 h5_link 发给最终用户，在手机端完成真人核验。
确认 POST /v1/assets/liveness/sessions/{id}/confirm → 状态变为 validated。
授权 POST /v1/assets/liveness/sessions/{id}/accept（可带 note）→ 状态变为 accepted。
上传真人素材：使用上一步的 session_id 调用上传接口（kind=real）。

也可随时查询最近一次已授权会话：GET /v1/assets/liveness/sessions/latest。

创建会话

bash

curl -X POST $URL/v1/assets/liveness/sessions \
  -H "Authorization: Bearer $YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

响应示例

json

{
  "session": {
    "session_id": "lvfs_9EIegs6xSuzCSGTr9OO8vyyPK2Z7YA63",
    "h5_link": "https://...",
    "status": "pending",
    "expires_at": 1785003600,
    "accepted_at": null
  }
}

关于隔离

真人人像库的 liveness 会话按渠道维度隔离（同一上游渠道下共享），不按最终用户细分。如果您需要把某个会话严格绑定到特定终端用户，请在您的业务系统里自行维护 session_id 与用户的对应关系。

在视频生成中引用素材

拿到 asset_uri 后，将其放入视频生成请求的 images 字段即可引用该素材（原样透传，无需任何转换）：

bash

curl $URL/v1/videos \
  -H "Authorization: Bearer $YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-2-0",
    "prompt": "让这张照片里的人物做出挥手动作",
    "seconds": "5",
    "size": "720p",
    "images": ["asset://asset-20260728-abc12"]
  }'

错误码

素材库接口在出错时返回统一结构 { "error": { "code": "...", "message": "..." } }。常见错误如下：

`code`	HTTP	说明
`asset_not_found`	404	素材不存在，或不属于当前账户
`missing_session_id`	400	`real` 上传缺少 `session_id`
`invalid_kind`	400	`kind` 不是 `virtual` / `real`
`invalid_asset_type`	400	`asset_type` 不是 `image` / `video`
`method_not_allowed`	405	对 `real` 素材调用了仅 `virtual` 支持的接口（PATCH / retry）
`asset_upstream_unavailable`	503	素材渠道暂不可用
`asset_upstream_error`	502	上游网关错误
`volc_asset_create_failed` 等	4xx / 5xx	上游返回的业务错误，内容原样透传，请按 `message` 提示处理

限制与说明

真实人像库的管理接口：当前仅暴露「查询 / 列表 / 删除」，不提供 PATCH 与 retry（真人人像库不支持）。
列表隔离：素材列表基于当前账户隔离（平台 user_assets 归属表），不会泄露其他账户的素材；查询/删除也先做归属校验。
统一契约：本文档描述的接口保持稳定，后续升级无需修改您的调用代码。

Seedance_sup

Seedance_V3 原生

Seedance_V3原生（SC）

素材库 Assets（Seedance_sup）

两种素材库

鉴权

资源对象 `asset`（响应字段）

接口总览

1. 上传素材 `POST /v1/assets`

2. 素材列表 `GET /v1/assets`

3. 查询单个素材 `GET /v1/assets/{asset_id}`

4. 更新素材 `PATCH /v1/assets/{asset_id}`

5. 删除素材 `DELETE /v1/assets/{asset_id}`

6. 重试生成 `POST /v1/assets/{asset_id}/retry`

7. 真人人像库 liveness 流程

在视频生成中引用素材

错误码

限制与说明

素材库 Assets（Seedance_sup） ​

两种素材库 ​

鉴权 ​

资源对象 asset（响应字段） ​

接口总览 ​

1. 上传素材 POST /v1/assets ​

2. 素材列表 GET /v1/assets ​

3. 查询单个素材 GET /v1/assets/{asset_id} ​

4. 更新素材 PATCH /v1/assets/{asset_id} ​

5. 删除素材 DELETE /v1/assets/{asset_id} ​

6. 重试生成 POST /v1/assets/{asset_id}/retry ​

7. 真人人像库 liveness 流程 ​

在视频生成中引用素材 ​

错误码 ​

限制与说明 ​

素材库 Assets（Seedance_sup）

两种素材库

鉴权

资源对象 `asset`（响应字段）

接口总览

1. 上传素材 `POST /v1/assets`

2. 素材列表 `GET /v1/assets`

3. 查询单个素材 `GET /v1/assets/{asset_id}`

4. 更新素材 `PATCH /v1/assets/{asset_id}`

5. 删除素材 `DELETE /v1/assets/{asset_id}`

6. 重试生成 `POST /v1/assets/{asset_id}/retry`

7. 真人人像库 liveness 流程

在视频生成中引用素材

错误码

限制与说明