MoonApiX Docs

简体中文

English

简体中文

English

外观

旧版兼容 ​

本页供已使用旧上传请求或历史素材的客户端查阅。新接入从上传素材开始，按“创建素材 → 按目标模型准备 → 查询状态”使用 V2；需要托管副本时再归档。

请求格式与记录语义 ​

旧请求格式不等于历史记录。相同的旧请求格式，在已接入 V2 的兼容上传中会建立新的可信内容快照；已有历史记录不会因服务升级或添加请求头而自动升级。

情况输入与行为如何读取结果
严格 V2 创建POST /v1/assets，设置 Asset-Contract: v2。不接受 model / mode，创建与目标模型准备分开。身份、storage、目标模型的 preparation 分别判断；创建本身不认证目标模型。
V2 下的旧上传兼容请求POST /v1/assets/uploads，不带 V2 契约头，沿用 mode 等旧字段。mode=asset 也先建立可信托管快照，再做目标模型准备。url / source_url 兼容别名只返回安全托管 URL，不返回原始输入 URL；准备结果按同一目标模型判断。
未升级的历史记录保留原有生命周期和原始 URL 语义；旧 mode=asset 不代表已有托管副本。按本页历史字段解释；需要确认当前模型可用性时查询并显式 Prepare。

MoonApiX-Asset-Contract: v2 仍是兼容头；每个请求只设置一个契约头。POST /v1/assets/uploads 携带任一 V2 契约头时也会选择严格 V2 创建，不能再提交旧 model / mode 请求体。成功的 V2 响应使用规范头 Asset-Contract: v2。

兼容上传仅做 OSS 归档时，未传 model 不返回 preparation 或旧顶层准备状态别名；传了 model 只读取该模型的准备投影，不触发认证。模型不可用或无权限不会阻止身份建立和 OSS 归档，而会反映在准备结果中。身份建立后，归档或准备失败仍保留 asset_id 和身份 status=ready。

旧请求入口 ​

操作路径兼容入口
上传素材POST /v1/assets/uploadsPOST /api/asset/createMedia
素材列表GET /v1/assets使用现有列表接口。
素材详情GET /v1/assets/{asset_id}GET /api/asset/get

新代码使用规范路径；列表与详情的参数见查询素材。修改名称、移动分组和删除见管理素材。

公网 URL 上传 ​

以下是旧请求格式，不设置 V2 契约头。服务端的实际快照和 URL 返回行为按上表区分，不能据此假定新建记录仍只保存原始 URL。

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"
  }'

本地文件上传 ​

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

未接入 V2 的旧上传路径仅支持文件 mode=oss 或 mode=both。V2 兼容上传在指定支持素材准备的目标模型时，也支持文件 mode=asset。严格 V2 创建不使用 mode。

字段用途
file / url本地文件或已有公网直链。JSON 也支持 urls，每个 URL 创建一条素材记录。
type素材类型，如 image、audio、video。
model需要素材准备的目标公开模型；先确认模型支持的素材策略。
mode旧上传模式，见下表。
group_id可选；不传使用默认分组。使用真人活体认证组时传入认证结果的 group_id，组初始可以为空。
purpose可选；如 video_reference、digital_human_avatar、voice_training。

历史 mode 语义 ​

下表的原始 URL 和托管行为仅适用于未升级的历史记录。V2 兼容新记录以兼容上传规则为准。

mode历史保存行为常见返回
asset保存客户公网 URL，并创建素材引用。asset_id、asset_ref；url 通常等于原始 source_url。
oss创建 MoonApiX OSS 测试 URL。asset_id、url、oss_url；不代表模型准备完成。
both同时创建托管副本和素材引用。asset_id、asset_ref、url、oss_url；准备结果仍需单独判断。

MoonApiX OSS 仅供联调和测试，不承诺长期保存、URL 长期有效或持续可用性。正式业务使用客户自有存储的稳定匿名公网直链。新接入使用 V2 分别表达创建、归档和准备，不再通过 mode 合并操作。

历史素材字段 ​

下表描述未升级的历史响应。V2 响应中的兼容别名不改变 V2 三层含义，尤其不能把其 source_url 当作原始输入 URL。

字段历史含义
object对象类型，通常为 asset。
id / asset_idMoonApiX 素材 ID，格式为 asset_xxx。
reference / asset_refMoonApiX 素材引用，格式为 Asset://asset_xxx。使用时仍须放入生成请求的素材输入字段。
group_id / domain所属分组与用途域；常见用途域为 media。
type / asset_type素材类型，如 image、audio、video、file。
name / description素材名称与说明。
source_url创建时传入的原始公网 URL。
url客户可用 URL；历史 mode=asset 通常为原始 URL，oss / both 通常为托管 URL。
oss_url托管测试 URL；历史 mode=oss / both 通常有值，不保证长期有效。
content可放入生成请求的内容片段，图片常见为 content.image_url.url。
content_type / size / durationMIME 类型、字节数、音视频时长（秒）。
状态与审核字段见历史状态与后续动作。
visibility通常为 private。
created_at / updated_at创建与更新时间。
request_id / trace_id排查问题时提供的请求与跟踪 ID。

历史状态与后续动作 ​

字段历史常见值含义
statuscreated、syncing、ready、failed、disabled素材记录状态，单独 ready 不证明目标模型准备完成。
sync_statuscreated、syncing、ready、failed素材引用准备状态。
preparation_statuscreated、syncing、ready、failed、disabled生成前准备状态。
generation_readytrue / false同一目标模型和调用范围内的准备结果，不保证立即执行。
review_statussucceeded、pending、failed、unknown审核证据；succeeded 不等于已完成准备。
review_passedtrue / false是否通过审核或可用性检查，不能替代生成准备判断。
sync_errorstring准备失败原因。

历史响应通常结合 preparation_status=ready 与 generation_ready=true 判断准备结果，不必把所有审核字段同时作为成功前提。review_status=unknown 不单独阻断已确认可用的准备；审核成功也不能覆盖准备失败。

V2 兼容响应的 sync_status / preparation_status 如有返回，会映射同一目标模型和调用范围的 preparation.status，也可能为 not_started、processing、not_required、unknown。新代码读取 preparation.*，不要套用历史枚举。

查询结果后续动作
已确认的历史准备流程仍在 syncing保留同一 asset_id，按该流程等待和续查；不要反复创建。
V2 not_started、processing 或 unknown显式调用同一素材的 Prepare 建立、推进或确认准备。GET 只读取保存的结果，不推进准备，单纯等待不能补充证据。
准备失败读取准备错误，检查内容、权限或素材来源；可重试时复用同一 asset_id。内容不合格时更换素材。
只有 generation_ready=false，无法确定原因按目标 model 查询完整准备状态，再决定是否 Prepare 或处理错误；不要统一按“等候后继续 GET”处理。

V2 的生成准备判断是同一目标模型和调用范围下，素材身份 status=ready、preparation.status 为 ready 或 not_required，且 preparation.generation_ready=true。切换模型时重新查询该模型的准备结果；不能复用另一范围的 true。

历史响应示例 ​

以下是未升级历史记录的示意片段，原始 URL 语义不适用于 V2 新记录。

json
{
  "object": "asset",
  "id": "asset_xxx",
  "asset_id": "asset_xxx",
  "asset_ref": "Asset://asset_xxx",
  "reference": "Asset://asset_xxx",
  "type": "image",
  "group_id": "group_xxx",
  "source_url": "https://example.com/reference.png",
  "url": "https://example.com/reference.png",
  "oss_url": "",
  "status": "ready",
  "sync_status": "syncing",
  "preparation_status": "syncing",
  "generation_ready": false
}

这个历史记录已建立，但尚不能据此生成。审核通过后仍可能在准备阶段失败，出现 review_status=succeeded、preparation_status=failed、generation_ready=false；应读取 sync_error，不能仅凭审核字段继续生成。V2 会保留身份，只在对应准备层表达失败。

切换到 V2 ​

  1. 新上传改用 V2 创建，移除创建请求中的旧 model / mode；托管和目标模型准备分别调用归档与 Prepare。
  2. 列表和详情使用 Asset-Contract: v2；需要准备结果时在详情查询明确传入目标 model，读取 storage.* / preparation.*。
  3. 继续保存已有 MoonApiX asset_id / asset_ref。请求头只选择响应契约，不会自动验证历史内容、归档或认证；历史证据不足时按返回状态显式处理。
  4. 保留创建和准备回执。处理中、结果未知或切换模型时复用同一素材，不因等待状态重新上传。

更多入口见上传与素材概览；需要官方 ID 与媒体下载地址时见官方素材管理。