查询素材列表

状态

本文记录已接入的 Modelflare 素材管理接口。调用需要有效的媒体 API Key、可用媒体渠道和对应权限。

注意

网关会记录服务方素材 ID、状态和用户归属；现有 Castaly 本地素材库与服务方素材命名空间保持分离。

接口

POST https://modelflare.dev/volc/asset/ListAssets

鉴权

使用 Modelflare API Key：

bash

-H "Authorization: Bearer YOUR_MODELFLARE_API_KEY"

创建、更新和删除请求建议携带 Idempotency-Key。同一用户使用相同 Key 重试时，网关会重放已保存响应，不重复创建或删除。

请求

按名称、素材组和素材组类型筛选素材。只有 Status: Active 后，才能在 Seedance 请求中使用素材 ID。

字段	类型	必填	说明	示例
model	string	是	计费模型，默认值为 volc-asset。	volc-asset
Filter.Name	string	否	按素材名称模糊匹配。	character
Filter.GroupIds	string[]	否	按素材组 ID 列表筛选。	["group-20260320141746-zsf6b"]
Filter.GroupType	AIGC	LivenessFace	否	按素材组类型筛选。
PageNumber	integer	否	页码，默认值为 1。	1
PageSize	integer	否	每页数量，默认值为 10。	10

JSON 示例：

JSON

{
  "model": "volc-asset",
  "Filter": {
    "Name": "character",
    "GroupIds": [
      "group-20260320141746-zsf6b"
    ],
    "GroupType": "AIGC"
  },
  "PageNumber": 1,
  "PageSize": 10
}

cURL 示例：

bash

curl --request POST https://modelflare.dev/volc/asset/ListAssets \
  --header "Authorization: Bearer YOUR_MODELFLARE_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
  "model": "volc-asset",
  "Filter": {
    "Name": "character",
    "GroupIds": [
      "group-20260320141746-zsf6b"
    ],
    "GroupType": "AIGC"
  },
  "PageNumber": 1,
  "PageSize": 10
}'

响应

请求成功。

字段	类型	必填	说明	示例
Items[]	object[]	否	包含素材 ID、名称、类型、所属组、状态、项目和时间戳的素材对象。	{ Id, Name, AssetType, GroupId, Status, ... }
Items[].Id / Name	string	否	素材 ID 和展示名称。	asset-20260528140922-d9646 / character-reference
Items[].AssetType / GroupId	string	否	素材类型和所属素材组。	Image / group-20260320141746-zsf6b
Items[].Status / ProjectName	string	否	处理状态和项目名称。	Active / default
Items[].CreateTime / UpdateTime	string	否	ISO 8601 创建和更新时间。	2026-03-20T14:25:01Z
Items[].URL	string	否	临时文件 URL，文档标注有效期为 12 小时；生成请求请使用 asset://<ID>。	https://example.com/temporary-asset
Items[].Error	object	否	当 Status 为 Failed 时返回包含 Code 和 Message 的处理错误。	{ Code, Message }
PageNumber	integer	否	返回页码。	1
PageSize	integer	否	返回每页数量。	10
TotalCount	integer	否	匹配的素材总数。	2

响应示例：

JSON

{
  "Items": [
    {
      "Id": "asset-20260528140922-d9646",
      "Name": "character-reference",
      "AssetType": "Image",
      "GroupId": "group-20260320141746-zsf6b",
      "Status": "Active",
      "ProjectName": "default"
    }
  ],
  "PageNumber": 1,
  "PageSize": 10,
  "TotalCount": 1
}

错误

状态码	含义
400	请求参数无效。
401	API Key 缺失或未授权。

错误体示例（接口返回时）：

JSON

{
  "error": {
    "code": "invalid_request",
    "message": "Request validation failed."
  }
}

创建图片、视频和音频是异步的：收到素材 ID 后，先调用 GetAsset，只有 Active 状态才能把它放进 Seedance 的 asset://<ID> 引用。