Skip to content

素材高级选项 ​

常用流程是上传后查询。本页集中说明模式、URL 字段与已有客户端的兼容入口。

mode 选择 ​

mode行为适用场景
asset保存公网原始 URL,并请求模型素材引用。支持素材创建的模型需要复用媒体,传入实际 model。
oss创建 MoonNexAI 托管测试 URL。本地文件联调;不代表对任意模型完成认证。
both同时请求托管副本和模型素材引用。确实需要两种结果,且目标模型支持素材创建。

文件上传通用示例使用 oss。both 需要支持的目标模型;文件 asset 仅在所选模型支持该创建流程时可用,不能默认所有模型都接受 multipart 素材。如果生成接口本身支持直接提交文件,也可使用该生成接口自己的 multipart 契约。

同时取得两种结果 ​

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": "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 / referenceMoonNexAI 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 不属于本站当前文档所承诺的素材接口。

相关页面 ​