上传素材
创建可复用的图片、音频或视频素材。保存返回的 asset_id 和 asset_ref;用于模型素材引用前,先查询准备结果。
方法与路径
POST /v1/assets/uploads新接入和已有客户端统一使用本站已注册的 /v1/assets/uploads 入口。
上传请求
使用客户公网 URL
目标模型支持素材引用时,传入实际公开模型名和原始 URL:
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
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 / file | JSON 使用公网 URL,multipart 使用本地文件。 |
type | 媒体类型:image、audio、video 或 file,仍须符合模型要求。 |
model | 需要模型素材引用时,填写实际公开模型名。 |
mode | 显式选择 asset、oss 或 both。 |
group_id | 可选,必须是当前账号的分组。 |
purpose | 可选用途,例如 video_reference。 |
JSON 批量提交使用 urls,每个 URL 创建一条素材。批量字段与媒体角色见高级选项。
响应示例
上传成功返回 HTTP 200。下例仍在准备中:
{
"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 放入生成接口支持的媒体字段。角色、数量、尺寸和时长仍须满足模型限制,见素材指南。
素材分组
按项目整理素材使用分组;分组本身不证明模型准备完成。