Skip to content

查询素材 ​

查看自己的素材,以及上传时已提交的模型准备结果。上传、续查和生成期间保存同一个 asset_id。

查询素材列表 ​

bash
curl "https://moonnexai.com/v1/assets?group_id=group_xxx&type=image&p=1&page_size=20" \
  -H "Authorization: Bearer <MOONNEXAI_API_KEY>"

列表查询参数 ​

参数说明
p页码,从 1 开始。
page_size每页数量,默认 10,最多 100。
group_id可选,当前账号的素材分组。
type可选,image、audio、video 或 file。
domain可选用途域,例如 media。
status可选素材记录状态。

分页使用 p,不是 page。

列表响应字段 ​

外层包含 object=list、data[]、本页数量 count、匹配总数 total 以及请求与跟踪 ID。素材数组是 data,不是 items。

查询素材详情 ​

bash
curl https://moonnexai.com/v1/assets/asset_xxx \
  -H "Authorization: Bearer <MOONNEXAI_API_KEY>"

详情查询参数 ​

路径使用自己的 asset_id,例如 asset_xxx。可选 group_id 用于校验分组;不匹配时返回未找到。新接入和已有客户端统一使用本站已注册的 /v1/assets/{asset_id} 入口。

详情沿用上传时选择的模型准备。追加另一个 model 查询参数不会为该模型建立准备。素材处于 syncing 时,详情查询会尝试同步已有准备;列表查询不执行这一步同步。

状态字段 ​

使用素材引用前,确认 status=ready、preparation_status=ready 且 generation_ready=true,并确认上传时选择的模型支持此引用。review_status / review_passed 是补充状态,不能替代准备结果;已返回审核失败或错误时先处理错误。只有 OSS URL 可用不等于任意模型都支持 Asset://。

状态下一步
status=ready、preparation_status=ready、generation_ready=true在支持的模型中使用引用,并显式填写媒体角色。
created / syncing保留 ID,短暂等待后继续查询详情,并设置重试次数或总时长上限。
preparation_status=failed 或 status=failed查看 sync_error 和错误信息,处理原因后再尝试。
disabled素材已停用,更新业务侧引用。
只有 generation_ready=false,没有明确处理中状态检查完整详情,不要假定所有 false 都能通过等待变为就绪。

审核通过不能覆盖准备失败;就绪也不保证生成成功或立即执行。只上传 OSS 的素材不能据此证明已完成目标模型认证。

响应示例 ​

json
{
  "object": "asset",
  "id": "asset_xxx",
  "asset_id": "asset_xxx",
  "asset_ref": "Asset://asset_xxx",
  "reference": "Asset://asset_xxx",
  "group_id": "group_xxx",
  "domain": "media",
  "asset_type": "image",
  "source_url": "https://example.com/reference.png",
  "url": "https://example.com/reference.png",
  "oss_url": "",
  "status": "ready",
  "sync_status": "ready",
  "preparation_status": "ready",
  "generation_ready": true,
  "review_status": "succeeded",
  "review_passed": true
}

素材字段 ​

字段说明
id / asset_idMoonNexAI 素材 ID。
asset_ref / reference模型支持时可放入生成输入的引用。
group_id、domain、asset_type分组、用途域和媒体类型。
source_url、url、oss_url原始与可用 URL,含义取决于上传模式。
content_type、size、durationMIME 类型、字节数、音视频时长(秒)。
status、preparation_status、generation_ready记录与准备结果;sync_status 是兼容准备字段。
review_status、review_passed、sync_error补充审核信息与准备错误。
request_id、trace_id排查问题时可提供的请求标识。

分组隔离 ​

查询范围属于当前认证账号。分组筛选只选择自己的分组;详情分组校验不会授予其他账号的素材访问权。

使用建议 ​

需要模型素材引用时,在上传请求中传入实际使用的 model 和 mode=asset;保存返回的 asset_id。处于 syncing 时继续查询同一 ID 的详情,详情查询会尝试同步已提交的准备结果。失败时查看 sync_error,不要无条件重复上传或继续生成。

输入 URL 的可用期应覆盖模型要求的时间;原始 URL 内容变化或过期会影响复用。重命名、移动与停用见管理素材。

素材分组 ​

创建和管理分组见素材分组。

相关页面 ​