MoonApiX Docs

简体中文

English

简体中文

English

外观

图像素材 ​

图像素材用于在图片编辑、图生图、视频参考和多步骤创作中复用图片文件。正式业务请使用客户自有存储的稳定公网 URL；MoonApiX OSS 上传仅供联调测试，不保证长期保存或持续可用。

状态和模型可用性 ​

素材详情里的 asset_id / asset_ref 是 MoonApiX 的素材身份和引用，不是其他服务的素材 ID。status=ready 只表示 MoonApiX 已建立素材身份和内容基线；storage.status=ready 只表示当前有一份已验证可访问的托管副本。这两个状态都不等于某个生成模型已经可以使用该素材。

如果要把素材用于需要准备的生成模型，请在详情请求中传入目标 model，再检查该模型返回的 preparation：通常应同时满足 preparation.status=ready 或 not_required，以及 preparation.generation_ready=true。generation_ready 是当前模型和调用范围下的可用性判断，不会改变正常调度，也不代表请求一定立即执行；生成前服务仍会重新验证。详细字段定义和兼容字段映射见查询素材。

上传、托管和模型准备是相互独立的操作。创建素材不会自动把它附加到后续图片或视频任务；创建任务时仍需显式传入公网 URL 或模型支持的 Asset://asset_xxx 引用。

常用入口 ​

方法路径用途
POST/v1/assets/uploads上传图片素材。
GET/v1/assets查询素材列表。
GET/v1/assets/{asset_id}查询素材详情。

上传示例 ​

bash
curl https://moonapix.com/v1/assets/uploads \
  -H "Authorization: Bearer <MOONAPIX_API_KEY>" \
  -F "file=@./product.png" \
  -F "type=image" \
  -F "purpose=image_reference" \
  -F "mode=oss"

接入建议 ​

  • 图片编辑和混合图可以直接使用公网 URL，也可以先上传为托管 URL。
  • 多次复用的图片建议保存素材 ID、URL、文件名和用途。
  • 用户删除素材后，业务侧应同步更新引用状态，避免继续提交失效 URL。

相关页面 ​