素材资源

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

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

MoonNexAI OSS 仅供联调和测试。OSS 上传和素材认证当前均免费，但 MoonNexAI 不承诺文件长期保存、URL 长期有效、持续可用性或长期存储服务等级。正式业务和长期使用请使用客户自有存储，并提供无需登录或额外请求头、可匿名公网访问的稳定直链。

什么时候使用素材

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

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

Seedance-2 与 Moon-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 不通用。
moon-2.0-wc 系列	moon-2.0-wc-720p、moon-2.0-wc-b-720p、moon-2.0-wc-b-720p-fast、moon-2.0-wc-c-720p、moon-2.0-wc-d-720p、moon-2.0-wc-e-720p、moon-2.0-wc-f-720p	支持	不作为当前输入路径	不建议	推荐公网 URL；七个型号均支持真人。基础、B 和 B Fast 最多 9 图 + 3 视频 + 3 音频且总计最多 12 个，其中 B / B Fast 不支持纯文本；F 最多 9 图 + 3 视频 + 3 音频，总计最多 12 个且音频必须带图片；C 最多 9 图且禁用视频/音频；D / E 最多 4 图 + 3 视频 + 1 音频且禁止纯音频。
moon-2.0-ld 系列	moon-2.0-ld-a	支持	支持	高级场景可用	推荐使用 references[]；图片最多 9 张、视频最多 3 个、音频最多 3 个，合计最多 15 个；音频应与图片或视频一起使用。
moon-2.0-am 系列	moon-2.0-am-720p-fast	支持	不作为当前输入路径	不建议	正式业务使用客户自有公网 URL；本地文件联调可用 mode=oss 获取临时测试 URL。适合单图、图片 + 背景音乐和多素材快速任务。

哪些组最适合 Asset://

• seedance-2.0-kz 系列最适合把素材接口接进长期工作流。
• seedance-2.0-cl 系列支持 mode=asset 创建图片和视频素材引用，但要按 CL 模型线单独创建或确认素材；不要和 seedance-2.0-kz 系列素材 ID 混用。seedance-2.0-cl-mini 使用同一套素材引用方式。
• moon-2.0-wc 系列适合按次计费的 720P 多素材组合任务。基础、B 和 B Fast 单次最多 12 个参考文件，其中图片最多 9 张、视频最多 3 个、音频最多 3 个；F 支持纯文本、真人和 4 到 15 秒，图片、视频、音频单类上限为 9、3、3 且总计最多 12 个；C 最多 9 张图片且不接受视频/音频；D / E 最多 4 图 + 3 视频 + 1 音频且禁止纯音频。正式业务使用客户自有公网 URL；mode=oss 仅用于本地文件联调。
• moon-2.0-ld-a 适合 720P 人物与姿势参考、多图片、多视频和背景音频组合；支持公网 URL、MoonNexAI 托管 URL 和模型可用的素材引用，单次素材合计最多 15 个。
• moon-2.0-am 系列适合 720P 按次快速多素材任务；正式业务使用客户自有公网 URL，mode=oss 仅用于本地文件联调。

上传素材

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

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

curl https://moonnexai.com/v1/assets/uploads \
  -H "Authorization: Bearer <MOONNEXAI_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	创建仅供测试的 MoonNexAI OSS URL，返回素材 ID。	免费。
asset	执行素材认证并创建 Asset://asset_xxx 素材引用。模型不支持时返回明确错误。	免费。
both	同时创建测试 OSS URL 和 Asset://asset_xxx 素材引用。	两个准备动作均免费。

mode=both 不建议作为默认选择。它会同时创建测试 OSS URL 和 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 通常更简单。

公网 URL 和二进制文件

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

• 已有公网 URL：直接在生成请求中传 URL。
• 生成接口支持 multipart/binary：按生成接口要求直接传文件。
• 仅在联调测试中需要临时 MoonNexAI OSS URL：调用 /v1/assets/uploads，使用 mode=oss。
• 需要 Asset://asset_xxx 素材引用：确认模型支持后调用 /v1/assets/uploads，使用 mode=asset。
• 联调时同时需要测试 OSS URL 和 Asset://asset_xxx：使用 mode=both，并处理两类准备状态。

OSS 上传和素材认证均不计费；后续视频或其他生成任务仍按对应模型计费。MoonNexAI OSS 不能替代客户自己的正式业务素材存储。

查询素材

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

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

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

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

文件建议

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

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