上传与素材概览

上传与素材接口用于显式上传图片、音频、视频等文件，并在后续生成任务中复用。MoonApiX 不会因为你调用生成接口而自动创建托管 URL 或 Asset://asset_xxx 素材引用，素材是一个需要主动调用的能力。

什么时候使用素材

场景	建议
文件已有稳定公网 URL	直接在生成请求中传 URL，推荐优先使用这种方式。
只在一次任务中使用图片或音频	通常直接传 URL 更简单。
需要按素材 ID 管理用户资产	用已有公网 URL 调用 /v1/assets/uploads，保存返回的素材 ID。
目标模型明确支持素材引用	优先使用 mode=asset 创建 Asset://asset_xxx 素材引用。
外部 URL 可能过期，或必须由 MoonApiX 托管	优先使用 mode=oss 创建 MoonApiX 托管 URL。
同时需要 MoonApiX 托管 URL 和模型素材引用	才使用 mode=both；这是高级场景，不建议作为默认选择。

路由清单

方法	路径	用途
POST	/v1/assets/uploads	上传素材。
GET	/v1/asset-groups	查询素材分组。
POST	/v1/asset-groups	创建素材分组。
GET	/v1/asset-groups/{group_id}	查询素材分组详情。
PATCH	/v1/asset-groups/{group_id}	更新素材分组名称或说明。
GET	/v1/assets	查询素材列表。
GET	/v1/assets/{asset_id}	查询素材详情。
POST	/api/asset/createMedia	兼容素材创建入口。
GET	/api/asset/get	兼容素材查询入口。

场景入口

POST上传素材上传图片、音频或视频，获取 URL 或素材引用。GROUP素材分组创建分组，并用 group_id 隔离素材。GET查询素材读取素材列表、详情、状态和排障字段。

上传请求

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"
  }'

如果你的公网 URL 稳定可访问，推荐使用 JSON 请求创建素材 ID；MoonApiX 会保存你传入的 URL，不会默认转存到 MoonApiX 托管存储。

mode 说明

mode	行为	适合场景
asset	创建 Asset://asset_xxx 素材引用，保存你传入的公网 URL。	目标模型明确支持素材引用，且素材需要复用。
oss	创建 MoonApiX 托管 URL。	外部 URL 可能过期，或业务要求由 MoonApiX 托管。
both	同时创建托管 URL 和 Asset://asset_xxx 素材引用。	高级场景：同一素材既要直接访问，也要被模型引用。

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

创建 Asset://asset_xxx 后，素材可能还需要短暂准备才能用于视频生成。如果你立即提交视频任务遇到素材暂不可用的错误，请等待一小段时间后用同一个 Asset://asset_xxx 重试；通常不需要重新创建素材。

模型支持速查

不同视频模型对“上传素材”和“生成时引用素材”的支持边界不同。上传页只负责显式创建 MoonApiX 素材记录、托管 URL 或 Asset://asset_xxx；生成时是否能直接使用素材引用，以对应模型页为准。

模型	推荐上传模式	上传获取 Asset://	生成时使用 Asset://	建议
seedance-2.0-kz-fast	mode=asset 或 mode=both	支持	支持	需要长期复用素材时优先选这组。
seedance-2.0-kz	mode=asset 或 mode=both	支持	支持	适合更高质量任务和完整素材复用。
seedance-2.0-qm-720p	mode=asset	支持	支持	复杂多素材任务推荐先上传获取 Asset://asset_xxx，再写入 references[]。
seedance-2.0-cl-fast	mode=asset 或 mode=both	支持	支持	与 seedance-2.0-kz-fast 是不同模型线，素材 ID 不要跨线混用。
seedance-2.0-cl	mode=asset 或 mode=both	支持	支持	与 seedance-2.0-kz 是不同模型线，素材 ID 不要跨线混用。
seedance-2.0-cl-mini	mode=asset 或 mode=both	支持	支持	使用 CL 系列素材参数体系，支持图片和视频素材引用；素材 ID 不要和 seedance-2.0-kz 系列跨线混用。
seedance-2.0-ld-17	mode=oss 或直接 URL	不作为主路径	以模型页为准	适合公网 URL、MoonApiX 托管 URL、多视觉参考和轻量音频参考。
seedance-2.0-me	mode=oss 或直接 URL	不建议作为主路径	不建议作为主路径	推荐公网 URL 或 MoonApiX 托管 URL，不支持视频参考、尾帧和独立音频。

使用 Asset://asset_xxx 时，请按实际生成模型创建或确认素材。不同 Seedance-2 模型线的素材准备结果不跨线通用，例如 seedance-2.0-kz-fast 准备的素材不要直接当作 seedance-2.0-cl-fast 或 seedance-2.0-cl-mini 的素材使用。

素材分组

你可以创建自己的素材分组，并在上传、列表和详情查询中传入 group_id。同一个账号下，不同分组的素材会按 group_id 隔离；没有传 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",
    "domain": "media"
  }'

创建成功后保存返回的 group_id，上传时传入：

{
  "model": "seedance-2.0-kz-fast",
  "mode": "asset",
  "type": "image",
  "group_id": "group_xxx",
  "url": "https://example.com/reference.png"
}

查询详情时也可以带上 group_id：

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

如果素材不在该分组内，会返回未找到。详细字段见 素材分组。

状态判断

字段	常见值	说明
status	created、syncing、ready、failed	MoonApiX 素材记录状态。
sync_status	created、syncing、ready、failed	素材引用准备状态。
preparation_status	created、syncing、ready、failed、disabled	是否已经适合用于生成任务的准备状态。
generation_ready	true / false	是否建议立即放进生成请求。

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

status = ready
preparation_status = ready
generation_ready = true

如果 preparation_status=syncing 或 generation_ready=false，请等待一小段时间后重新查询同一个 asset_id，不要重复创建素材。

响应示例

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

相关页面

• 素材资源
• 视频模型矩阵
• 创建视频任务
• API Reference