创建视频任务

视频创建接口用于提交文生视频、图生视频和参考素材视频任务。任务提交成功后会返回 id 或 task_id，需要通过查询接口获取最终结果。

方法与路径

http

POST /v1/videos

兼容入口：

http

POST /v1/video/generations

标准请求

POST /v1/videos 是统一的视频任务创建入口；不同模型支持的输入素材字段并不完全相同。已覆盖 MoonNexAI 通用素材写法的模型，推荐使用 references[] 描述输入素材，并用 media_type 标明素材类型、用 role 标注素材用途；images[] / videos[] / audios[] 和旧字段继续兼容。未覆盖的模型请按对应模型页面的字段说明提交。

当前推荐优先使用 references[] 的公开模型包括：seedance-2.0-kz-fast、seedance-2.0-kz、seedance-2.0-cl-fast、seedance-2.0-cl、seedance-2.0-cl-mini、moon-2.0-dj-fast、moon-2.0-wc-720p、moon-2.0-wc-b-720p、moon-2.0-wc-b-720p-fast、moon-2.0-wc-c-720p、moon-2.0-wc-d-720p、moon-2.0-wc-e-720p、moon-2.0-wc-f-720p、moon-2.0-gl-a-720p、moon-2.0-gl-a-720p-fast、moon-2.0-ld-a、moon-2.0-am-720p-fast、moon-2.0-il-720p 和 grok-image-video。

seedance-2.0-cl、seedance-2.0-cl-fast 和 seedance-2.0-cl-mini 也可直接用 image_url / first_frame_url / video_url 提交公网 URL 或本模型线 ready 的 Asset://asset_xxx；三个型号的 generate_audio 均默认 true，显式传 false 可关闭生成音频；seedance-2.0-cl-mini 支持 480p / 720p，时长 4 - 15 秒。
moon-2.0-wc-720p、moon-2.0-wc-b-720p、moon-2.0-wc-b-720p-fast 使用公网 URL 或 MoonNexAI 托管 URL 写入 references[]；单次请求参考文件总数最多 12 个，其中图片最多 9 张、视频最多 3 个、音频最多 3 个。标准型号 moon-2.0-wc-720p 支持纯文本和 4 到 14 秒，兼容接受 15 秒并按 14 秒生成；B 和 B Fast 不支持纯文本，支持 4 到 15 秒。
moon-2.0-wc-c-720p 支持 4 到 15 秒目标时长、纯文本或最多 9 张参考图；不支持视频和音频。
moon-2.0-wc-d-720p 支持 4 到 15 秒目标时长、纯文本或最多 4 张图片 + 3 个视频 + 1 个音频；音频必须与图片或视频一起提交。
moon-2.0-wc-e-720p 支持 4 到 15 秒目标时长、纯文本或最多 4 张图片 + 3 个视频 + 1 个音频；音频必须与图片或视频一起提交。
moon-2.0-wc-f-720p 支持 720P、4 到 15 秒、纯文本或图片/视频/音频参考，支持真人；最多 9 张图片、3 个视频、3 个音频，references[] 合计最多 12 个，音频必须与图片一起提交。
moon-2.0-ld-a 支持 720P 和 5 至 15 秒；图片最多 9 张、视频最多 3 个、音频最多 3 个，素材合计最多 15 个；人物参考图不要求必须是仅人脸图片。
moon-2.0-dj-fast 只支持图片参考，最多 9 张，时长仅支持 5、10、15 秒；参考图不要求必须是人脸图，可用于人物、服装、产品、场景和风格参考。
moon-2.0-il-720p 支持 720P 和 4 到 14 秒；图片最多 9 张、视频最多 3 个、音频最多 3 个，素材合计最多 12 个；音频必须与图片一起提交。
grok-video-1.5 当前接口行为要求提供 1 张参考图，最高 15 秒；grok-image-video 支持最多 5 张参考图，最高 15 秒。

happyhorse-1.0 和 wan2.7 也使用本入口，具体素材边界见 HappyHorse / Wan 视频模型。

bash

curl https://moonnexai.com/v1/videos \
  -H "Authorization: Bearer <MOONNEXAI_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "moon-2.0-wc-720p",
    "prompt": "A cinematic product shot of @product, slow camera push-in, clean studio light.",
    "references": [
      {
        "media_type": "image",
        "role": "reference_image",
        "url": "https://example.com/product.png",
        "alias": "product"
      }
    ],
    "duration": 14,
    "aspect_ratio": "16:9",
    "callback_url": "https://example.com/moonnexai/webhook"
  }'

图生视频

json

{
  "model": "seedance-2.0-kz-fast",
  "prompt": "Animate the product with a slow rotating camera and soft studio light.",
  "images": [
    {
      "url": "https://example.com/product.png",
      "role": "first_frame"
    }
  ],
  "duration": 5,
  "aspect_ratio": "1:1"
}

如果素材已有稳定公网 URL，优先直接传 URL。如果你已经通过素材接口创建了可引用素材，并且所选模型支持素材引用，可以传入 Asset://asset_xxx。素材引用创建后可能还需要短暂准备；如果立即生成遇到素材暂不可用的错误，请等待一小段时间后用同一个素材引用重试：

json

{
  "model": "seedance-2.0-kz",
  "prompt": "Animate the product with a slow rotating camera and soft studio light.",
  "images": [
    {
      "url": "Asset://asset_xxx",
      "role": "reference_image"
    }
  ],
  "duration": 5,
  "aspect_ratio": "1:1"
}

已上传并审核通过的素材不会自动关联到视频任务。创建视频时必须在本次请求里显式传入图片 URL 或 Asset://asset_xxx；只传 input_type: "reference" 不会加载最近上传、最近审核通过或同分组里的素材。

Seedance-2 参考图视频也可以使用兼容 content[] 写法：

使用 content[] 时，图片、视频和音频条目建议显式填写 role。图片常用 reference_image、first_frame 或 last_frame，视频常用 reference_video，音频常用 reference_audio。为兼容历史请求，图片、视频和音频条目未填写 role 时会按媒体类型分别当作 reference_image、reference_video、reference_audio 处理；如果你需要首帧、尾帧、参考图绑定音频或其它特定用途，请务必显式传入对应 role。

json

{
  "model": "seedance-2.0-kz-fast",
  "prompt": "图中女孩对着镜头说“茄子”，360度环绕运镜",
  "mode": "fast",
  "resolution": "720p",
  "ratio": "adaptive",
  "duration": 5,
  "generate_audio": true,
  "watermark": false,
  "web_search": false,
  "input_type": "reference",
  "generation_type": "video",
  "content": [
    {
      "type": "image_url",
      "role": "reference_image",
      "image_url": {
        "url": "Asset://asset_xxx"
      }
    }
  ]
}

如果要把素材作为首帧使用，可以改成：

json

{
  "model": "seedance-2.0-kz-fast",
  "prompt": "图中女孩对着镜头说“茄子”，360度环绕运镜",
  "duration": 5,
  "ratio": "adaptive",
  "resolution": "720p",
  "first_frame_url": "Asset://asset_xxx"
}

seedance-2.0-cl-fast / seedance-2.0-cl / seedance-2.0-cl-mini 是独立标准兼容线路，支持公网 URL、MoonNexAI 托管 URL 和通过素材接口创建的 Asset://asset_xxx。请按 CL 模型线创建或确认素材，不要把 seedance-2.0-kz / seedance-2.0-kz-fast 模型线的素材 ID 直接混用到 CL 模型线：

json

{
  "model": "seedance-2.0-cl-fast",
  "prompt": "Animate this product image with a slow camera push-in and clean studio lighting.",
  "image_url": "https://example.com/product.png",
  "input_reference_role": "first_frame",
  "duration": 4,
  "ratio": "16:9",
  "resolution": "480p",
  "generate_audio": false,
  "watermark": false
}

多素材输入

图片、视频和音频素材优先直接传稳定公网 URL；如果素材需要复用，并且你已经创建了 MoonNexAI 素材，也可以在支持素材引用的模型中使用 Asset://asset_xxx。音频参考通常需要与图片或视频参考一起使用；不要只提交音频素材，否则任务可能被拒绝。

对 moon-2.0-wc-720p、moon-2.0-wc-b-720p、moon-2.0-wc-b-720p-fast 这类使用公网 URL 的多素材模型，参考图片、视频和音频建议使用可直接下载的媒体直链，并保留真实文件后缀，例如 .png、.mp4、.wav 或 .mp3。不要依赖登录态、Cookie、额外鉴权 Header、一次性下载页或复杂防盗链链接。这三个型号单次请求最多 12 个参考文件；图片最多 9 张、视频最多 3 个、音频最多 3 个，但三类合计不能超过 12 个。标准型号 moon-2.0-wc-720p 支持 4 到 14 秒；传入 15 秒时按 14 秒生成。

moon-2.0-wc-f-720p 同样使用公网 URL，接受图片、视频和音频参考。上限为 9 张图片、3 个视频、3 个音频，合计最多 12 个；音频必须搭配至少一张图片，只有视频不能满足该条件。音频作为背景音乐时，建议在提示词里明确写“使用 @音乐作为背景音乐”。

moon-2.0-ld-a 也推荐使用可直接下载且保留真实后缀的素材 URL，支持图片、视频和音频混合输入。该模型单次最多 9 张图片、3 个视频、3 个音频，三类合计最多 15 个；支持 5 至 15 秒，音频应与图片或视频一起提交。

json

{
  "model": "seedance-2.0-kz-fast",
  "prompt": "保留参考图中的人物外观，生成一段舞台演唱视频，镜头稳定推进。",
  "duration": 14,
  "resolution": "720p",
  "ratio": "16:9",
  "generate_audio": true,
  "content": [
    {
      "type": "image_url",
      "image_url": {
        "url": "Asset://asset_image_xxx"
      },
      "role": "reference_image"
    },
    {
      "type": "audio_url",
      "audio_url": {
        "url": "Asset://asset_audio_xxx"
      },
      "role": "reference_audio"
    }
  ]
}

对已覆盖通用素材写法的模型，首帧、尾帧和多参考图推荐使用标准 images 写法。其他模型请先查看对应模型页，不要默认套用同一组字段：

json

{
  "model": "moon-2.0-wc-720p",
  "prompt": "让 @hero 面向镜头自然挥手，保持主体一致。",
  "duration": 5,
  "references": [
    {
      "media_type": "image",
      "role": "reference_image",
      "url": "https://example.com/hero.jpg",
      "alias": "hero"
    }
  ],
  "ratio": "16:9"
}

moon-2.0-dj-fast 使用统一 references[]，当前只支持图片素材：

json

{
  "model": "moon-2.0-dj-fast",
  "prompt": "Use @product as the main subject, create a short clean product ad.",
  "duration": 10,
  "ratio": "16:9",
  "resolution": "720P",
  "references": [
    {
      "media_type": "image",
      "role": "reference_image",
      "url": "https://example.com/product.png",
      "alias": "product"
    }
  ]
}

moon-2.0-ld-a 的三张人物参考图 + 背景音频写法：

json

{
  "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": "音乐"
    }
  ]
}

Grok 视频也使用 /v1/videos。单图图生视频推荐 grok-video-1.5 + input_reference；多参考图视频推荐 grok-image-video + reference_image_urls 或 references[]。Grok 视频的 seconds 建议传字符串，例如 "15"：

json

{
  "model": "grok-image-video",
  "prompt": "综合多张参考图的角色特征和场景质感，输出一段稳定的镜头运动视频。",
  "seconds": "15",
  "aspect_ratio": "16:9",
  "size": "720P",
  "reference_image_urls": [
    "https://example.com/ref-1.jpg",
    "https://example.com/ref-2.jpg"
  ]
}

常用参数

字段	类型	说明
`model`	string	视频模型名。
`prompt`	string	视频描述。建议包含主体、场景、镜头、动作和风格。
`references`	array	可选。新接入复杂素材的推荐数组。条目格式为 `{ "media_type": "image", "role": "reference_image", "url": "...", "alias": "hero" }`。
`image` / `image_url`	string	可选。单张源图片 URL；兼容旧写法。已覆盖通用素材写法的模型新接入优先用 `references[]`。
`images`	array	可选。图片 URL 或素材引用数组。已覆盖通用素材写法的模型推荐条目格式为 `{ "url": "...", "role": "reference_image" }`。同一请求中请按模型页面要求选择首帧、尾帧或参考图用途，不要混用不兼容角色。
`reference_image_url` / `reference_image_urls`	string / array	可选。参考图 URL 或素材引用。
`input_reference`	string	可选。单张参考图或首帧图，适合 `grok-video-1.5`。
`first_frame_url` / `last_frame_url`	string	可选。首帧图和尾帧图。Grok 视频当前不建议使用尾帧。
`video` / `video_url`	string	可选。参考视频或待延展视频 URL；兼容旧写法。已覆盖通用素材写法的模型新接入优先用 `videos[]`。
`reference_video_url` / `reference_video_urls`	string / array	可选。参考视频 URL 或素材引用。部分模型不支持视频参考，请以对应模型页为准。
`videos`	array	可选。视频素材数组。已覆盖通用素材写法的模型推荐条目格式为 `{ "url": "...", "role": "reference_video" }`。部分模型不支持视频参考，请以对应模型页为准。
`audio` / `audio_url`	string	可选。参考音频 URL 或素材引用；兼容旧写法。已覆盖通用素材写法且支持独立音频的模型新接入优先用 `audios[]`。音频参考通常需要与图片或视频参考一起使用。
`audios`	array	可选。音频素材数组。已覆盖通用素材写法且支持独立音频的模型推荐条目格式为 `{ "url": "...", "role": "reference_audio" }`。不要只传音频素材。
`content`	array	可选。多媒体内容数组，支持 `text`、`image_url`、`video_url`、`audio_url` 条目。
`duration`	integer	可选。视频时长，具体取值以模型支持范围为准。
`seconds`	string	可选。部分兼容模型使用该字段表示时长。
`aspect_ratio` / `ratio`	string	可选。视频比例，例如 `16:9`、`9:16`、`1:1`。
`resolution`	string	可选。分辨率，例如 `480p`、`720p`、`1080p`。
`video_config`	object	可选。兼容格式，常见字段为 `aspect_ratio`、`resolution_name`。
`generate_audio`	boolean	可选。控制模型是否生成音频；`seedance-2.0-cl`、`seedance-2.0-cl-fast`、`seedance-2.0-cl-mini` 省略时默认 `true`，显式传 `false` 可关闭音频。
`generateAudio`	boolean	可选兼容字段，语义与 `generate_audio` 相同；新接入优先使用 `generate_audio`。
`metadata`	object	可选。扩展参数；也可放入 `content`、`duration`、`seconds`、`resolution` 等模型参数。
`callback_url`	string	可选。任务完成后接收回调的 HTTPS 地址。

references[] 条目的常见结构：

字段	类型	说明
`media_type`	string	素材类型。常见值为 `image`、`video`、`audio`、`music`。
`role`	string	素材用途。常见值为 `first_frame`、`last_frame`、`reference_image`、`reference_video`、`reference_audio`、`background_music`、`voice_reference`、`style_reference`、`character_reference`。音频参考通常需要同时提供图片或视频参考。
`url`	string	公网 URL、MoonNexAI 托管 URL，或模型明确支持时的 `Asset://asset_xxx`。
`alias`	string	可选。素材别名，不包含 `@`，并且同一请求内应唯一；在 prompt 中用 `@alias` 指代素材。省略时会按媒体类型依次生成 `图片1`、`视频1`、`音频1` 等内置顺序别名。
`asset_id` / `asset_ref`	string	可选。MoonNexAI 素材 ID 或素材引用。是否可直接生成取决于模型支持。

内置顺序别名兼容 @图片1 与 @图片 1 两种写法，视频N、音频N 同理；数字后可以直接继续正文，例如 @图片1保持人物外观。为便于阅读，仍建议在别名后加空格或标点。自定义别名必须与后续正文分隔，例如写成 @主体走到龙椅旁，不要写成 @主体走到龙椅旁。

别名无法匹配素材时返回 invalid_reference_alias；同一别名绑定多个不同素材时返回 duplicate_reference_alias。别名只负责把提示词与参考素材绑定，不保证多个参考人物在成片中一定保持独立身份；多人任务仍需在提示词中明确人物、位置、服装和动作。

content[] 条目的常见结构：

字段	类型	说明
`type`	string	`text`、`image_url`、`video_url` 或 `audio_url`。
`text`	string	文本内容。视频任务通常直接使用顶层 `prompt`。
`image_url.url`	string	图片 URL 或素材引用。
`video_url.url`	string	视频 URL 或素材引用。
`audio_url.url`	string	音频 URL 或素材引用。
`asset_id` / `asset-id`	string	可选。MoonNexAI 素材 ID。
`asset_url`	string	可选。素材引用地址，例如 `Asset://asset_xxx`。
`role`	string	媒体条目建议填写。常见值为 `reference_image`、`first_frame`、`last_frame`、`reference_video`、`reference_audio`；图片、视频或音频条目缺少 `role` 时会按媒体类型兼容为参考素材，但需要首帧、尾帧、参考图绑定音频等特定用途时必须显式填写。

响应示例

json

{
  "id": "task_01HX...",
  "object": "task",
  "status": "submitted",
  "model": "seedance-2.0-kz-fast",
  "created_at": 1710000000
}

兼容视频接口在任务成功后通常会把最终视频地址放在多个字段中，便于不同 SDK 读取。客户端应先判断 status，只有 succeeded 时才读取 URL；pending、submitted、running、failed 或 cancelled 都不要读取 URL，failed 时请读取 error：

json

{
  "id": "task_01HX...",
  "task_id": "task_01HX...",
  "object": "video",
  "model": "seedance-2.0-kz-fast",
  "status": "succeeded",
  "url": "https://example.com/result.mp4",
  "video_url": "https://example.com/result.mp4",
  "output": {
    "url": "https://example.com/result.mp4"
  },
  "metadata": {
    "url": "https://example.com/result.mp4"
  }
}

提交后要保存

字段	用途
`id` / `task_id`	后续查询任务状态和结果。
`model`	复盘参数、核对计费和排查问题。
`trace_id` / `request_id`	联系 MoonNexAI 排查时使用。
原始请求体	便于重试、对比和定位字段差异。

对话协议

向量

音频

模型

GPT Image

Ideogram 图像

Midjourney 任务

Seedance-2 视频

Moon-2 视频

创建视频任务

方法与路径

标准请求

图生视频

多素材输入

常用参数

响应示例

提交后要保存

相关页面

Ideogram 图像

Midjourney 任务

Seedance-2 视频

Moon-2 视频

创建视频任务 ​

方法与路径 ​

标准请求 ​

图生视频 ​

多素材输入 ​

常用参数 ​

响应示例 ​

提交后要保存 ​

相关页面 ​

创建视频任务

方法与路径

标准请求

图生视频

多素材输入

常用参数

响应示例

提交后要保存

相关页面