Skip to content

上传素材 ​

创建可复用的图片、音频或视频素材。保存返回的 asset_id 和 asset_ref;用于模型素材引用前,先查询准备结果。

方法与路径 ​

http
POST /v1/assets/uploads

新接入和已有客户端统一使用本站已注册的 /v1/assets/uploads 入口。

上传请求 ​

使用客户公网 URL ​

目标模型支持素材引用时,传入实际公开模型名和原始 URL:

bash
curl https://moonnexai.com/v1/assets/uploads \
  -H "Authorization: Bearer <MOONNEXAI_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "seedance-2.0-kz-fast",
  "mode": "asset",
  "type": "image",
  "url": "https://example.com/reference.png"
}'

mode=asset 保存原始 URL,并请求为所选模型准备素材。请保持该 URL 可用;此模式不承诺创建 MoonNexAI 托管副本。把示例 URL 换成有权使用、可匿名下载的媒体直链。

上传文件到 MoonNexAI OSS 测试 URL ​

bash
curl https://moonnexai.com/v1/assets/uploads \
  -H "Authorization: Bearer <MOONNEXAI_API_KEY>" \
  -F "file=@./reference.png" \
  -F "type=image" \
  -F "purpose=video_reference" \
  -F "mode=oss"

mode=oss 用于取得联调 URL。本地文件同时需要模型准备时,见模式选项。OSS 不保证长期保存或持续可用。

上传到指定分组 ​

在 JSON 示例中加入 "group_id": "group_xxx",或在 multipart 中加入 -F "group_id=group_xxx"。先创建分组;不传时使用当前账号的默认分组。

常用字段 ​

字段说明
url / fileJSON 使用公网 URL,multipart 使用本地文件。
type媒体类型:image、audio、video 或 file,仍须符合模型要求。
model需要模型素材引用时,填写实际公开模型名。
mode显式选择 asset、oss 或 both。
group_id可选,必须是当前账号的分组。
purpose可选用途,例如 video_reference。

JSON 批量提交使用 urls,每个 URL 创建一条素材。批量字段与媒体角色见高级选项。

响应示例 ​

上传成功返回 HTTP 200。下例仍在准备中:

json
{
  "object": "asset",
  "asset_id": "asset_xxx",
  "asset_ref": "Asset://asset_xxx",
  "reference": "Asset://asset_xxx",
  "group_id": "group_xxx",
  "domain": "media",
  "asset_type": "image",
  "mode": "asset",
  "source_url": "https://example.com/reference.png",
  "url": "https://example.com/reference.png",
  "reference_url": "https://example.com/reference.png",
  "status": "syncing",
  "sync_status": "syncing",
  "preparation_status": "syncing",
  "generation_ready": false
}

拿到 ID 或 URL 不代表已就绪;保留此 ID 继续查询详情。

状态字段 ​

使用素材引用前,确认 status=ready、preparation_status=ready 且 generation_ready=true,并确认上传时选择的模型支持此引用。review_status / review_passed 是补充状态,不能替代准备结果;已返回审核失败或错误时先处理错误。只有 OSS URL 可用不等于任意模型都支持 Asset://。

需要模型素材引用时,在上传请求中传入实际使用的 model 和 mode=asset;保存返回的 asset_id。处于 syncing 时继续查询同一 ID 的详情,详情查询会尝试同步已提交的准备结果。失败时查看 sync_error,不要无条件重复上传或继续生成。

完整状态和后续动作见查询素材。

mode 选择 ​

asset 请求模型素材引用,oss 创建托管测试 URL,both 同时请求两者。URL 字段含义和完整示例见高级选项。

支持模型 ​

选择 API Key 已启用的模型,并核对该模型的媒体要求。不同模型线的素材引用不能默认互换,见模型选择。

使用素材引用 ​

确认就绪后,把返回的 Asset://asset_xxx 放入生成接口支持的媒体字段。角色、数量、尺寸和时长仍须满足模型限制,见素材指南。

素材分组 ​

按项目整理素材使用分组;分组本身不证明模型准备完成。

相关页面 ​