MoonApiX Docs

简体中文

English

简体中文

English

外观

准备素材 ​

为已创建的素材指定目标模型，建立或确认可用于生成的引用。每次继续使用同一个 asset_id，无需为了等待就绪重复上传。

发起或继续准备 ​

http
POST /v1/assets/{asset_id}/prepare
bash
curl https://moonapix.com/v1/assets/asset_xxx/prepare \
  -H "Authorization: Bearer <MOONAPIX_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{ "model": "seedance-2.5-cl" }'

model 必填，使用实际要生成的公开模型名。准备接口始终返回 V2，无需选择请求头；成功响应带 Asset-Contract: v2。目前不支持非空 config_id。

  • HTTP 200：已有可用准备结果，仍需检查下方就绪条件。
  • HTTP 202：尚未完成；间隔一段时间后再次对同一 ID、同一模型调用 Prepare。
  • 请求报错：按错误码处理；准备结果中的 error.retryable 表示该失败是否可重试。

判断是否可生成 ​

就绪响应的关键字段：

json
{
  "object": "asset",
  "asset_id": "asset_xxx",
  "asset_ref": "Asset://asset_xxx",
  "status": "ready",
  "storage": {
    "status": "ready"
  },
  "preparation": {
    "model": "seedance-2.5-cl",
    "status": "ready",
    "generation_ready": true,
    "review_status": "unknown"
  }
}

同时确认以下条件，再把 asset_ref 放入生成请求：

  1. 顶层 status=ready。
  2. preparation.model 是本次目标模型，preparation.status 为 ready 或 not_required。
  3. preparation.generation_ready=true。

storage.status 表示托管副本状态；审核结果 review_status 是独立证据。单独的存储就绪或审核通过不能代替上述条件；review_status=unknown 也不单独否定已确认的准备结果。

状态与下一步 ​

preparation.status含义下一步
not_started尚未准备。对同一 ID 调用 Prepare。
processing正在准备。间隔后再次调用 Prepare 继续处理。
ready / not_required已有引用或当前范围无需专用引用。同时确认 generation_ready=true，再生成。
unknown历史引用在当前模型和调用范围内尚未确认。调用 Prepare 确认可用性；等待查询不会补充证据。
failed此次准备失败。查看 preparation.error；仅在允许重试且原因已处理时重试，内容不合规时更换素材。

GET 查询只读取已保存结果，不启动、不轮询或推进准备。准备失败会保留已建立的素材身份和独立的存储结果。

高级：显式准备操作与失败恢复

通常省略 operation，复用有效引用或推进活动准备。需要明确控制时，可传 operation=create 建立初始引用、operation=rebuild 重建已失效引用，或 operation=refresh 查询已有有效引用；刷新失败不会覆盖原本有效的引用。

仅在错误允许重试且原因已经处理后重建。内容拒绝应更换素材，重建不能绕过内容限制。完整参数见 API Reference。

用于生成 ​

在目标模型支持的输入字段中显式传入引用。以下是图片参考项，需要放入该模型生成请求的 content 数组：

json
{
  "type": "image_url",
  "role": "reference_image",
  "image_url": {
    "url": "Asset://asset_xxx"
  }
}

仅在提示词中提到图片，或只设置输入模式，不会自动加载素材。完整生成参数见视频模型矩阵和对应模型页。

模型与复用范围 ​

同一个 MoonApiX 素材可以查询不同模型的准备结果。切换模型时保留 asset_id，对新的目标模型调用 Prepare；兼容的准备结果可以复用。

  • CL 系列（包括 seedance-2.5-cl）可在该范围复用；CL-B Fast / Mini 可在 CL-B 范围复用，CL 与 CL-B 准备范围隔离。
  • KZ、SZ 等模型的素材要求以各自模型说明为准。
  • SH 图片 AIGC Prepare 已验证就绪；视频 AIGC 准备尚未完成成功验收，音频使用稳定公网 URL。SH 不接受活体分组，普通准备不构成真人授权，详见 SH 模型说明。

就绪结果仅适用于当前模型、身份、API Key 权限和调用配置。多素材任务必须有同一条允许路径同时满足所有素材；生成时会重验权限和引用，不保证立即执行或改变正常调度。

相关页面 ​