查询素材
查看自己的素材,以及上传时已提交的模型准备结果。上传、续查和生成期间保存同一个 asset_id。
查询素材列表
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。
查询素材详情
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 的素材不能据此证明已完成目标模型认证。
响应示例
{
"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_id | MoonNexAI 素材 ID。 |
asset_ref / reference | 模型支持时可放入生成输入的引用。 |
group_id、domain、asset_type | 分组、用途域和媒体类型。 |
source_url、url、oss_url | 原始与可用 URL,含义取决于上传模式。 |
content_type、size、duration | MIME 类型、字节数、音视频时长(秒)。 |
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 内容变化或过期会影响复用。重命名、移动与停用见管理素材。
素材分组
创建和管理分组见素材分组。