素材库 API 接口文档

素材库用于管理视频生成所需的图片、视频、音频素材。上传后的素材会获得 asset:// 格式的引用地址，可直接用于视频生成请求中。

令牌隔离机制

素材库按**令牌（Token）**进行隔离，同一用户下不同令牌拥有各自独立的素材库空间。

隔离规则

使用令牌 A 的 API Key 创建的素材，令牌 B 无法查看、修改或删除

创建素材时必须指定 group_id，需先通过「创建素材库」接口创建分组

查询素材列表（group_id <= 0 或不传）时，返回当前令牌的所有素材 + 账号历史素材

分组可通过「转移素材库」接口在令牌之间转移

全部素材

「全部素材」视图包含：

当前令牌所有分组中的素材

账号的历史素材（升级前创建的，token_id=0）

其他令牌的素材不可见。

历史数据兼容

升级前已创建的素材库和素材保留为历史数据（token_id=0）：

通过「全部素材」视图可见，可正常使用

历史素材的 asset:// 引用地址不变，已有的视频生成请求无需修改

可通过「转移素材库」接口将历史分组移至指定令牌管理

Playground（视频生成广场）

Playground 通过 URL 参数 ?token_id=X 切换令牌视角：

必须选择令牌才能操作素材库

选择令牌后，显示「全部素材」和令牌专属的自定义分组

在选定令牌下创建的分组和素材归入该令牌

创建素材前必须先选择或创建一个分组

认证方式

所有接口需要在请求头中携带 API Key：

Authorization: Bearer sk-xxxx
Content-Type: application/json

基础地址

{BASE_URL}/v1/assets

1. 创建素材

上传一个素材（图片/视频/音频）到素材库。必须先创建素材库分组，然后指定 group_id 参数。

请求

POST /v1/assets

请求参数

参数	类型	必填	说明
url	string	是	素材文件的公网可访问 URL
asset_type	string	是	素材类型：`Image`、`Video`、`Audio`
name	string	否	素材名称（上限 64 字符）
group_id	int	是	素材库 ID，必须指定素材归属的素材库（通过「创建素材库」接口获得）
upload_mode	string	否	上传模式：`sync`（默认，同步阻塞等待审核完成后返回）、`async`（异步，立即返回处理中的素材，后台轮询上游审核）。详见「1.1 异步上传素材」

图片要求

高度：300px ~ 6000px

URL 必须公网可访问（火山引擎服务端会下载该文件）

请求示例

响应示例

{
  "code": "success",
  "data": {
    "id": "asset-20260403150605-bfjwz",
    "asset_url": "asset://asset-20260403150605-bfjwz"
  }
}

说明

id：素材唯一标识

asset_url：素材引用地址，格式为 asset://{id}，可直接用于视频生成请求

素材创建后需要等待处理完成（状态变为 Active）才能使用，通常耗时几秒到几十秒

素材归入指定的素材库分组，仅该分组所属令牌可访问

必须先通过「创建素材库」接口创建分组，获得 group_id 后才能创建素材

1.1 异步上传素材

当素材审核耗时较长、或需要批量上传时，可使用异步模式（upload_mode=async）。异步上传会立即返回一条状态为 Processing 的素材记录，同时返回一个 id（即上游任务 ID）。平台在后台轮询上游审核，完成后将该素材状态更新为 Active（失败则为 Failed）。返回的 id 可直接用于「查询单个素材」接口，无论素材处于处理中还是已完成，都能用同一个 id 查到最新状态。

同步模式（默认）会阻塞等待审核完成，单次请求最长可能等待几十秒；异步模式立即返回，适合不希望长时间占用连接的场景。

请求

POST /v1/assets

请求参数

与「1. 创建素材」相同，额外指定 upload_mode 为 async：

参数	类型	必填	说明
url	string	是	素材文件的公网可访问 URL
asset_type	string	是	素材类型：`Image`、`Video`、`Audio`
name	string	否	素材名称（上限 64 字符）
group_id	int	是	素材库 ID
upload_mode	string	是	固定为 `async`
callback_url	string	否	结果回调地址（Webhook）。填写后，任务处理完成（成功或失败）时平台会向该地址 POST 一次结果，免去轮询。详见「1.3 上传结果回调（Webhook）」
callback_secret	string	否	可选。回调签名密钥，用于验签防伪造。不需要验签时留空即可，回调照常发送，只是不带签名头

响应示例

{
  "code": "success",
  "data": {
    "id": "task-20260630120000-abcde",
    "status": "Processing"
  }
}

说明

id：异步上传返回的任务 ID，可直接作为「查询单个素材」接口的 id 参数轮询状态。

status：Processing 表示后台正在处理。

提交后请轮询「查询单个素材」接口（传入上面返回的 id），根据 status 字段判断结果：

Processing：仍在处理中，建议每隔 3 秒轮询一次

Active：处理完成，响应中的 asset_url 即可用于视频生成

Failed：处理失败（审核拒绝、URL 不可访问或上游超时等），响应会额外带 error 对象说明失败原因，详见「3. 查询单个素材」的失败响应示例

素材完成后其真实素材 ID 会写入 id 字段返回，但用异步返回的任务 ID 仍可继续查询该素材，两者均可作为查询凭证。

若提交时携带了 callback_url，任务完成后平台会主动 POST 结果到该地址，可省去轮询；轮询与回调二者独立、互为补充。详见「1.3 上传结果回调（Webhook）」。

若任务在 5 分钟内始终未处理完成（上游异常/审核阻塞等），平台会将该素材置为 Failed，避免长期卡在 Processing。

轮询示例（Python）

1.2 批量异步上传素材

一次性提交多个素材 URL，共享同一批次（batch_id）在后台异步处理。适合需要一次录入大量素材的场景，避免逐条调用「创建素材」。

批量上传仅支持异步模式（async）。提交后立即返回一个 batch_id 和每条 URL 的初始状态（Processing），平台在后台逐条向上游提交审核并回填结果。请通过「3.1 按批次查询素材」轮询整批进度。

请求

POST /v1/assets

请求参数

参数	类型	必填	说明
urls	string[]	是	素材文件的公网可访问 URL 数组，最多 50 条。非空时走批量异步，忽略 `url` 单条字段
asset_type	string	否	素材类型：`Image`、`Video`、`Audio`，默认 `Image`。批次内所有素材共用同一类型
name	string	否	素材名称，批次内所有素材共用
group_id	int	是	素材库 ID，必须指定素材归属的素材库
upload_mode	string	否	批量下只能为 `async`（默认即 `async`）；显式传 `sync` 会被拒绝
callback_url	string	否	整批结果回调地址（Webhook）。填写后，整批处理完成时平台会 POST 一次批次结果到该地址。详见「1.3 上传结果回调（Webhook）」
callback_secret	string	否	可选。回调签名密钥，不需要验签时留空即可

每个 URL 必须包含受支持的文件扩展名，否则会被上游拒绝：

图片：jpeg / jpg / png / webp / bmp / tiff / gif / heic

视频：mp4 / mov

音频：wav / mp3

URL 必须公网可访问（服务端会下载该文件）

请求示例

响应示例

{
  "code": "success",
  "data": {
    "batch_id": "task-20260713070255-c9a9f950",
    "task_id": "task-20260713070255-c9a9f950",
    "total": 3,
    "status": "Processing",
    "items": [
      { "source_url": "https://example.com/img-1.jpg", "status": "Processing" },
      { "source_url": "https://example.com/img-2.jpg", "status": "Processing" },
      { "source_url": "https://example.com/img-3.jpg", "status": "Processing" }
    ]
  }
}

响应字段说明

字段	说明
batch_id	批次 ID，后续用「3.1 按批次查询素材」查整批进度
task_id	上游任务 ID，与 `batch_id` 相同
total	本批提交的素材条数
status	批次整体状态，提交成功后固定为 `Processing`
items[].source_url	原始提交 URL
items[].status	单条初始状态，均为 `Processing`

说明

提交成功后，平台为每条 URL 落一条 Processing 占位记录（共享同一 batch_id），后台逐条轮询上游审核并回填为 Active / Failed。

上游对批次内素材串行审核，整批耗时随条数线性增长（实测每条约 26～27 秒，10 条约 6 分钟）。请勿期望提交即完成，应通过「3.1 按批次查询素材」轮询最终结果。

单条素材完成后其真实素材 ID 可用于「3. 查询单个素材」及视频生成。

常见错误

请求	返回
`urls` 全为空白	`{"error":{"message":"urls 不能全为空"}}`
`urls` 超过 50 条	`{"error":{"message":"单次批量最多提交 50 条素材"}}`
`upload_mode` 传 `sync`	`{"error":{"message":"批量上传仅支持 async 模式"}}`
URL 无支持扩展名	`{"error":{"message":"第 N 条URL文件类型不受支持..."}}`

1.3 上传结果回调（Webhook）

异步上传（单条 1.1 与批量 1.2）支持在提交时携带 callback_url，任务处理完成后平台会主动向该地址 POST 一次结果，下游无需轮询即可实时拿到最终状态。回调与轮询相互独立、互为补充：即使配置了回调，仍可继续调用查询接口；回调因网络原因最终投递失败时，也可回退为轮询兜底。

触发时机

单条异步：该任务处理完成（completed）或失败（failed）时触发一次。

批量异步：整批处理完成时触发一次，载荷内 result.items 覆盖批次内所有素材。

无论成功或失败都会回调；任务超时（默认 5 分钟未完成）等严重错误也会以 status=failed 回调。

每个任务仅回调一次（平台内部按 task_id 原子去重，回调与超时兜底竞争时也只发一次）。

请求头

请求头	说明
Content-Type	`application/json`
X-Track-Id	本次任务 ID（= 载荷中的 `task_id`），下游可用作幂等键去重
X-Webhook-Signature	仅当提交时填写了 `callback_secret` 才有；值为 `HMAC-SHA256(callback_secret, 原始请求体)` 的十六进制字符串，用于验签防伪造

回调载荷

平台以 POST 发送如下 JSON（结构与任务查询结果一致）：

{
  "code": 200,
  "task_id": "task-20260716024754-ad728332",
  "status": "completed",
  "total_count": 1,
  "done_count": 1,
  "result": {
    "review_batch_id": "task-20260716024754-ad728332",
    "items": [
      {
        "asset_id": "local-20260716024755-51504ef1",
        "source_url": "https://example.com/sunflower.jpg",
        "asset_url": "asset://asset-20260716104759-mm8tf",
        "downstream_asset_id": "asset-20260716104759-mm8tf",
        "downstream_final_url": "https://.../signed-url",
        "downstream_url_expire_at": "2026-07-16T14:48:08Z",
        "submit_review_status": 1,
        "asset_type": "Image",
        "error_code": "",
        "error_message": "",
        "createtime": "2026-07-16T02:47:59Z"
      }
    ]
  }
}

载荷字段说明

字段	说明
code	任务级状态码，`200` 表示任务完成；非 `200` 表示任务失败
task_id	任务 ID，与单条异步返回的 `id` / 批量返回的 `batch_id` 一致
status	任务状态：`completed`（完成）/ `failed`（失败）
total_count	任务内素材总数
done_count	已处理完成数
result	成功时的结果对象；任务级失败时可能为 `null`
result.items[].source_url	原始提交 URL，用于对账哪条 URL 对应哪个素材
result.items[].asset_url	`asset://{id}` 引用地址，可直接用于视频生成
result.items[].submit_review_status	`1` 表示该条审核通过；其他值表示未通过，失败原因见 `error_code` / `error_message`

下游接收要求

收到回调后请尽快返回 HTTP 2xx（建议 200）表示已接收。

平台投递超时或返回非 2xx 时会有限次退避重试（立即 + 1s + 3s + 7s，共 4 次），仍失败则记录日志放弃，此时请用查询接口兜底。

请用 task_id（或 X-Track-Id）做幂等去重，避免重试导致的重复处理。

回调签名密钥（callback_secret，可选）

大多数场景无需验签，只填 callback_url 即可，本节可跳过。 仅当你需要在下游严格校验回调来源、防止伪造时才使用 callback_secret。

callback_secret 用于校验回调请求确实来自本平台、且内容未被篡改。它的工作方式是"共享密钥"，由客户自己定义，平台不下发、也不保存明文用于其他用途：

如何获取

无需向平台申请。由客户自行生成一个足够随机的字符串即可（建议 32 位以上，例如 openssl rand -hex 32 的输出）。

客户自行妥善保管，不要泄露给第三方。同一密钥可在多次上传中复用，也可按业务区分。

如何使用

提交异步上传时，在请求体里带上 callback_secret（与 callback_url 一起）。

任务完成后，平台用同一个密钥对回调请求体（原始字节）做 HMAC-SHA256，把结果的十六进制字符串放进 X-Webhook-Signature 请求头发给你。

下游收到回调后，用自己保存的密钥对收到的原始请求体重新计算 HMAC-SHA256，与 X-Webhook-Signature 比对：一致则可信，不一致则应拒绝（可能是伪造或篡改）。

说明：
不传 callback_secret 时，回调请求不带 X-Webhook-Signature 头，此时下游无法验签，建议至少通过校验来源 IP / 隐蔽的 callback_url 路径等方式自行保障安全。
验签必须使用原始请求体字节计算，不要先把 JSON 解析成对象再重新序列化（字段顺序/空格差异会导致签名不一致）。

验签示例（Python）

回调地址要求

callback_url 必须是下游公网可访问的 http(s) 地址。

1.4 异步上传素材（新）

对接上游官方素材管理接口的异步上传方式，专用端点 POST /v1/assets/async。与「1.1 异步上传素材」的关键区别：

立即返回真实素材 ID：提交后上游直接分配 asset-xxxxx 素材 ID（无需等任务回填），状态初始为 Pending。

实时状态：处理中查询时平台实时透传上游最新 status，无平台后台轮询延迟。

永久访问 URL：素材处理完成（Active）后，平台会将其转存到平台 OSS，返回永久有效的访问 URL（与「1.1 异步上传素材」一致），无需担心签名过期。

本接口与「1. 创建素材」「1.1 异步上传素材」并存，互不影响。已有集成无需改动；需要真实素材 ID 立即返回时使用本接口。素材同样归属到 group_id 指定的素材库，可在平台界面按分组查看。

请求

POST /v1/assets/async

请求参数

参数	类型	必填	说明
url	string	是	素材文件的公网可访问 URL，需可被上游直接访问
group_id	int	是	素材库 ID，指定素材归属的素材库（通过「创建素材库」接口获得）
asset_type	string	否	素材类型：`Image`、`Video`、`Audio`，默认 `Image`
name	string	否	素材名称

请求示例

响应示例

{
  "code": "success",
  "data": {
    "id": "asset-20260716171312-pvq2l",
    "group_id": 8,
    "status": "Pending"
  }
}

说明

id：上游返回的真实素材 ID，直接作为「3. 查询单个素材」接口（POST /v1/assets/get）的 id 参数轮询状态。

group_id：素材归属的素材库 ID（即请求传入值）。

status：初始为 Pending（处理中）。

状态轮询

用返回的 id 调用「3. 查询单个素材」接口轮询，status 取值：

status	含义	是否终态
`Pending`	处理中	否，需继续轮询
`Active`	处理成功，可正常使用	是
`Failed`	处理失败	是
`Deleted`	已删除	是

建议轮询间隔 ≥ 500ms（上游单令牌限速 10 次/秒）。素材通常在 5–30 秒内进入终态。素材进入 Active 后，查询返回的 url 为平台 OSS 的永久访问地址，可长期使用。

轮询示例（Python）

错误响应

场景	响应
`url` 为空	`{"error":{"message":"url 不能为空"}}`
`group_id` 未指定	`{"error":{"message":"group_id 必须指定，请先创建素材库分组"}}`
分组不存在/无权访问	`{"error":{"message":"指定的分组不存在或无权访问"}}`
`asset_type` 非法	`{"error":{"message":"asset_type 必须为 Image、Video 或 Audio"}}`
上游创建失败	`{"error":{"message":"[ErrorCode] 上游返回的失败原因"}}`

2. 查询素材列表

分页查询当前令牌的素材列表。

请求

POST /v1/assets/list

请求参数

参数	类型	必填	说明
page_number	int	否	页码，默认 1
page_size	int	否	每页数量，默认 20，最大 100
name	string	否	按名称模糊搜索
group_id	int	否	素材库 ID。`-2`：仅查历史分组（`token_id=0`）；`<= 0`（其他值）或不传：查当前令牌所有素材 + 历史素材；`> 0`：查指定分组

请求示例

响应示例

{
  "code": "success",
  "data": {
    "items": [
      {
        "id": "asset-20260403150605-bfjwz",
        "name": "sunflower-renamed",
        "url": "https://ark-media-asset.tos-cn-beijing.volces.com/...(签名URL，有效期12小时)",
        "asset_url": "asset://asset-20260403150605-bfjwz",
        "asset_type": "Image",
        "status": "Active",
        "create_time": "2026-04-03T07:06:05Z"
      }
    ],
    "total_count": 1,
    "page_number": 1,
    "page_size": 20
  }
}

响应字段说明

字段	说明
id	素材 ID
name	素材名称
url	素材原始文件访问地址（签名 URL，有效期 12 小时）
asset_url	素材引用地址，用于视频生成
asset_type	素材类型：`Image` / `Video` / `Audio`
status	素材状态：`Active`（可用）/ `Processing`（处理中）/ `Failed`（失败）
error	仅当 `status=Failed` 时出现，为失败原因对象 `{"message": "..."}`（若上游返回错误码则形如 `{"code": "...", "message": "..."}`）；成功素材不含此字段
create_time	创建时间

3. 查询单个素材

根据素材 ID 查询详细信息。仅能查询当前令牌可见范围内的素材。

id 参数同时接受素材 ID和异步上传返回的任务 ID：异步上传（upload_mode=async）时，用返回的任务 ID 查询即可，无论素材处于 Processing 还是 Active 状态都能查到。

本接口也用于「1.3 异步上传素材（新）」的状态轮询：传入新接口返回的真实素材 ID 即可。此时平台会实时透传上游查询该素材的最新状态，status 取值为 Pending（处理中）/ Active（成功）/ Failed（失败）/ Deleted（已删除），返回的 url 为带签名访问地址（有效期约 12 小时，过期后重新查询即可刷新）。两套接口的 status 语义对应关系：旧接口 Processing ≈ 新接口 Pending，其余一致。

请求

POST /v1/assets/get

请求参数

参数	类型	必填	说明
id	string	是	素材 ID，或异步上传返回的任务 ID

请求示例

响应示例

{
  "code": "success",
  "data": {
    "id": "asset-20260403150605-bfjwz",
    "name": "sunflower-renamed",
    "url": "https://ark-media-asset.tos-cn-beijing.volces.com/...(签名URL，有效期12小时)",
    "asset_url": "asset://asset-20260403150605-bfjwz",
    "asset_type": "Image",
    "status": "Active",
    "create_time": "2026-04-03T07:06:05Z"
  }
}

用异步返回的 task_id 查询

异步上传（upload_mode=async）返回的 id 即上游任务 ID，可直接作为 id 参数查询，无需关心它稍后会回填为真实素材 ID：

处理中返回 status=Processing；处理完成后用同一个 task_id 查询即返回 status=Active 及真实的 asset_url：

{
  "code": "success",
  "data": {
    "id": "asset-20260713095616-z2djw",
    "name": "test-async",
    "url": "https://.../asset-20260713095616-z2djw.jpg",
    "asset_url": "asset://asset-20260713095616-z2djw",
    "asset_type": "Image",
    "status": "Active",
    "create_time": "2026-07-13 09:55:52"
  }
}

典型用途：创建素材（含异步上传）后，用返回的 id 轮询此接口等待状态变为 Active，无需从素材列表中按名称翻找。

失败响应示例

当素材审核不通过或处理失败（status=Failed）时，响应会额外带一个 error 对象，透传上游返回的具体失败原因；无具体原因时回退为通用文案「素材处理失败」：

{
  "code": "success",
  "data": {
    "id": "task-20260714065603-2f6d17a7",
    "name": "",
    "asset_type": "Image",
    "status": "Failed",
    "error": {
      "code": "",
      "message": "InvalidParameter.WidthTooSmall: Width must be between 300px and 6000px."
    },
    "create_time": "2026-07-14 14:55:53"
  }
}

字段	说明
error.code	上游错误码，可能为空字符串
error.message	失败原因描述；上游未返回具体原因时回退为「素材处理失败」

同步上传（upload_mode=sync）失败时直接在创建接口的响应中以 {"error":{"message":"..."}} 返回原因；异步上传失败原因则通过本接口（及「查询素材列表」「按批次查询素材」）的 error 字段获取。

3.1 按批次查询素材

根据批量上传返回的 batch_id 查询整批素材的最新状态与详情。用于轮询「1.2 批量异步上传素材」提交的整批进度。

请求

POST /v1/assets/batch/get

请求参数

参数	类型	必填	说明
batch_id	string	是	批量上传返回的批次 ID

请求示例

响应示例

{
  "code": "success",
  "data": {
    "batch_id": "task-20260713070255-c9a9f950",
    "total_count": 3,
    "items": [
      {
        "id": "asset-20260713150306-cwb85",
        "name": "batch-test",
        "url": "https://.../asset-20260713150306-cwb85.jpg",
        "asset_url": "asset://asset-20260713150306-cwb85",
        "asset_type": "Image",
        "status": "Active",
        "create_time": "2026-07-13 15:02:48",
        "batch_id": "task-20260713070255-c9a9f950",
        "source_url": "https://example.com/img-1.jpg"
      },
      {
        "id": "task-20260713070255-c9a9f950",
        "name": "batch-test",
        "url": "",
        "asset_url": "",
        "asset_type": "Image",
        "status": "Processing",
        "create_time": "2026-07-13 15:02:48",
        "batch_id": "task-20260713070255-c9a9f950",
        "source_url": "https://example.com/img-2.jpg"
      }
    ]
  }
}

响应字段说明

字段	说明
batch_id	回显批次 ID
total_count	批次内素材总数
items[].id	素材 ID。完成后为真实 asset_id；处理中为 `batch_id` 占位
items[].name	素材名称
items[].url	可预览 URL（已配置 OSS 时为平台 OSS 直链）；处理中为空
items[].asset_url	`asset://{id}` 归一化地址；处理中为空
items[].asset_type	素材类型
items[].status	`Processing`（处理中）/ `Active`（可用）/ `Failed`（失败）
items[].error	仅当该条 `status=Failed` 时出现，为失败原因字符串（上游有错误码时形如 `[错误码] 描述`）；成功素材不含此字段
items[].create_time	记录创建时间
items[].batch_id	批次 ID
items[].source_url	原始提交 URL，便于对账哪条 URL 对应哪个素材

说明

该接口按 batch_id 返回整批全部素材，各条状态独立，可实时反映 Processing → Active/Failed 的进度。

判断整批完成：所有 items[].status 均不为 Processing 即处理结束。建议每隔 5～10 秒轮询一次。

Failed 的素材会在该条上带 error 字符串说明失败原因。若整批因上游参数校验等原因整体失败（如尺寸不符），批内每条会带相同的失败原因。

该能力仅在支持批量上传的素材渠道生效。

轮询示例（Python）

常见错误

请求	返回
`batch_id` 不存在或无权访问	`{"error":{"message":"批次不存在或无权访问"}}`
缺 `batch_id`	`{"error":{"message":"...Field validation for 'BatchId' failed on the 'required' tag"}}`

4. 更新素材

更新素材的名称。仅能更新当前令牌可见范围内的素材。

请求

POST /v1/assets/update

请求参数

参数	类型	必填	说明
id	string	是	素材 ID
name	string	是	新名称（上限 64 字符）

请求示例

响应示例

{
  "code": "success",
  "data": {
    "id": "asset-20260403150605-bfjwz"
  }
}

5. 删除素材

删除指定素材。仅能删除当前令牌可见范围内的素材。

请求

POST /v1/assets/delete

请求参数

参数	类型	必填	说明
id	string	是	素材 ID

请求示例

响应示例

{
  "code": "success",
  "data": {
    "id": "asset-20260403150605-bfjwz"
  }
}

6. 获取素材库列表

获取当前令牌的素材库分组列表。必须指定令牌（通过 API Key 自动识别，或 Playground 中选择令牌）。

注意：如果用户存在历史未绑定令牌的分组（token_id=0），接口会在列表头部返回一个合成的「历史分组」条目（id=-2），方便查看历史素材。新用户没有历史分组时，只返回令牌专属的自定义分组。

请求

GET /v1/assets/groups

请求参数

无需请求体。

请求示例

响应示例

{
  "code": "success",
  "data": [
    {
      "id": -2,
      "name": "历史分组",
      "group_name": "历史分组",
      "is_default": false,
      "asset_count": 12
    },
    {
      "id": 8,
      "name": "人像素材",
      "group_name": "user-10-token-5-人像素材",
      "is_default": false,
      "asset_count": 5
    },
    {
      "id": 12,
      "name": "风景素材",
      "group_name": "user-10-token-5-风景素材",
      "is_default": false,
      "asset_count": 3
    }
  ]
}

响应字段说明

字段	说明
id	素材库 ID（本地）。`-2` 为历史分组（合成条目），`> 0` 为自定义分组，可在创建素材、查询素材列表时作为 `group_id` 使用
name	素材库显示名称（如 `人像素材`），可直接展示给用户
group_name	素材库完整名称，格式为 `user-{用户ID}-token-{令牌ID}-{自定义名称}`
is_default	是否为默认素材库（固定返回 `false`）
asset_count	该素材库中的素材数量

说明

如果用户有历史分组（token_id=0），列表头部会包含 id=-2 的「历史分组」条目

新用户没有历史分组时，只返回令牌专属的自定义分组

不能在历史分组中创建新素材，仅用于查看和管理历史数据

查询历史分组的素材请使用「查询素材列表」接口，group_id 设为 -2

创建素材前需先通过此接口获取可用的 group_id（> 0），或通过「创建素材库」接口新建分组

7. 创建素材库

创建一个自定义素材库，归入当前令牌的专属区。创建后可在上传素材时通过 group_id 参数指定素材归属。

请求

POST /v1/assets/groups

请求参数

参数	类型	必填	说明
name	string	是	素材库名称

请求示例

响应示例

{
  "code": "success",
  "data": {
    "group_name": "user-10-token-5-人像素材"
  }
}

说明

素材库名称会自动添加前缀，格式为 user-{用户ID}-token-{令牌ID}-{自定义名称}

创建后通过「获取素材库列表」接口获取分配的 id，后续使用该 id 作为 group_id

新建的分组仅当前令牌可见，其他令牌无法访问

8. 转移素材库

将素材库分组转移到另一个令牌。

典型用途：

将历史分组移到某个令牌进行管理

在不同令牌之间调整素材分组归属

支持两种模式：

id > 0：转移指定的自建分组到目标令牌，自建分组可在令牌间双向互转

id = -2：将所有历史分组（token_id=0）整体转移到目标令牌，转移后历史分组消失，各分组以真实 ID 作为独立的自建分组展示

请求

POST /v1/assets/groups/transfer

请求参数

参数	类型	必填	说明
id	int	是	素材库 ID（通过获取素材库列表接口获得）。传 `-2` 可转移所有历史分组
token_id	int	是	目标令牌 ID，必须为正整数，且必须属于当前用户

请求示例

将分组移到令牌 5：

响应示例

{
  "code": "success"
}

说明

转移只修改本地归属记录，不影响上游素材数据

转移后，原令牌将无法看到该分组及其中的素材

目标令牌可通过分组列表访问该分组

目标令牌必须属于当前用户，否则返回错误

历史分组（id=-2）转移后，id=-2 条目消失，各分组以真实数据库 ID 独立展示

自建分组可在令牌之间双向互转，不限方向

素材库与令牌的关系

用户（User）
├── 令牌 A（Token）
│   ├── 自定义素材库 1（仅令牌 A 可见）
│   └── 自定义素材库 2（仅令牌 A 可见）
├── 令牌 B（Token）
│   └── 自定义素材库 3（仅令牌 B 可见）
└── 历史素材（token_id=0，升级前创建）
    └── 通过「历史分组」（id=-2）可见，可转移到具体令牌

创建素材时必须指定 group_id（> 0），需先通过「创建素材库」接口创建分组

group_id == -2 查询历史分组的素材

group_id <= 0（其他值）或不传时查询当前令牌的所有素材 + 历史素材

group_id > 0 查询指定分组，该分组必须在当前令牌可见范围内

分组可通过「转移素材库」接口在令牌之间转移

系统不再自动创建默认分组

获取分组列表时，如果用户有历史数据会自动包含「历史分组」条目

升级前后对比

行为	升级前	升级后
素材归属	按用户隔离，同一用户所有令牌共享	按令牌隔离，不同令牌各自独立
创建素材	不指定 group_id 时自动归入默认分组	必须指定 group_id，需先创建分组
历史素材	—	通过「历史分组」（`id=-2`）可见，可转移到令牌管理
asset:// 引用	正常使用	不受影响，历史引用继续有效
默认分组	系统自动创建	不再自动创建，需手动创建分组
自定义分组命名	`user-{uid}-{name}`	`user-{uid}-token-{tid}-{name}`
获取分组列表	返回所有分组（含默认）	返回令牌专属自定义分组 + 条件性「历史分组」
分组显示名称	需前端解析	接口直接返回 `name` 字段

9. 在视频生成中使用素材

素材上传并处于 Active 状态后，可通过 asset:// URL 在视频生成请求中引用。

请求

POST /v1/video/generations

图生视频示例（使用素材作为参考图）

响应示例

{
  "task_id": "cgt-20260403152344-dtdwq"
}

查询视频生成结果

成功响应示例

{
  "code": "success",
  "data": {
    "task_id": "cgt-20260403152344-dtdwq",
    "status": "SUCCESS",
    "progress": "100%",
    "data": {
      "id": "cgt-20260403152344-dtdwq",
      "model": "doubao-seedance-2-0-fast-260128",
      "status": "succeeded",
      "duration": 5,
      "resolution": "720p",
      "ratio": "16:9",
      "content": {
        "video_url": "https://ark-acg-cn-beijing.tos-cn-beijing.volces.com/...(签名URL，有效期24小时)"
      },
      "usage": {
        "total_tokens": 108900,
        "completion_tokens": 108900
      }
    }
  }
}

content 中支持的素材引用类型

type	role	说明
image_url	reference_image	参考图片
image_url	first_frame	首帧图片
image_url	last_frame	尾帧图片
video_url	reference_video	参考视频
audio_url	reference_audio	参考音频

每种类型的 URL 均支持 https:// 公网地址和 asset:// 素材库引用两种格式。

完整流程示例（Python）

以下示例演示完整流程：创建分组 → 上传图片素材 → 等待就绪 → 生成视频 → 获取结果。

完整流程示例（Java）

以下示例演示完整流程：创建分组 → 上传图片素材 → 等待就绪 → 生成视频 → 获取结果。

错误码

HTTP 状态码	错误信息	说明
400	group_id 必须指定，请先创建素材库分组	创建素材时未指定 group_id
400	请选择令牌	获取分组列表或创建分组时未选择令牌
400	asset_type 必须为 Image、Video 或 Audio	素材类型参数错误
400	urls 不能全为空	批量上传时 urls 数组为空或全为空白
400	单次批量最多提交 50 条素材	批量上传 urls 超过 50 条
400	批量上传仅支持 async 模式	批量上传显式传了 upload_mode=sync
400	批次不存在或无权访问	按批次查询时 batch_id 不存在或不属于当前令牌
400	参数错误	缺少必填字段或格式错误
400	target_token_id 必须为正整数	转移分组时目标令牌 ID 无效
400	分组名称不能为空	创建分组时 name 为空
400	token_id 格式错误	Playground 传入的 token_id 不是有效的正整数
403	未找到可用的素材资产渠道	管理员未配置素材资产渠道 AK/SK
403	无权访问此素材	素材不属于当前令牌的可见范围
403	无权访问该令牌的素材库	Playground 指定的令牌不属于当前用户
500	InvalidParameter.DownloadFailed	素材 URL 无法访问或下载失败
500	InvalidParameter.HeightTooSmall	图片高度不满足 300px ~ 6000px 要求
500	NotFound.asset_id	素材 ID 不存在

令牌隔离机制#

隔离规则#

全部素材#

历史数据兼容#

Playground（视频生成广场）#

认证方式#

基础地址#

1. 创建素材#

1.1 异步上传素材#

1.2 批量异步上传素材#

1.3 上传结果回调（Webhook）#

触发时机#

请求头#

回调载荷#

下游接收要求#

回调签名密钥（callback_secret，可选）#

验签示例（Python）#

回调地址要求#

1.4 异步上传素材（新）#

2. 查询素材列表#

3. 查询单个素材#

3.1 按批次查询素材#

4. 更新素材#

5. 删除素材#

6. 获取素材库列表#

7. 创建素材库#

8. 转移素材库#

素材库与令牌的关系#

升级前后对比#

9. 在视频生成中使用素材#

content 中支持的素材引用类型#

完整流程示例（Python）#

完整流程示例（Java）#

错误码#

令牌隔离机制

隔离规则

全部素材

历史数据兼容

Playground（视频生成广场）

认证方式

基础地址

1. 创建素材

1.1 异步上传素材

1.2 批量异步上传素材

1.3 上传结果回调（Webhook）

触发时机

请求头

回调载荷

下游接收要求

回调签名密钥（callback_secret，可选）

验签示例（Python）

回调地址要求

1.4 异步上传素材（新）

2. 查询素材列表

3. 查询单个素材

3.1 按批次查询素材

4. 更新素材

5. 删除素材

6. 获取素材库列表

7. 创建素材库

8. 转移素材库

素材库与令牌的关系

升级前后对比

9. 在视频生成中使用素材

content 中支持的素材引用类型

完整流程示例（Python）

完整流程示例（Java）

错误码