查询素材

素材查询用于读取素材列表、素材详情和素材状态。需要在生成任务中复用素材时，建议先确认素材已经可用。

查询素材列表

GET /v1/assets

curl "https://moonapix.com/v1/assets?type=image&page=1&page_size=20" \
  -H "Authorization: Bearer <MOONAPIX_API_KEY>"

如果素材在自建分组中，可以加上 group_id：

curl "https://moonapix.com/v1/assets?group_id=group_xxx&type=image&page=1&page_size=20" \
  -H "Authorization: Bearer <MOONAPIX_API_KEY>"

列表查询参数

参数	类型	必填	说明
group_id	string	否	素材分组 ID。传入后只返回该分组下的素材；不传时查询默认分组。
type	string	否	素材类型。常见值为 image、audio、video、file。
status	string	否	素材状态。常见值为 created、syncing、ready、failed、disabled。
domain	string	否	素材用途域。常见值为 media。
page	integer	否	页码，默认 1。
page_size	integer	否	每页数量，默认 20。

列表响应字段

字段	类型	说明
object	string	固定为 list。
data	array	素材数组。每一项字段见下方“素材字段”。
count	integer	当前页返回数量。
total	integer	符合条件的素材总数。
page	integer	当前页码。
page_size	integer	每页数量。
request_id	string	请求 ID。排查问题时提供。
trace_id	string	跟踪 ID。排查问题时提供。

查询素材详情

GET /v1/assets/{asset_id}

curl https://moonapix.com/v1/assets/asset_xxx \
  -H "Authorization: Bearer <MOONAPIX_API_KEY>"

需要校验素材是否属于某个分组时，可以在详情查询中传 group_id。如果素材不在该分组中，会返回未找到。

curl "https://moonapix.com/v1/assets/asset_xxx?group_id=group_xxx" \
  -H "Authorization: Bearer <MOONAPIX_API_KEY>"

兼容入口：

GET /api/asset/get

详情查询参数

参数	类型	必填	说明
group_id	string	否	用于校验素材是否属于指定分组。素材不在该分组内时会返回未找到。

素材字段

字段	说明
object	对象类型，通常为 asset。
id	素材 ID，格式为 asset_xxx。
asset_id	素材 ID，和 id 等价。
group_id	素材所属分组 ID。
domain	素材用途域。常见值为 media。
type / asset_type	素材类型，常见值为 image、audio、video、file。
name	素材名称。
description	素材说明。
source_url	你创建素材时传入的原始公网 URL。
url	客户可用 URL。mode=asset 时通常等于 source_url；mode=oss 或 mode=both 时通常是 MoonApiX 托管 URL。
oss_url	MoonApiX 托管 URL。只有 mode=oss 或 mode=both 时通常有值。
reference / asset_ref	可用于部分生成接口的素材引用，格式为 Asset://asset_xxx。
content_type	文件 MIME 类型。
size	文件大小，单位字节。
duration	音频或视频时长，单位秒。
status	素材记录状态。常见值见下方状态表。
sync_status	素材引用准备状态。
preparation_status	生成前准备状态。
generation_ready	是否建议立即用于生成请求。
review_status	素材审核/可用性结果。常见值为 succeeded、pending、failed、unknown。
review_passed	是否已通过素材审核/可用性检查。
visibility	可见性。通常为 private。
created_at	创建时间。
updated_at	更新时间。
request_id	请求 ID。排查问题时提供。
trace_id	跟踪 ID。排查问题时提供。

状态字段

字段	常见值	说明
status	created、syncing、ready、failed、disabled	素材记录状态。
sync_status	created、syncing、ready、failed	素材引用准备状态。
preparation_status	created、syncing、ready、failed、disabled	是否已经适合用于生成任务的准备状态。
generation_ready	true / false	是否建议立即放进生成请求。
review_status	succeeded、pending、failed、unknown	素材审核结果。succeeded 表示素材审核已通过，但不等于已经完成生成前同步。
review_passed	true / false	是否已通过素材审核/可用性检查。
sync_error	string	素材同步失败原因。仅失败时通常有值。

用于视频生成前，建议同时确认：

status = ready
preparation_status = ready
generation_ready = true
review_status = succeeded
review_passed = true

如果 preparation_status=syncing 或 generation_ready=false，请等待一小段时间后重新查询同一个 asset_id。不要为了等待 ready 反复创建新素材。如果 preparation_status=failed，请查看 sync_error，更换素材或检查素材 URL 是否可公开访问。

有些素材服务会先返回“素材已过审”，随后在同步到生成引擎时失败。例如图片命中版权或内容策略时，可能出现：

{
  "status": "failed",
  "preparation_status": "failed",
  "generation_ready": false,
  "review_status": "succeeded",
  "review_passed": true,
  "sync_error": "InputImageSensitiveContentDetected.PolicyViolation: The request failed because the input image may be related to copyright restrictions."
}

这种情况表示素材审核通过，但不能用于生成；请以 generation_ready 和 preparation_status 判断是否可生成。

响应示例

{
  "id": "asset_xxx",
  "asset_id": "asset_xxx",
  "object": "asset",
  "type": "image",
  "asset_type": "image",
  "group_id": "group_xxx",
  "domain": "media",
  "name": "reference.png",
  "description": "",
  "source_url": "https://example.com/reference.png",
  "url": "https://example.com/reference.png",
  "oss_url": "",
  "reference": "Asset://asset_xxx",
  "asset_ref": "Asset://asset_xxx",
  "content_type": "image/png",
  "size": 245678,
  "duration": 0,
  "status": "ready",
  "sync_status": "ready",
  "preparation_status": "ready",
  "generation_ready": true,
  "visibility": "private",
  "created_at": 1710000000,
  "updated_at": 1710000000,
  "request_id": "2026060301010100000000000000000000",
  "trace_id": "2026060301010100000000000000000000"
}

分组隔离

group_id 是客户侧自定义分组 ID。上传素材时传入 group_id 后，列表和详情查询也建议带同一个 group_id。

场景	结果
列表查询传 group_id=group_xxx	只返回该分组下的素材。
详情查询传正确 group_id	正常返回素材详情。
详情查询传错误 group_id	返回未找到，可用于校验业务侧保存关系。
不传 group_id	使用默认分组。

使用建议

• 生成任务前确认 generation_ready=true。
• 如果刚创建的 Asset://asset_xxx 暂时不能用于视频生成，请等待一小段时间后用同一个素材引用重试。
• 在业务系统保存素材 ID、分组 ID、用途、用户或项目的对应关系。
• 如果素材准备失败，请保存 asset_id、trace_id 和接口原始响应。

素材分组

GET /v1/asset-groups
POST /v1/asset-groups
GET /v1/asset-groups/{group_id}
PATCH /v1/asset-groups/{group_id}

创建分组示例：

curl https://moonapix.com/v1/asset-groups \
  -H "Authorization: Bearer <MOONAPIX_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "project-a",
    "description": "Project A materials"
  }'

相关页面

• 上传素材
• 上传与素材概览
• 视频模型矩阵
• API Reference