MoonNexAI API Docs

Appearance

moon-2.0-ld 系列 ​

moon-2.0-ld 系列是 MoonNexAI Moon-2 的 720P 按次多素材视频模型线。当前公开型号为 moon-2.0-ld-a，适合文生视频、人物与姿势参考、多图一致性、参考视频和背景音频组合。创建任务时，model 固定填写 moon-2.0-ld-a。

当前配置 ​

项目说明
推荐入口POST /v1/videos
查询入口GET /v1/videos/{task_id} 或 GET /v1/tasks/{task_id}
推荐素材字段references[]
输出分辨率720P
支持时长5 至 15 秒
支持比例1:1、16:9、9:16、4:3、3:4
计费方式按次计费；实际价格以模型列表、价格页和扣费记录为准

能力边界 ​

能力支持情况
文生视频支持
图片参考支持，最多 9 张
视频参考支持，最多 3 个
音频参考支持，最多 3 个
混合素材支持；图片、视频和音频合计最多 15 个
首帧 / 尾帧支持，使用 first_frame / last_frame 明确角色
人物与姿势参考支持；参考图不要求必须是仅人脸图片，也不是换脸接口
独立音频不建议；音频应与至少一张图片或一个视频一起提交
素材来源支持稳定公网 URL、MoonNexAI 托管 URL，以及模型可用的素材引用

人物参考图可用于人物全身、姿势、服装、产品、场景、构图和视觉风格。需要稳定人物效果时，建议使用主体清晰、无遮挡、人物一致的参考图，并在提示词中明确动作和镜头要求。所有任务仍需通过平台内容安全检查。

推荐流程 ​

  1. 准备可直接下载的图片、视频和音频公网 URL。
  2. 联调本地文件时可通过 /v1/assets/uploads 的 mode=oss 获取临时测试 URL；正式业务请使用客户自有存储的稳定公网 URL。
  3. 调用 /v1/videos，在 references[] 中填写素材类型、角色、URL 和别名。
  4. 保存返回的 task_id，继续查询直到 status 为 succeeded 或 failed。

URL 建议保留真实文件后缀，例如 .jpg、.png、.mp4、.wav 或 .mp3，并确保不依赖登录、Cookie、额外鉴权 Header、一次性下载页或防盗链验证。

三张人物参考图 + 背景音频 ​

bash
curl https://moonnexai.com/v1/videos \
  -H "Authorization: Bearer <MOONNEXAI_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "moon-2.0-ld-a",
    "prompt": "让 @人物 参考多张图片自然摆出各种姿势，并使用 @音乐 作为背景音乐。",
    "duration": 15,
    "ratio": "9:16",
    "resolution": "720P",
    "references": [
      {
        "media_type": "image",
        "role": "character_reference",
        "url": "https://example.com/person-1.jpg",
        "alias": "人物"
      },
      {
        "media_type": "image",
        "role": "reference_image",
        "url": "https://example.com/person-2.jpg"
      },
      {
        "media_type": "image",
        "role": "reference_image",
        "url": "https://example.com/person-3.jpg"
      },
      {
        "media_type": "audio",
        "role": "background_music",
        "url": "https://example.com/background-music.wav",
        "alias": "音乐"
      }
    ]
  }'

alias 不要带 @；提示词中使用 @alias 指代素材。多张图片可以共用一个人物语义，不要求每个条目都设置不同别名。

多素材组合 ​

json
{
  "model": "moon-2.0-ld-a",
  "prompt": "让 @角色 参考 @动作 的节奏完成自然表演，并使用 @音乐 作为背景音乐。",
  "duration": 15,
  "ratio": "16:9",
  "resolution": "720P",
  "references": [
    {
      "media_type": "image",
      "role": "character_reference",
      "url": "https://example.com/character.png",
      "alias": "角色"
    },
    {
      "media_type": "video",
      "role": "reference_video",
      "url": "https://example.com/motion.mp4",
      "alias": "动作"
    },
    {
      "media_type": "audio",
      "role": "reference_audio",
      "url": "https://example.com/music.mp3",
      "alias": "音乐"
    }
  ]
}

单类上限为图片 9 张、视频 3 个、音频 3 个，三类合计不能超过 15 个。音频作为背景音乐时，建议使用 background_music 或 reference_audio，并在提示词中明确其用途。

常用字段 ​

字段类型说明
modelstring固定填写 moon-2.0-ld-a。
promptstring视频描述。建议写清主体、动作、场景、镜头和素材绑定。
durationnumber/string支持 5 至 15 秒的整数。
ratio / aspect_ratiostring1:1、16:9、9:16、4:3 或 3:4。
resolutionstring填写 720P。
referencesarray推荐。图片、视频和音频引用数组，总数最多 15 个。
references[].media_typestringimage、video、audio 或 music。
references[].rolestring图片常用 reference_image、character_reference、first_frame、last_frame；视频使用 reference_video；音频使用 reference_audio 或 background_music。
references[].urlstring稳定公网 URL、MoonNexAI 托管 URL 或模型可用的素材引用。
references[].aliasstring可选。提示词中可用 @alias 指代素材。
images / videos / audiosarray兼容写法；新接入复杂素材优先使用 references[]。
callback_urlstring可选。任务完成后的 HTTPS 回调地址。

查询与下载 ​

bash
curl https://moonnexai.com/v1/videos/{task_id} \
  -H "Authorization: Bearer <MOONNEXAI_API_KEY>"

先检查 status。只有 status 为 succeeded 时才读取 video_url、url、result_url、output.url 或 metadata.url。也可以使用标准内容入口下载：

成功任务可能直接返回 media-nex.windfimusic.com 的签名视频 URL。该域名是由 MoonNexAI 管理的官方转存媒体地址；请原样保存并使用完整 URL，包括全部查询参数。

bash
curl -L https://moonnexai.com/v1/videos/{task_id}/content \
  -H "Authorization: Bearer <MOONNEXAI_API_KEY>" \
  -o output.mp4

注意事项 ​

  • duration 可填写 5 至 15 秒范围内的整数。
  • 音频素材应与图片或视频素材一起使用，不建议音频-only 请求。
  • 参考图不要求只包含人脸，但人物稳定性取决于图片清晰度、主体一致性、提示词和内容安全检查。
  • 多素材越多，下载、媒体识别和内容检查耗时可能越长；建议先用少量素材跑通，再逐步增加。
  • 结果只使用 MoonNexAI 返回的公开 URL 或标准内容入口，不要拆分或自行拼接结果地址；media-nex.windfimusic.com 地址的签名查询参数不得删除或改写。

相关页面 ​