上传素材

上传素材用于创建可复用的图片、音频或视频资源。上传成功后，MoonApiX 会返回素材 ID、可访问 URL、素材引用和状态信息。

如果素材已经有稳定公网 URL，可以用 JSON 请求传 url。旧兼容记录会保存原始 URL，旧契约只有 mode=oss 或 mode=both 创建托管 URL；V2 的内容快照及三层状态契约见下方。

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

Asset V2 操作契约（当前生效）

Asset V2 已在当前素材接口版本生效。它不会自动升级历史素材；历史记录仍按旧兼容语义解释。Asset 身份、Storage 托管副本和 Preparation 目标模型准备独立计算；status=ready 只表示 MoonApiX 素材身份和内容基线可用。

Create Asset

bash

curl https://moonapix.com/v1/assets \
  -H "Authorization: Bearer <MOONAPIX_API_KEY>" \
  -H "MoonApiX-Asset-Contract: v2" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/reference.png",
    "type": "image",
    "storage": { "enabled": false }
  }'

创建操作读取文件或抓取 URL 快照，建立不可变内容基线和稳定 asset_id，成功返回 201。它不认证目标模型，不接受旧的 model / mode 字段。storage.enabled 是请求是否同时归档的意图，不是归档成功事实；响应只通过 storage.status 表达事实，不返回永久的 storage.enabled 字段。设为 false 仍会建立内容基线，托管可后续补全。asset_id / asset_ref 是 MoonApiX 自己的身份，不是其他服务的素材 ID；服务端引用由平台服务端维护。

POST /v1/assets/uploads 携带同一 V2 请求头时也是严格创建契约的兼容入口，使用相同输入，不能把旧 model / mode 请求体与 V2 请求头混用。

Archive Asset

bash

curl https://moonapix.com/v1/assets/asset_xxx/archive \
  -H "Authorization: Bearer <MOONAPIX_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{}'

归档操作为既有身份补全托管副本。可用 {} 请求复用已有可信内容来源，也可提交 {"url":"https://example.com/reference.png"} 或 multipart 的单个 file；回填内容必须与已建立的可信内容基线一致。相同 URL 不能证明字节一致，未验证的历史内容和内容不一致会返回明确错误，不能覆盖旧内容。

storage.status=ready 表示当前托管副本已验证且可访问，保存期限仍由存储服务政策决定。归档失败不会删除素材身份，也不会把已经成功的目标模型准备结果改成失败。

Prepare Asset

bash

curl https://moonapix.com/v1/assets/asset_xxx/prepare \
  -H "Authorization: Bearer <MOONAPIX_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{ "model": "seedance-2.5-cl" }'

准备操作为目标公开模型建立或确认可用引用，按正常调用策略选择执行路径，并可复用已经兼容的准备结果。准备结果可用返回 200，尚未完成返回 202。当前不支持非空 config_id，会明确报错。

preparation.generation_ready=true 表示查询时点、当前模型和允许的调用范围内至少存在一条无需新增准备即可引用的路径；多素材任务必须由同一条路径同时满足全部素材要求。不保证立即执行，也不改变正常调度承诺。review_status=unknown 不证明审核成功或失败，也不会阻断已经独立确认可用的准备结果。准备失败保留已有 asset_id、身份 status=ready 和独立的存储结果。

查询素材是只读操作，不轮询或推进认证；处理中或需要重试时显式调用 Prepare，使用同一个 asset_id。

V2 下的旧上传兼容请求

服务发布后，已接入 V2 的兼容上传仍可接受未携带 V2 请求头的旧 mode 请求。mode=asset 同样先建立可信托管快照，再做目标模型准备；url / source_url 别名只包含安全托管 URL，不返回原始输入 URL。未升级历史记录仍按下方旧契约解释。

仅做 OSS 归档时，未指定 model 则不返回 preparation 或旧顶层准备状态别名；指定 model 只读取该模型的准备投影，不触发认证。模型不可用或无权限不会阻止素材身份建立和 OSS 归档，而是反映在准备结果中。身份建立后，即使归档或认证失败，也保留 asset_id 和身份 status=ready。

客户端判定顺序：先看 asset.status 是否为 ready，再看同一目标模型下 preparation.status 是否为 ready 或 not_required，最后确认 preparation.generation_ready=true。只看 status=ready、storage.status=ready 或 review_status=succeeded 都不够。

方法与路径

http

POST /v1/assets/uploads

兼容入口：

http

POST /api/asset/createMedia

上传请求

使用客户公网 URL

以下无 V2 请求头的示例采用旧兼容请求格式。对于未升级的旧记录，MoonApiX 会保存原始 URL；旧契约仅在 mode=oss 或 mode=both 时创建托管 URL。V2 兼容记录的快照行为见上方。

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

上传文件到 MoonApiX OSS 测试 URL

仅在联调或测试本地文件时使用。该 URL 不适合作为客户正式业务的长期素材地址。

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"

未接入 V2 的旧上传路径只支持文件 mode=oss 或 mode=both。已接入 V2 的兼容上传在指定支持素材准备的目标模型时，也支持文件 mode=asset，并先建立可信托管快照；严格 V2 创建不使用 mode 字段。如果目标生成接口本身支持二进制文件，也可以按生成接口要求直接提交文件，不必先创建素材。

上传到指定分组

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",
    "group_id": "group_xxx",
    "url": "https://example.com/reference.png"
  }'

常用字段

字段	类型	说明
`file`	file	要上传的文件。
`url`	string	可选。已有公网文件 URL。使用 JSON 请求时常用。
`group_id`	string	可选。素材分组 ID；不传时使用默认分组。活体认证返回的组初始可以为空；上传成功后才创建素材 ID，见真人活体认证。
`model`	string	可选。需要创建素材引用时建议传入目标模型名。
`type`	string	素材类型，常见值为 `image`、`audio`、`video`。
`purpose`	string	可选。素材用途，例如 `video_reference`、`digital_human_avatar`、`voice_training`。
`mode`	string	可选。`oss`、`asset` 或 `both`。建议显式传入。

JSON 请求可以传 url 或 urls。urls 用于一次提交多个公网 URL；每个 URL 会创建一条素材记录。

旧兼容 mode 选择

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

mode	保存内容	主要返回	适合场景
`asset`	保存客户公网 URL，并创建素材引用。	`id` / `asset_id`、`reference` / `asset_ref`。	模型明确支持 `Asset://asset_xxx`，素材需要复用。
`oss`	创建 MoonApiX OSS 测试 URL。	`id` / `asset_id`、`url`、`oss_url`。	仅用于联调测试，不作为长期业务存储。
`both`	同时保存托管 URL 和素材引用。	同时返回 `url` / `oss_url` 和 `reference` / `asset_ref`。	高级场景：同一素材既要直接访问，也要用于素材引用。

双层素材结果

MoonApiX 统一返回客户稳定素材 ID：

text

asset_id = asset_xxx
asset_ref = Asset://asset_xxx

不同 mode 下，素材可能同时有两层结果：

字段	含义
`source_url`	你传入的原始公网 URL。使用 `mode=asset` 时通常就是这个 URL。
`url`	客户可用 URL。`mode=asset` 时通常等于 `source_url`；`mode=oss` / `both` 时通常是 MoonApiX 托管 URL。
`oss_url`	MoonApiX 托管 URL。只有 `mode=oss` 或 `mode=both` 时通常有值。
`reference` / `asset_ref`	可用于部分生成接口的素材引用，格式为 `Asset://asset_xxx`。
`content`	便于直接放进生成请求的内容片段。图片常见为 `content.image_url.url`。

对于旧兼容请求，如果文件已有稳定公网 URL，可使用 mode=asset；只有联调测试需要临时 OSS URL 时使用 mode=oss。mode=both 是高级场景，不建议作为默认选择。V2 中归档与认证独立计算，某一步失败不覆盖另一层的成功状态。

支持模型

以下表格描述旧兼容素材准备策略。V2 的 asset_id 是稳定身份；切换模型时查询目标模型的 preparation，不能仅凭另一模型的准备结果判断可用。

模型	上传获取 `Asset://`	推荐模式	说明
`seedance-2.0-kz-fast`	支持	`asset` / `both`	适合图片、视频、音频等素材复用。
`seedance-2.0-kz`	支持	`asset` / `both`	适合更高质量任务和长期素材复用。
`seedance-2.0-cl-fast`	支持	`asset` / `both`	和 `seedance-2.0-kz-fast` 是不同模型线，素材 ID 不要跨线混用。
`seedance-2.0-cl`	支持	`asset` / `both`	和 `seedance-2.0-kz` 是不同模型线，素材 ID 不要跨线混用。
`seedance-2.0-cl-mini`	支持	`asset` / `both`	与 CL 系列其他型号共享素材兼容范围；不要与 KZ 或 CL-B 跨范围混用。
`seedance-2.5-cl`	支持	`asset` / `both`	确认目标模型准备完成；单独 `status=ready` 不够，不能把认证引用失败降级为公网 URL。
`seedance-2.0-cl-b-fast`、`seedance-2.0-cl-b-mini`	支持	`asset` / `both`	CL-B 型号之间共享素材兼容范围；与 CL、KZ 等范围隔离。
`seedance-2.0-sz`、`seedance-2.0-sz-fast`、`seedance-2.0-sz-mini`、`seedance-2.5-sz`	支持	`asset` / `both`	按目标 SZ 模型创建或确认素材；支持图片、视频和音频参考，素材 ID 不要跨模型线混用。
`moon-2.0-am-720p-fast`	不作为主路径	`oss` 或直接 URL	新接入优先用公网 URL、MoonApiX 托管 URL 或 `references[]`。适合单图、图片 + 背景音乐和多素材快速任务。

CL 系列（包括 seedance-2.5-cl）的素材准备可在该兼容范围中复用，CL-B 的 Fast / Mini 型号也可在 CL-B 范围内复用。CL 和 CL-B 属于不同素材兼容范围，不能互相复用准备结果。更换目标模型时保留同一个 MoonApiX asset_id，并查询该模型的 preparation.generation_ready；这会确认当前调用范围可用性，不会为兼容型号重复认证，也不改变正常路由策略。

如果你不确定目标模型是否支持 mode=asset，先按对应模型页确认素材策略。素材创建成功后，建议在业务系统里同时保存 asset_id、asset_ref、目标模型和素材状态。

使用素材引用

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

review_status=succeeded 本身不证明准备完成。目标模型的 generation_ready=true 是当前调用范围内的准备判断，不表示后续视频任务会自动使用该素材，也不保证立即执行。创建视频任务时仍需要把 Asset://asset_xxx 放到 image、reference_image_urls、first_frame_url 或 content[] 等输入字段里。

示例：

json

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

只传下面这样的请求不会加载素材，因为请求体里没有任何图片 URL 或素材引用：

json

{
  "model": "seedance-2.0-kz-fast",
  "prompt": "图中女孩对着镜头说“茄子”，360度环绕运镜",
  "input_type": "reference",
  "duration": 5
}

素材分组

如需按项目、用户或业务场景隔离素材，可以先创建素材分组，再在上传时传入 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"
  }'

json

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

详细分组接口见素材分组。

SH 模型的素材准备边界

seedance-2.0-sh、seedance-2.0-sh-fast、seedance-2.0-sh-mini 和 seedance-2.5-sh 已验证图片 AIGC Prepare 可达到就绪。视频 AIGC 准备尚未完成成功验收；上传或获得 asset_id 不表示视频引用已可生成。V2 应复用同一素材身份，按目标模型显式 Prepare，并以该模型的 preparation.status 和 preparation.generation_ready 判断准备结果；GET 查询不推进准备。音频使用稳定公网 URL，不作为独立 AIGC 认证素材提交。这些模型未开放真人扫脸／活体认证，不接受活体分组；普通 AIGC 素材准备也不构成真人授权或活体验证。更多能力和验收范围见 SH 模型说明。

旧兼容状态字段

字段	常见值	说明
`status`	`created`、`syncing`、`ready`、`failed`	MoonApiX 素材记录状态；单独为 `ready` 不证明认证成功。
`sync_status`	`created`、`syncing`、`ready`、`failed`	素材引用准备状态。
`preparation_status`	`created`、`syncing`、`ready`、`failed`、`disabled`	生成前准备状态。
`generation_ready`	`true` / `false`	当前目标生成范围内的准备结果；不保证立即执行。
`review_status`	`succeeded`、`pending`、`failed`、`unknown`	素材审核结果。`succeeded` 表示素材审核已通过，但不等于已经完成生成前同步。
`review_passed`	`true` / `false`	是否已通过素材审核/可用性检查。
`sync_error`	string	素材同步失败原因。仅失败时通常有值。

使用旧兼容记录时，结合目标模型的准备字段判断，不将五个字段同时作为成功前提。review_status=unknown 不单独阻断已经确认可用的准备结果。

text

preparation_status = ready
generation_ready = true

如果 generation_ready=false 或 preparation_status=syncing，不要重新创建素材。等待一小段时间后查询同一个 asset_id，ready 后继续使用同一个 Asset://asset_xxx。如果 preparation_status=failed，请查看 sync_error，更换素材或检查素材 URL 是否可公开访问。

旧兼容记录可能先返回“素材已过审”，随后在同步到生成引擎时失败。例如图片命中版权或内容策略时，可能出现以下旧响应；V2 保留已建立的素材身份，只在准备层记录失败：

json

{
  "status": "failed",
  "preparation_status": "failed",
  "generation_ready": false,
  "review_status": "succeeded",
  "review_passed": true,
  "sync_error": "InputImageSensitiveContentDetected.PolicyViolation: The request failed because the input image may be related to copyright restrictions."
}

这种情况表示素材审核通过，但不能用于生成；请以 generation_ready 和 preparation_status 判断是否可生成。

旧兼容响应示例

mode=asset

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": "syncing",
  "preparation_status": "syncing",
  "generation_ready": false,
  "trace_id": "2026060301010100000000000000000000",
  "created_at": 1710000000
}

mode=asset 刚创建时可能返回 syncing。查询到 generation_ready=true 后再用于视频生成。

mode=both

json

{
  "id": "asset_xxx",
  "asset_id": "asset_xxx",
  "object": "asset",
  "type": "image",
  "group_id": "group_xxx",
  "url": "https://media.moonapix.com/user-assets/image/example.png",
  "source_url": "https://example.com/reference.png",
  "oss_url": "https://media.moonapix.com/user-assets/image/example.png",
  "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
}

只有联调时同时需要 OSS 测试 URL 和模型素材引用时才使用 mode=both。如果只是一次性生成，直接传客户自己的公网 URL 更简单；如果只需要素材引用，用 mode=asset；如果只需临时测试 URL，用 mode=oss。

对话协议

向量

音频

模型

GPT Image

Gemini Nano

Ideogram 图像

Midjourney 任务

Seedance-2 视频

Moon-2 视频

上传素材

Asset V2 操作契约（当前生效）

Create Asset

Archive Asset

Prepare Asset

V2 下的旧上传兼容请求

方法与路径

上传请求

使用客户公网 URL

上传文件到 MoonApiX OSS 测试 URL

上传到指定分组

常用字段

旧兼容 mode 选择

双层素材结果

支持模型

使用素材引用

素材分组

SH 模型的素材准备边界

旧兼容状态字段

旧兼容响应示例

mode=asset

mode=both

相关页面

Ideogram 图像

Midjourney 任务

Seedance-2 视频

Moon-2 视频

上传素材 ​

Asset V2 操作契约（当前生效） ​

Create Asset ​

Archive Asset ​

Prepare Asset ​

V2 下的旧上传兼容请求 ​

方法与路径 ​

上传请求 ​

使用客户公网 URL ​

上传文件到 MoonApiX OSS 测试 URL ​

上传到指定分组 ​

常用字段 ​

旧兼容 mode 选择 ​

双层素材结果 ​

支持模型 ​

使用素材引用 ​

素材分组 ​

SH 模型的素材准备边界 ​

旧兼容状态字段 ​

旧兼容响应示例 ​

mode=asset ​

mode=both ​

相关页面 ​

上传素材

Asset V2 操作契约（当前生效）

Create Asset

Archive Asset

Prepare Asset

V2 下的旧上传兼容请求

方法与路径

上传请求

使用客户公网 URL

上传文件到 MoonApiX OSS 测试 URL

上传到指定分组

常用字段

旧兼容 mode 选择

双层素材结果

支持模型

使用素材引用

素材分组

SH 模型的素材准备边界

旧兼容状态字段

旧兼容响应示例

mode=asset

mode=both

相关页面