上传与素材概览

上传与素材接口用于管理图片、音频、视频等文件，并在后续生成任务中复用。旧兼容契约下，素材上传和准备需要主动调用，生成请求不会自动创建托管 URL 或素材引用。

Asset V2 契约（当前生效）

Asset V2 已在当前素材接口版本生效。它不会自动升级历史素材；历史记录仍按旧兼容语义解释。使用 MoonApiX-Asset-Contract: v2 选择严格创建及查询契约。

不要把任何一个 ready 单独当成“可以生成”。客户端应先确认素材身份，再按目标模型查询 Preparation：

text

asset.status = ready
preparation.status ∈ { ready, not_required }
preparation.generation_ready = true

多素材请求还必须在同一条当前允许的执行路径上同时满足这些条件；不能把不同执行路径或不同素材库的 ready 结果拼在一起。生成请求仍需显式传入 Asset://asset_xxx 或公网 URL，服务端会在提交前重新校验。

层级	公共字段	判断内容
Asset	`asset_id`、`asset_ref`、`status`	稳定的 MoonApiX 客户侧素材身份及内容版本。`asset_id` 不是其他服务的素材 ID；V2 的 `status=ready` 只表示身份和内容基线已建立，不表示归档或模型认证成功。
Storage	`storage.status`	独立托管状态。`ready` 表示当前存在已验证、可访问副本，不承诺永久保存。
Preparation	`preparation`	仅指定目标 `model` 时返回该模型在当前调用范围内的准备投影；它描述可用引用，不是素材身份。

创建身份、补全归档、准备目标模型是三个可独立执行和重试的操作，见 V2 上传操作。严格创建请求不使用旧 model / mode 字段，storage.enabled 仅表达请求归档意图。

preparation.generation_ready=true 表示查询时点、当前模型和允许调用范围内至少存在一条无需新增准备即可引用的路径；多素材时这条路径必须同时满足全部素材要求。它不保证立即执行，也不改变正常能力、权限、价格和调度策略。生成时仍须重新验证。review_status=unknown 只表示没有独立审核证据，不等于通过或失败，也不会单独阻断已确认可用的准备结果。

查询素材为只读，不上传、不轮询、不推进准备、不结算；需要推进或重试时显式调用 Prepare。目前不支持 config_id，非空值会明确报错。

V2 兼容 mode=asset 请求也先建立可信托管快照；响应中的 url / source_url 别名只使用安全托管 URL，不返回原始输入 URL。仅 OSS 归档、不传 model 时省略 preparation 和旧顶层准备别名；传 model 时只读准备投影。模型不可用或无权限不阻断 OSS 归档和身份建立。归档或认证失败保留已建立的 asset_id 与身份 status=ready，各层状态相互独立。

asset_id / asset_ref 是 MoonApiX 客户侧身份和引用。SZ 系列还支持为当前账号已登记的素材返回火山官方素材 ID、组 ID 和当前媒体下载地址，见官方素材详情与完整调用示例及官方素材组管理。生成请求继续使用 MoonApiX 标识；已有官方 ID 时先解析到自己的 MoonApiX 素材。

旧兼容使用场景

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

路由清单

方法	路径	用途
`POST`	`/v1/assets/uploads`	上传素材。
`POST`	`/v1/visual-validate-sessions`	创建真人活体认证会话。
`POST`	`/v1/visual-validate-results`	查询真人活体认证结果。
`GET`	`/v1/asset-groups`	查询素材分组。
`POST`	`/v1/asset-groups`	创建素材分组。
`GET`	`/v1/asset-groups/{group_id}`	查询素材分组详情。
`PATCH`	`/v1/asset-groups/{group_id}`	更新素材分组名称或说明。
`DELETE`	`/v1/asset-groups/{group_id}`	删除自定义素材分组。
`GET`	`/v1/assets`	查询素材列表。
`GET`	`/v1/assets/{asset_id}`	查询素材详情。
`PATCH`	`/v1/assets/{asset_id}`	更新素材名称、说明或所属分组。
`DELETE`	`/v1/assets/{asset_id}`	删除素材。
`POST`	`/api/asset/createMedia`	兼容素材创建入口。
`GET`	`/api/asset/get`	兼容素材查询入口。

场景入口

VVS真人活体认证认证会话返回素材组；上传素材后才会创建素材 ID。POST上传素材上传图片、音频或视频，获取 URL 或素材引用。GROUP素材分组创建分组，并用 group_id 隔离素材。GET查询素材读取素材列表、详情、状态和排障字段。

上传请求

bash

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 创建素材引用：

bash

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

以下无 V2 请求头的请求示例采用旧兼容格式。对于未升级的旧记录，MoonApiX 保存原始 URL，旧 mode=asset 不默认转存；V2 兼容记录的快照行为见上方。

旧兼容 mode 说明

以下原始 URL 保存行为仅适用于未升级的旧兼容记录。

mode	行为	适合场景
`asset`	创建 `Asset://asset_xxx` 素材引用，保存你传入的公网 URL。	目标模型明确支持素材引用，且素材需要复用。
`oss`	创建 MoonApiX OSS 测试 URL。	仅用于联调测试，不作为长期业务存储。
`both`	同时创建托管 URL 和 `Asset://asset_xxx` 素材引用。	高级场景：同一素材既要直接访问，也要被模型引用。

mode=oss 上传和 mode=asset 素材认证当前均免费，mode=both 的两个准备动作也均免费。MoonApiX OSS 仅供联调和测试，不承诺文件长期保存、URL 长期有效、持续可用性或长期存储服务等级；正式业务请使用客户自有存储的匿名公网直链。

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

模型支持速查

seedance-2.0-sh、seedance-2.0-sh-fast、seedance-2.0-sh-mini 和 seedance-2.5-sh 的图片 AIGC 素材准备已验证就绪；视频 AIGC 素材准备尚未完成成功验收，不能将上传成功视为视频可用于生成。按实际目标模型显式执行 Prepare，再查询 preparation.status 与 preparation.generation_ready。音频使用可匿名访问的稳定公网 URL，不提供独立 AIGC 认证结果。这些模型未开放真人扫脸或活体认证，不能复用其他模型的活体分组。图片准备成功也不代表参考素材生成已验收，详见 SH 模型说明。

不同视频模型对“上传素材”和“生成时引用素材”的支持边界不同。上传页只负责显式创建 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-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 系列其他型号属于同一素材兼容范围；不要与 KZ 或 CL-B 跨范围混用。
`seedance-2.5-cl`	`mode=asset` 或 `mode=both`	支持	支持	必须按 `seedance-2.5-cl` 准备并等待 `generation_ready=true`、`preparation_status=ready`；引用解析失败时生成请求直接报错，不回退为公网 URL。
`seedance-2.0-cl-b-fast`、`seedance-2.0-cl-b-mini`	`mode=asset` 或 `mode=both`	支持	支持	CL-B 型号之间属于同一素材兼容范围；不要与 CL、KZ 或其他范围混用。
`seedance-2.0-sz`、`seedance-2.0-sz-fast`、`seedance-2.0-sz-mini`、`seedance-2.5-sz`	`mode=asset` 或 `mode=both`	支持	支持	按目标 SZ 模型创建或确认素材；支持图片、视频和音频参考，素材 ID 不要跨模型线混用。
`seedance-2.0-gl`、`seedance-2.0-gl-fast`、`seedance-2.0-gl-mini`	`mode=asset`；已有稳定 URL 可直接使用	支持	支持	按目标 GL 模型准备素材；客户公网 URL 优先，multipart/`mode=oss` 仅作为可选中转。
`moon-2.0-am-720p-fast`	`mode=oss` 或直接 URL	不作为主路径	不作为主路径	适合公网 URL、MoonApiX 托管 URL、单图、图片 + 背景音乐和多素材快速任务。

素材准备复用范围：seedance-2.0-cl-fast、seedance-2.0-cl、seedance-2.0-cl-mini 和 seedance-2.5-cl 属于同一 CL 素材兼容范围；seedance-2.0-cl-b-fast 与 seedance-2.0-cl-b-mini 属于另一个 CL-B 素材兼容范围。同一范围内可以复用已建立的素材准备，不需要为每个型号重复创建素材或认证；CL 与 CL-B 之间不能复用对方的准备结果。KZ 等其他范围也彼此独立。V2 始终保留同一个 MoonApiX asset_id；切换目标模型后仍应查询该模型的 Preparation，因为能力、权限和可选路由可能不同。是否可用于当前生成请求，以同一调用范围中的 preparation.generation_ready 为准。

素材分组

你可以创建自己的素材分组，并在上传、列表和详情查询中传入 group_id。同一个账号下，不同分组的素材会按 group_id 隔离；没有传 group_id 时会使用默认分组。

创建分组：

bash

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，上传时传入：

json

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

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

bash

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

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

旧兼容状态判断

字段	常见值	说明
`status`	`created`、`syncing`、`ready`、`failed`	MoonApiX 素材记录状态；单独为 `ready` 不证明认证成功。
`sync_status`	`created`、`syncing`、`ready`、`failed`	素材引用准备状态。
`preparation_status`	`created`、`syncing`、`ready`、`failed`、`disabled`	是否已经适合用于生成任务的准备状态。
`generation_ready`	`true` / `false`	当前目标生成范围内的准备结果；不保证立即执行。

使用旧兼容记录时，结合目标模型的准备字段判断，不只检查记录 status：

text

preparation_status = ready
generation_ready = true

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

旧兼容响应示例

json

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

对话协议

向量

音频

模型

GPT Image

Gemini Nano

Ideogram 图像

Midjourney 任务

Seedance-2 视频

Moon-2 视频

上传与素材概览

Asset V2 契约（当前生效）

旧兼容使用场景

路由清单

场景入口

上传请求

旧兼容 mode 说明

模型支持速查

素材分组

旧兼容状态判断

旧兼容响应示例

相关页面

Ideogram 图像

Midjourney 任务

Seedance-2 视频

Moon-2 视频

上传与素材概览 ​

Asset V2 契约（当前生效） ​

旧兼容使用场景 ​

路由清单 ​

场景入口 ​

上传请求 ​

旧兼容 mode 说明 ​

模型支持速查 ​

素材分组 ​

旧兼容状态判断 ​

旧兼容响应示例 ​

相关页面 ​

上传与素材概览

Asset V2 契约（当前生效）

旧兼容使用场景

路由清单

场景入口

上传请求

旧兼容 mode 说明

模型支持速查

素材分组

旧兼容状态判断

旧兼容响应示例

相关页面