上传素材

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

如果素材已经有稳定公网 URL，推荐用 JSON 请求传 url 创建素材 ID。MoonApiX 会保存你传入的 URL；只有使用 mode=oss 或 mode=both 时，才会创建 MoonApiX 托管 URL。

方法与路径

http

POST /v1/assets/uploads

兼容入口：

http

POST /api/asset/createMedia

上传请求

使用客户公网 URL

推荐优先使用这种方式。MoonApiX 会保存你传入的 URL；除非你显式使用 mode=oss 或 mode=both，否则不会默认转存到 MoonApiX 托管存储。

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 托管 URL

当外部 URL 不稳定，或业务明确要求 MoonApiX 托管 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"

文件上传只支持 mode=oss 或 mode=both。如果目标生成接口本身支持二进制文件，也可以按生成接口要求直接提交文件，不必先创建素材。

上传到指定分组

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；不传时使用默认分组。
`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 选择

mode	保存内容	主要返回	适合场景
`asset`	保存客户公网 URL，并创建素材引用。	`id` / `asset_id`、`reference` / `asset_ref`。	模型明确支持 `Asset://asset_xxx`，素材需要复用。
`oss`	创建 MoonApiX 托管 URL。	`id` / `asset_id`、`url`、`oss_url`。	外部 URL 可能过期，或业务要求由 MoonApiX 托管。
`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；只有明确需要 MoonApiX 托管 URL 时再使用 mode=oss。mode=both 是高级场景，不建议作为默认选择；它会同时创建 MoonApiX 托管 URL 和 Asset://asset_xxx 模型素材引用，可能分别产生 asset_upload_oss 和 asset_create_media 费用，且任一动作失败都会影响最终可用性。

支持模型

mode=asset 只适合目标模型明确支持素材引用创建的场景。使用 Seedance-2 不同模型线时，请按实际生成模型创建或确认素材，避免把不同模型线的素材 ID 混用。

模型	上传获取 `Asset://`	推荐模式	说明
`seedance-2.0-kz-fast`	支持	`asset` / `both`	适合图片、视频、音频等素材复用。
`seedance-2.0-kz`	支持	`asset` / `both`	适合更高质量任务和长期素材复用。
`seedance-2.0-qm-720p`	支持	`asset`	多素材组合任务推荐先获取 `Asset://asset_xxx`，再用 `references[]` 提交。
`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 系列素材参数体系，支持图片和视频素材引用；素材 ID 不要和 seedance-2.0-kz 系列跨线混用。
`seedance-2.0-ld-17`	不作为主路径	`oss` 或直接 URL	新接入优先用公网 URL、MoonApiX 托管 URL 或 `references[]`。支持范围以 LD 系列页为准。
`seedance-2.0-me`	不建议作为主路径	`oss` 或直接 URL	推荐直接传公网 URL 或 MoonApiX 托管 URL。

如果你不确定目标模型是否支持 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"
}

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

状态字段

字段	常见值	说明
`status`	`created`、`syncing`、`ready`、`failed`	MoonApiX 素材记录状态。
`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	素材同步失败原因。仅失败时通常有值。

建议在生成前确认：

text

status = ready
preparation_status = ready
generation_ready = true
review_status = succeeded
review_passed = true

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

有些素材服务会先返回“素材已过审”，随后在同步到生成引擎时失败。例如图片命中版权或内容策略时，可能出现：

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
}

只有同时需要托管 URL 和模型素材引用时才使用 mode=both。如果只是一次性生成，直接传 URL 更简单；如果只需要素材引用，用 mode=asset；如果只需要 MoonApiX 托管 URL，用 mode=oss。

对话协议

向量

音频

模型

Ideogram 图像

Midjourney 任务

Seedance-2 视频

上传素材

方法与路径

上传请求

使用客户公网 URL

上传文件到 MoonApiX 托管 URL

上传到指定分组

常用字段

mode 选择

双层素材结果

支持模型

使用素材引用

素材分组

状态字段

响应示例

mode=asset

mode=both

相关页面

Ideogram 图像

Midjourney 任务

Seedance-2 视频

上传素材 ​

方法与路径 ​

上传请求 ​

使用客户公网 URL ​

上传文件到 MoonApiX 托管 URL ​

上传到指定分组 ​

常用字段 ​

mode 选择 ​

双层素材结果 ​

支持模型 ​

使用素材引用 ​

素材分组 ​

状态字段 ​

响应示例 ​

mode=asset ​

mode=both ​

相关页面 ​

上传素材

方法与路径

上传请求

使用客户公网 URL

上传文件到 MoonApiX 托管 URL

上传到指定分组

常用字段

mode 选择

双层素材结果

支持模型

使用素材引用

素材分组

状态字段

响应示例

mode=asset

mode=both

相关页面