素材高级选项
常用流程是上传后查询。本页集中说明模式、URL 字段与已有客户端的兼容入口。
mode 选择
| mode | 行为 | 适用场景 |
|---|---|---|
asset | 保存公网原始 URL,并请求模型素材引用。 | 支持素材创建的模型需要复用媒体,传入实际 model。 |
oss | 创建 MoonNexAI 托管测试 URL。 | 本地文件联调;不代表对任意模型完成认证。 |
both | 同时请求托管副本和模型素材引用。 | 确实需要两种结果,且目标模型支持素材创建。 |
文件上传通用示例使用 oss。both 需要支持的目标模型;文件 asset 仅在所选模型支持该创建流程时可用,不能默认所有模型都接受 multipart 素材。如果生成接口本身支持直接提交文件,也可使用该生成接口自己的 multipart 契约。
同时取得两种结果
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": "both",
"type": "image",
"url": "https://example.com/reference.png"
}'素材引用必须等准备成功后再使用;托管 URL 已存在时,模型准备仍可能处理中或失败。
URL 字段
| 字段 | 含义 |
|---|---|
source_url | 素材实际使用的来源 URL;asset 通常为输入地址,转存后也可能为托管地址。 |
url | 可用 URL;asset 通常是原始 URL,oss / both 通常是托管 URL。 |
oss_url | 创建了托管副本时的测试 URL,可能为空。 |
asset_ref / reference | MoonNexAI Asset://asset_xxx,不是公网 HTTP URL。 |
完整保留返回 URL 及访问所需 query,不向媒体地址发送 API Key。OSS 仅供测试,不承诺长期存储或持续可用。上传与准备收费以控制台和实际记录为准;生成按模型单独计费。
转存导致地址变化时,上传响应可能通过 input_url 返回原始输入地址。需要时从该回执保存;详情响应不保证返回最初输入的 URL。
批量 URL 与媒体角色
url、urls 选择一种表达,使用共同的 type、model、mode 和可选 group_id。每个 URL 创建一条素材;单条返回素材对象,多条返回 object=list、data[]、count。逐条保存 ID 并检查状态。
可选的 purpose、role、subject_type 表达模型已支持的媒体用途,不会绕过素材限制或启用不支持的能力。名称与说明在上传后通过管理素材编辑。
模型选择
选择账号已启用且实际用于生成的模型;上传示例使用 seedance-2.0-kz-fast。媒体类型、角色、数量和时长限制以目标模型页为准。一个模型上传成功不证明其他模型也可引用;详情查询报告已有的上传准备,不会通过查询参数为另一个模型选择准备。
模型支持公网媒体 URL 且不要求素材引用时,可以直接使用自有稳定 URL。上传不会自动把素材加入生成请求。
已有客户端兼容入口
| 操作 | 推荐路径 | 已有别名 |
|---|---|---|
| 上传 | POST /v1/assets/uploads | 使用同一已注册入口。 |
| 详情 | GET /v1/assets/{asset_id} | 使用同一已注册入口。 |
POST /v1/assets 也接受当前媒体上传字段,不表示拆分了身份创建、归档和模型准备。本文档使用上传时请求准备、详情查询继续同步的 Nex 流程。独立模型准备、归档、官方媒体管理和活体认证会话 API 不属于本站当前文档所承诺的素材接口。