素材资源

素材资源接口用于显式上传图片、音频、视频等文件，并在后续生成任务中复用。上传成功后，MoonApiX 会返回素材 ID、可访问 URL、素材引用和状态信息。

MoonApiX 不会在视频生成时自动替你创建托管 URL 或 Asset://asset_xxx 素材引用。你可以直接在生成请求中传自己的公网 URL；如果某个生成接口支持二进制文件，也可以按该接口要求直接提交文件。只有当你明确调用素材上传接口时，才会创建 MoonApiX 托管 URL 或素材引用。

什么时候使用素材

• 同一张图片或同一段音频会被多次使用。
• 生成接口需要稳定引用文件，避免外部 URL 过期。
• 业务系统希望按素材 ID 管理用户素材。
• 目标模型明确支持 Asset://asset_xxx 素材引用。
• 数字人形象、克隆音色、图生视频等任务需要先准备文件。

如果只是一次性图生视频，且文件已经有稳定公网 URL，通常不需要先创建素材。

Seedance-2 素材策略

分组速查表

分组	代表模型	mode=oss	mode=asset	mode=both	使用建议
seedance-2.0-kz 系列	seedance-2.0-kz-fast、seedance-2.0-kz	支持	支持	高级场景可用	需要素材复用时优先选这组。
seedance-2.0-cl 系列	seedance-2.0-cl-fast、seedance-2.0-cl、seedance-2.0-cl-mini	支持	支持	高级场景可用	支持标准素材创建和引用；seedance-2.0-cl-mini 支持 480P / 720P，时长 4 - 15 秒；与 seedance-2.0-kz 系列素材 ID 不通用。
seedance-2.0-ld 系列	seedance-2.0-ld-17	支持	不作为主路径	不建议	适合公网 URL、MoonApiX 托管 URL、多视觉参考和轻量音频参考。
seedance-2.0-qm 系列	seedance-2.0-qm-720p	支持	支持	高级场景可用	多素材组合任务推荐先上传获取 Asset://asset_xxx。
seedance-2.0-wc 系列	seedance-2.0-wc-720p	支持	不作为当前输入路径	不建议	9 图 + 3 视频 + 3 音频组合推荐使用公网 URL；本地文件可用 mode=oss 获取 MoonApiX 托管公网 URL。
seedance-2.0-me	seedance-2.0-me	支持	不建议作为主路径	不建议	推荐公网 URL 或 MoonApiX 托管 URL；不支持视频参考、尾帧和独立音频。

哪些组最适合 Asset://

• seedance-2.0-kz 系列最适合把素材接口接进长期工作流。
• seedance-2.0-cl 系列支持 mode=asset 创建图片和视频素材引用，但要按 CL 模型线单独创建或确认素材；不要和 seedance-2.0-kz 系列素材 ID 混用。seedance-2.0-cl-mini 使用同一套素材引用方式。
• seedance-2.0-qm 系列适合把素材接口接进多素材组合工作流，先上传获取 Asset://asset_xxx，再在视频任务中写入 references[]。
• seedance-2.0-wc 系列适合按次计费的 720P 多素材组合任务，最多 9 图 + 3 视频 + 3 音频，但当前推荐传公网 URL；本地文件先用 mode=oss 转成 MoonApiX 托管公网 URL。

上传素材

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

使用已有公网 URL 创建素材引用：

curl https://moonapix.com/v1/assets/uploads \
  -H "Authorization: Bearer <MOONAPIX_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-2.0-kz-fast",
    "mode": "asset",
    "type": "image",
    "url": "https://example.com/reference.png"
  }'

常用字段：

字段	类型	说明
file	file	要上传的文件。
url	string	可选。已有公网文件 URL。使用 JSON 请求时常用。
model	string	可选。需要创建素材引用时建议传入目标模型名。
type	string	素材类型，常见值为 image、audio、video。
purpose	string	可选。素材用途，例如 video_reference、digital_human_avatar、voice_training。
mode	string	可选。oss、asset 或 both。默认以接口当前配置为准，建议显式传入。

mode 说明：

mode	行为	计费动作
oss	创建 MoonApiX 托管 URL，返回可复用的素材 ID。	成功后按 asset_upload_oss 计费。
asset	创建 Asset://asset_xxx 素材引用。模型不支持时返回明确错误。	素材 ready 后按 asset_create_media 计费。
both	同时创建 MoonApiX 托管 URL 和 Asset://asset_xxx 素材引用。	两个动作分别计费，仅建议高级场景使用。

mode=both 不建议作为默认选择。它会同时创建 MoonApiX 托管 URL 和 Asset://asset_xxx 模型素材引用，可能分别产生 asset_upload_oss 和 asset_create_media 费用；任一动作失败都会影响最终可用性。只有本地文件或不稳定 URL 必须由 MoonApiX 托管，同时目标模型又需要 Asset://asset_xxx 素材引用时才使用。

成功响应示例：

{
  "id": "asset_xxx",
  "object": "asset",
  "type": "image",
  "url": "https://example.com/assets/asset_xxx.png",
  "reference": "Asset://asset_xxx",
  "status": "ready",
  "sync_status": "ready",
  "preparation_status": "ready",
  "generation_ready": true,
  "trace_id": "2026060301010100000000000000000000",
  "created_at": 1710000000
}

如果 mode=asset 或 mode=both 需要异步准备，初始状态可能是 created 或 syncing，review_status 可能是 pending。只有 generation_ready=true 且 preparation_status=ready 的素材才适合立即用于要求素材引用的模型。review_passed=true 只表示审核已通过；如果随后同步到生成引擎失败，响应会返回 preparation_status=failed、generation_ready=false 和 sync_error。

引用素材

生成接口中可以直接使用 Asset://asset_xxx：

{
  "model": "seedance-2.0-kz-fast",
  "prompt": "Turn this product image into a short premium ad shot.",
  "image": "Asset://asset_xxx",
  "duration": 5,
  "aspect_ratio": "16:9"
}

素材不会因为审核通过或 generation_ready=true 就自动加载到后续视频任务。每一次生成请求都必须显式传入素材引用或素材 URL；只写 input_type: "reference" 不会关联最近上传或最近审核通过的素材。

Seedance-2 参考图视频示例：

{
  "model": "seedance-2.0-kz-fast",
  "prompt": "图中女孩对着镜头说“茄子”，360度环绕运镜",
  "mode": "fast",
  "resolution": "720p",
  "ratio": "adaptive",
  "duration": 5,
  "generate_audio": true,
  "watermark": false,
  "web_search": false,
  "input_type": "reference",
  "generation_type": "video",
  "content": [
    {
      "type": "image_url",
      "role": "reference_image",
      "image_url": {
        "url": "Asset://asset_xxx"
      }
    }
  ]
}

如果希望素材作为首帧，请把 role 改为 first_frame，或使用 first_frame_url: "Asset://asset_xxx"。

部分接口也支持直接传公网 URL。对于长期业务流程，可以使用素材 ID，便于追踪和复用；对于一次性任务，直接传 URL 通常更简单，也不会产生 MoonApiX 托管 URL 的上传费用。

公网 URL 和二进制文件

素材接口不是所有文件输入的必经步骤：

• 已有公网 URL：直接在生成请求中传 URL。
• 生成接口支持 multipart/binary：按生成接口要求直接传文件。
• 需要 MoonApiX 托管 URL：调用 /v1/assets/uploads，使用 mode=oss。
• 需要 Asset://asset_xxx 素材引用：确认模型支持后调用 /v1/assets/uploads，使用 mode=asset。
• 同时需要托管 URL 和 Asset://asset_xxx：使用 mode=both，并确认可以接受两类计费和两类准备状态。

只要你显式创建 MoonApiX 托管 URL，就会按 asset_upload_oss 计费。二进制文件直接提交给生成接口，不等同于创建 MoonApiX 托管 URL。

查询素材

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

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

列表接口支持分页。你可以按素材类型筛选，也可以在自己的业务系统中保存 asset_id 与订单、用户或项目的对应关系。

查询响应会带 trace_id 或响应头 X-MoonApiX-Trace-Id。如果素材同步失败，或 review_status=failed，请保留 asset_id、trace_id 和接口原始响应，方便排查。

文件建议

类型	建议
图片	使用清晰主体，避免过度压缩；商品图建议背景干净。
音频	使用清晰人声，减少混响、噪声和背景音乐。
视频	保持主体稳定，避免强遮挡和频繁切镜。

更多参数和响应结构见 API Reference。