查询素材

状态

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

注意

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

接口

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

鉴权

使用 Modelflare API Key：

bash

-H "Authorization: Bearer YOUR_MODELFLARE_API_KEY"

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

请求

按 ID 查询单个素材。用于轮询异步上传，直到 Status 变为 Active 或 Failed。

字段	类型	必填	说明	示例
Id	string	是	要查询的素材 ID。	asset-20260528140922-d9646

JSON 示例：

JSON

{
  "Id": "asset-20260528140922-d9646"
}

cURL 示例：

bash

curl --request POST https://modelflare.dev/volc/asset/GetAsset \
  --header "Authorization: Bearer YOUR_MODELFLARE_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
  "Id": "asset-20260528140922-d9646"
}'

响应

请求成功。

字段	类型	必填	说明	示例
Id	string	是	素材 ID。	asset-20260528140922-d9646
Name	string	否	素材名称。	character-reference
URL	string	否	临时文件 URL，文档标注有效期为 12 小时；不要将其保存为生成请求的长期引用。	https://example.com/temporary-asset
AssetType	Image	Video	Audio	否
GroupId	string	否	所属素材组 ID。	group-20260320141746-zsf6b
Status	Processing	Active	Failed	否
ProjectName	string	否	项目名称。	default
CreateTime / UpdateTime	string	否	ISO 8601 时间戳。	2026-05-28T06:09:31Z

响应示例：

JSON

{
  "Id": "asset-20260528140922-d9646",
  "Name": "character-reference",
  "AssetType": "Image",
  "GroupId": "group-20260320141746-zsf6b",
  "Status": "Active",
  "ProjectName": "default",
  "CreateTime": "2026-05-28T06:09:22Z",
  "UpdateTime": "2026-05-28T06:09:31Z"
}

错误

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

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

JSON

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

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