素材资源

素材资源接口用于显式上传图片、音频、视频等文件，并在后续生成任务中复用。素材 ID 和引用属于 MoonApiX；获得 ID 或 status=ready 本身不能证明素材已满足目标模型的生成要求。

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

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

本页的 mode=oss|asset|both 请求和顶层状态示例属于旧兼容契约。V2 已在当前素材接口版本生效，创建、归档与准备相互独立；版本选择和适用范围见 上传素材，三层状态见 查询素材。

V2 的 status=ready 表示素材身份和内容基线已建立，storage.status=ready 表示托管副本已验证可用；只有指定目标 model 时才返回 preparation。asset_id / asset_ref 是 MoonApiX 客户侧身份，不是其他服务的素材 ID。客户端应按实际生成模型确认 preparation.status ∈ {ready, not_required} 且 generation_ready=true；同一个 MoonApiX asset_id 可以继续复用，无需因为换模型就重新创建素材身份，但仍需按目标模型重新查询。多素材必须在同一可用路径上同时满足条件。

什么时候使用素材

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

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

Seedance-2 与 Moon-2 素材策略

seedance-2.0-sh、seedance-2.0-sh-fast、seedance-2.0-sh-mini 和 seedance-2.5-sh 已验证图片 AIGC 素材准备就绪，视频 AIGC 准备尚未完成成功验收。上传成功、图片准备就绪均不证明视频参考生成已验收。按实际目标模型显式 Prepare 并查询准备结果，不能仅看素材身份 status=ready。音频使用稳定公网 URL。这些模型未开放真人扫脸／活体认证，普通 AIGC 认证不能代替真人活体认证，也不能使用其他模型的活体分组。详见 SH 模型说明。

分组速查表

分组	代表模型	mode=oss	mode=asset	mode=both	使用建议
seedance-2.0-sz 系列	seedance-2.0-sz、seedance-2.0-sz-fast、seedance-2.0-sz-mini	可选中转	支持	高级场景可用	按实际生成模型创建图片、视频或音频素材；最多 9 图 + 3 视频 + 3 音频，合计最多 15 个。
seedance-2.5-sz	seedance-2.5-sz	可选中转	支持	高级场景可用	按 seedance-2.5-sz 单独准备素材；最多 30 图 + 10 视频 + 10 音频，合计最多 50 个。
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.5-cl	支持	支持	高级场景可用	CL 型号共享素材兼容范围；无需逐型号重复认证。CL 与 CL-B、KZ 范围隔离；生成前查询目标模型准备状态。
seedance-2.0-cl-b 系列	seedance-2.0-cl-b-fast、seedance-2.0-cl-b-mini	支持	支持	高级场景可用	CL-B 型号共享素材兼容范围；与 CL、KZ 等范围隔离。生成前查询目标模型准备状态。
seedance-2.0-gl 系列	seedance-2.0-gl、seedance-2.0-gl-fast、seedance-2.0-gl-mini	可选中转	支持	高级场景可用	客户自有稳定公网 URL 优先；需要素材 ID 时按目标模型创建，最多 9 图 + 3 视频 + 3 音频、合计 15 个。
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、moon-2.0-ld-b	支持	支持	高级场景可用	两个型号能力相同；推荐使用 references[]；图片最多 9 张、视频最多 3 个、音频最多 3 个，合计最多 15 个；音频应与图片或视频一起使用。
moon-2.0-am 系列	moon-2.0-am-720p-fast	支持	不作为当前输入路径	不建议	正式业务使用客户自有公网 URL；本地文件联调可用 mode=oss 获取临时测试 URL。适合单图、图片 + 背景音乐和多素材快速任务。
moon-2.0-me 系列	moon-2.0-me-a-720p、moon-2.0-me-b-720p、moon-2.0-me-a-fast	支持	按模型能力为准	高级场景可用	A / A Fast 最多 9 张图片；B 最多 9 图 + 3 视频 + 3 音频，合计最多 15 个；推荐使用 references[] 和稳定公网 URL。

哪些组最适合 Asset://

• seedance-2.0-sz、seedance-2.0-sz-fast、seedance-2.0-sz-mini 和 seedance-2.5-sz 均支持按目标模型执行 mode=asset 素材认证。三类素材混合任务必须在生成请求中显式传入图片、视频和音频引用；审核或准备完成不会自动附加到后续任务。
• seedance-2.0-kz 系列最适合把素材接口接进长期工作流。
• seedance-2.0-cl 系列（包括 seedance-2.5-cl）共享一个素材兼容范围，已建立的准备结果可以跨这些型号复用，无需重复认证。
• seedance-2.0-cl-b-fast 和 seedance-2.0-cl-b-mini 共享另一个素材兼容范围；CL 与 CL-B 的准备结果相互隔离。切换模型后查询对应模型的 Preparation，以 generation_ready 确认当前调用范围可用；该查询不会改变路由顺序。
• seedance-2.0-gl 系列支持 mode=asset 创建当前模型可用的图片、视频和音频素材引用。客户已有稳定公网 URL 时直接使用即可；multipart/mode=oss 只作为本地文件的可选中转，不是正式业务的必选步骤。
• 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 和 moon-2.0-ld-b 适合 720P 人物与姿势参考、多图片、多视频和背景音频组合；两个型号能力相同，支持公网 URL、MoonApiX 托管 URL 和模型可用的素材引用，单次素材合计最多 15 个。
• moon-2.0-am 系列适合 720P 按次快速多素材任务；正式业务使用客户自有公网 URL，mode=oss 仅用于本地文件联调。
• moon-2.0-me-a-720p、moon-2.0-me-a-fast 和 moon-2.0-me-b-720p 推荐使用 references[] 传入稳定公网 URL；A / A Fast 仅支持图片，B 支持图片、视频和音频混合参考，音频需要搭配图片或视频。

上传素材

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 OSS URL，返回素材 ID。	免费。
asset	执行素材认证并创建 Asset://asset_xxx 素材引用。模型不支持时返回明确错误。	免费。
both	同时创建测试 OSS URL 和 Asset://asset_xxx 素材引用。	两个准备动作均免费。

mode=both 同时申请托管与素材准备。旧兼容响应可能聚合两个动作的结果；V2 分别报告 storage 和 preparation，归档失败不会撤销已经有效的素材准备结果，准备失败也不会删除已建立的素材身份或已验证托管副本。V2 的具体上传适配范围见 上传素材。

旧兼容契约的成功响应示例：

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

旧兼容记录在异步准备时可能返回 created 或 syncing，审核和准备状态须分别读取。审核通过不能替代目标模型的准备结果，也不存在所有契约都适用的五字段就绪门槛。

V2 指定模型查询中的 preparation.generation_ready=true 表示当前允许调用范围内至少存在一条无需新增准备即可使用的路径。实际生成仍按正常调用配置执行，并重新验证素材；它不保证立即生成。preparation.review_status=unknown 表示缺少独立审核证据，不能据此推断失败或认证成功。

引用素材

生成接口中可以直接使用 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 提供独立的素材组和素材管理接口，只允许操作当前账号的资源：

操作	接口
创建、列出素材组	POST /v1/asset-groups、GET /v1/asset-groups
查询、编辑素材组	GET /v1/asset-groups/{group_id}、PATCH /v1/asset-groups/{group_id}
删除素材组	DELETE /v1/asset-groups/{group_id}
编辑素材名称、说明或移动分组	PATCH /v1/assets/{asset_id}
删除素材	DELETE /v1/assets/{asset_id}

删除是将状态标记为 disabled 的软删除，成功返回 HTTP 200 和 deleted=true。默认组、系统组不能删除；自建组即使非空也可以软删除，但不会连带删除或移动组内素材。移动素材时，目标组必须属于当前账号、已启用且用途域相同。

软删除保留历史记录，不物理清除托管文件，不撤销其他服务中已有的认证引用，也不取消已提交的生成任务；不能用它保证已发出 URL 立即失效。请求示例、返回字段和错误码见素材分组、编辑素材和删除素材。

公网 URL 和二进制文件

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

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

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

查询素材

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 与订单、用户或项目的对应关系。

V2 契约已在当前素材接口版本生效，按目标模型查询准备状态：

curl "https://moonapix.com/v1/assets/asset_xxx?model=seedance-2.5-cl" \
  -H "Authorization: Bearer <MOONAPIX_API_KEY>" \
  -H "MoonApiX-Asset-Contract: v2"

V2 GET 只读，不发起素材认证或查询外部准备进度；无 model 时省略 Preparation。需要开始或继续准备时，显式执行 Prepare 并复用同一素材 ID，详见 上传素材 和 查询素材。不要把旧兼容查询可能推进准备的行为套用到 V2。

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

文件建议

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

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