素材库 API

创建和管理可复用素材，并在生成任务中使用统一素材 ID。

最后更新: 2026-08-06

核心概念

概念	标识示例	说明
素材组	group-1111111111111111111111111111111101	字符串公开 ID，格式为 group-{32位小写无连字符UUID}{2位数字}，用于组织当前账户素材。
素材	asset-aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa01	字符串公开 ID，格式为 asset-{32位小写无连字符UUID}{2位数字}；ACTIVE 状态时可在生成任务的 assetId 中引用。

素材使用流程

1
创建素材分组
按人物、产品或场景组织素材。
2
通过 URL 导入素材
平台先创建本地素材记录，再由后台异步同步到各处理通道。
3
等待素材可用
查询素材详情；status=ACTIVE 表示至少一个处理通道可用，syncStatus 描述全部处理通道的同步进度。
4
引用素材 ID
在视频生成请求的 content 中添加 asset 内容项并传入 EaseRouter 素材 ID。

V1.0 支持范围

仅支持通过以 http:// 或 https:// 开头的 URL 导入素材，暂不支持 multipart 文件上传或 Base64。
开放 image、video、audio 三种素材类型。
创建素材采用异步处理，接口返回 PROCESSING 后由后台完成同步。
素材源 URL 必须在同步期间保持可访问，并返回与声明类型一致的文件内容。
平台保存素材记录、用户归属、状态、映射；V1.0 不承诺将原始文件转存到 EaseRouter 自有 OSS。

分页查询素材组

POST/api/v1/assetGroup/page

按 ID 倒序查询当前账户未删除的素材组。

参数	类型	要求	说明
`pageNum`	integer	可选	页码，默认 1。
`pageSize`	integer	可选	每页数量，默认 10。

{ "pageNum": 1, "pageSize": 10 }

{
  "code": "SUCCESS",
  "msg": "操作成功",
  "result": [
    {
      "id": "group-1111111111111111111111111111111101",
      "name": "人物素材",
      "description": "品牌人物与角色参考素材",
      "groupType": "GENERAL",
      "status": "ACTIVE",
      "syncStatus": "READY",
      "createdAt": "2026-07-14 10:00:00"
    }
  ],
  "page": {
    "pageNum": 1,
    "pageSize": 10,
    "startRow": 0,
    "endRow": 1,
    "total": 1,
    "pages": 1
  }
}

素材组响应字段	类型	说明
id	string	素材组公开 ID，格式为 group-{32位小写无连字符UUID}{2位数字}。
name	string	素材组名称。
description	string	素材组说明。
groupType	string	GENERAL 或 HUMAN。
status	string	PENDING、ACTIVE、FAILED 或 DELETED；分页不会返回已删除记录。
syncStatus	string	全部处理通道的聚合同步状态，取值见“处理通道同步状态”。
createdAt	datetime	创建时间，格式 yyyy-MM-dd HH:mm:ss。

创建素材组

POST/api/v1/assetGroup/add

为当前账户创建本地素材组，并异步同步到已登记的处理通道。

参数	类型	要求	说明
`name`	string	必填	素材组名称，1-40 个字符。
`description`	string	可选	素材组说明，最多 120 个字符。

{
  "name": "人物素材",
  "description": "品牌人物与角色参考素材"
}

{
  "code": "SUCCESS",
  "msg": "操作成功",
  "result": {
    "id": "group-1111111111111111111111111111111101",
    "name": "人物素材",
    "description": "品牌人物与角色参考素材",
    "groupType": "GENERAL",
    "status": "PENDING",
    "syncStatus": "SYNCING",
    "createdAt": "2026-07-14 10:00:00"
  }
}

查询素材组详情

GET/api/v1/assetGroup/detail/{id}

按 group-{32位小写无连字符UUID}{2位数字} 格式的公开 ID 查询当前账户素材组。

{
  "code": "SUCCESS",
  "msg": "操作成功",
  "result": {
    "id": "group-1111111111111111111111111111111101",
    "name": "人物素材",
    "description": "品牌人物与角色参考素材",
    "groupType": "GENERAL",
    "status": "ACTIVE",
    "syncStatus": "READY",
    "createdAt": "2026-07-14 10:00:00"
  }
}

更新素材组

POST/api/v1/assetGroup/update

更新素材组名称或说明，请求体需包含素材组 ID。

参数	类型	要求	说明
`id`	string	必填	当前账户的素材组公开 ID，格式为 group-{32位小写无连字符UUID}{2位数字}。
`name`	string	必填	新名称，1-40 个字符。
`description`	string	可选	新说明，最多 120 个字符；传空字符串可清空。

{
  "code": "SUCCESS",
  "msg": "操作成功",
  "result": {
    "id": "group-1111111111111111111111111111111101",
    "name": "人物参考素材",
    "description": "",
    "groupType": "GENERAL",
    "status": "PENDING",
    "syncStatus": "SYNCING",
    "createdAt": "2026-07-14 10:00:00"
  }
}

删除素材组

POST/api/v1/assetGroup/delete

删除空素材组；HTTP 始终返回 200，以响应 code 判断结果。

{ "id": "group-1111111111111111111111111111111101" }

分页查询素材

POST/api/v1/asset/page

按 ID 倒序查询当前账户未删除的素材。

参数	类型	要求	说明
`pageNum`	integer	可选	页码，默认 1。
`pageSize`	integer	可选	每页数量，默认 10。
`groupId`	string	可选	按素材组公开 ID 精确筛选。
`status`	string	可选	按数据库状态精确筛选，请传 PROCESSING、ACTIVE 或 FAILED。

{
  "pageNum": 1,
  "pageSize": 10,
  "groupId": "group-1111111111111111111111111111111101",
  "status": "ACTIVE"
}

响应字段	类型	说明
id	string	素材公开 ID，格式为 asset-{32位小写无连字符UUID}{2位数字}。
groupId	string	所属素材组公开 ID，格式为 group-{32位小写无连字符UUID}{2位数字}。
name	string	素材名称。
assetType	string	IMAGE、VIDEO 或 AUDIO。
status	string	PROCESSING、ACTIVE、FAILED 或 DELETED；分页不会返回已软删除记录。
syncStatus	string	全部处理通道的聚合同步状态，取值见“处理通道同步状态”。
sourceUrl	string	导入素材时提交的来源 URL。
failureReason	string	失败原因；值为 null 时不会出现在响应中。
createdAt	datetime	创建时间，格式 yyyy-MM-dd HH:mm:ss。
updatedAt	datetime	更新时间，格式 yyyy-MM-dd HH:mm:ss。

{
  "code": "SUCCESS",
  "msg": "操作成功",
  "result": [
    {
      "id": "asset-bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb02",
      "groupId": "group-1111111111111111111111111111111101",
      "name": "品牌人物侧面照",
      "assetType": "IMAGE",
      "status": "FAILED",
      "syncStatus": "FAILED",
      "sourceUrl": "https://example.com/character-side.png",
      "failureReason": "当前服务不支持素材处理或请求参数无效",
      "createdAt": "2026-07-14 10:05:00",
      "updatedAt": "2026-07-14 10:05:02"
    }
  ],
  "page": {
    "pageNum": 1,
    "pageSize": 10,
    "startRow": 0,
    "endRow": 1,
    "total": 1,
    "pages": 1
  }
}

创建素材

POST/api/v1/asset/add

通过 HTTP/HTTPS 前缀 URL 创建素材，并返回 PROCESSING 状态的本地记录。

参数	类型	要求	说明
`groupId`	string	必填	当前账户下的素材组公开 ID，格式为 group-{32位小写无连字符UUID}{2位数字}。
`name`	string	必填	素材名称，1-60 个字符。
`assetType`	string	必填	素材类型：image、video 或 audio。
`sourceType`	string	可选	固定为 url，不传时默认 url。
`sourceUrl`	string	必填	以 http:// 或 https:// 开头的媒体地址，最多 2000 个字符；接口不判断公网、私网或可达性。

{
  "groupId": "group-1111111111111111111111111111111101",
  "name": "品牌主理人正面照",
  "assetType": "image",
  "sourceType": "url",
  "sourceUrl": "https://example.com/character.png"
}

{
  "code": "SUCCESS",
  "msg": "操作成功",
  "result": {
    "id": "asset-aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa01",
    "groupId": "group-1111111111111111111111111111111101",
    "name": "品牌主理人正面照",
    "assetType": "IMAGE",
    "status": "PROCESSING",
    "syncStatus": "SYNCING",
    "sourceUrl": "https://example.com/character.png",
    "createdAt": "2026-07-14 10:04:00",
    "updatedAt": "2026-07-14 10:04:00"
  }
}

查询素材详情

GET/api/v1/asset/detail/{id}

按 asset-{32位小写无连字符UUID}{2位数字} 格式的公开 ID 查询当前账户素材。

{
  "code": "SUCCESS",
  "msg": "操作成功",
  "result": {
    "id": "asset-aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa01",
    "groupId": "group-1111111111111111111111111111111101",
    "name": "品牌主理人正面照",
    "assetType": "IMAGE",
    "status": "ACTIVE",
    "syncStatus": "READY",
    "sourceUrl": "https://example.com/character.png",
    "createdAt": "2026-07-14 10:04:00",
    "updatedAt": "2026-07-14 10:04:18"
  }
}

更新素材

POST/api/v1/asset/update

更新当前账户下的素材名称，请求体需包含素材 ID。

参数	类型	要求	说明
`id`	string	必填	当前账户的素材公开 ID，格式为 asset-{32位小写无连字符UUID}{2位数字}。
`name`	string	必填	新的素材名称，1-60 个字符。

{
  "id": "asset-aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa01",
  "name": "品牌人物主视觉"
}

{
  "code": "SUCCESS",
  "msg": "操作成功",
  "result": {
    "id": "asset-aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa01",
    "groupId": "group-1111111111111111111111111111111101",
    "name": "品牌人物主视觉",
    "assetType": "IMAGE",
    "status": "PROCESSING",
    "syncStatus": "SYNCING",
    "sourceUrl": "https://example.com/character.png",
    "createdAt": "2026-07-14 10:04:00",
    "updatedAt": "2026-07-14 10:04:18"
  }
}

删除素材

POST/api/v1/asset/delete

删除当前账户素材；HTTP 始终返回 200，以响应 code 判断结果。

{ "id": "asset-aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa01" }

平台仅把素材标记为 DELETED 并写入 deletedAt，以保留生成任务、账单和审计所需的历史关联。已删除素材不能再用于创建新任务；当前后端不会自动清理来源文件或处理通道资源。

素材状态

状态	是否可用于生成	说明
PROCESSING	否	本地记录已创建，异步消费者正在提交或同步。
ACTIVE	取决于路由	至少一个处理通道的素材映射已可用；创建任务时仍会校验所选模型路由对应的映射。
FAILED	否	素材处理失败，可读取 failureReason。
DELETED	否	素材已软删除，不会再出现在列表和详情接口。

处理通道同步状态

syncStatus	说明
SYNCING	当前没有可用映射，至少一个处理通道正在等待提交、已经提交、处理中、等待前置资源或等待技术重试。
READY	当前登记的所有处理通道映射均已可用。
PARTIAL	至少一个处理通道映射已可用，但并非全部可用；业务 status 通常为 ACTIVE。
WAITING_CONFIG	当前没有可用映射，且同步因处理通道配置尚未就绪而等待。
FAILED	当前没有可用映射，且已无正在同步或等待配置的映射。

在生成任务中使用素材

POST/api/v1/video/task/create

使用 ACTIVE 状态的当前账户素材 ID 创建视频生成任务。

{
  "model": "doubao-seedance-2-0-260128",
  "content": [
    {
      "type": "text",
      "text": "参考图片1中的人物，让人物自然转身并看向镜头，镜头缓慢推进"
    },
    {
      "type": "asset",
      "assetId": "asset-aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa01",
      "role": "reference_image"
    }
  ],
  "resolution": "720p",
  "ratio": "16:9",
  "duration": 5,
  "watermark": false
}

仅 type=asset 的内容项需要素材映射。平台会先确定当前模型的所选路由，再校验素材归属、ACTIVE 状态、实际媒体类型、role，以及该路由对应处理通道的素材映射是否为可用状态。status=ACTIVE、syncStatus=PARTIAL 只表示部分处理通道已可用，并不保证当前所选路由可用。

素材业务失败

HTTP	业务 code	当前 msg 场景
200	FAIL	媒体地址未以 http:// 或 https:// 开头、素材组不存在、素材不存在、素材组仍包含素材、真人素材组尚未认证成功、素材无权访问或尚未可用，或素材尚未同步到所选模型路由对应的处理通道。
200	INTERNAL_SERVER_ERROR	未处理的程序异常。