视频生成

MoonNexAI 视频接口用于创建文生视频、图生视频和带素材引用的视频任务。视频任务通常需要异步处理：提交任务后先得到 task_id，再通过任务查询接口或回调获取最终结果。

基本流程

选择视频模型，并确认模型支持的比例、时长和输入方式。
如需使用图片或视频素材，正式业务应直接传客户自有存储的公网 URL；只有联调测试需要临时 OSS URL，或目标模型明确需要素材 ID 时，才调用素材接口。
调用 POST /v1/videos 创建任务。
保存响应中的 id，通过 GET /v1/tasks/{task_id} 查询状态。
任务成功后读取 output[].url、output.url、url、video_url、result_url 或 metadata.url，并在业务系统中保存结果；失败或未完成任务不要读取结果 URL。

输入素材边界

MoonNexAI 不会因为你选择某个视频模型，就自动帮你创建托管 URL 或素材 ID。素材入口是显式能力：

输入方式	适合场景	是否先调用素材接口
客户自己的公网 URL	文件已经有稳定可访问地址，或只在一次任务中使用。	不需要。直接在视频请求中传 URL。
二进制文件	生成接口本身支持 multipart/binary 输入。	不需要走 `/v1/assets/uploads`，按对应生成接口要求直接提交文件。
MoonNexAI OSS 测试 URL	仅用于联调或测试本地文件。MoonNexAI 不保证长期保存或持续可用。	显式调用 `/v1/assets/uploads`，使用 `mode=oss`。
`Asset://asset_xxx` 素材引用	目标模型要求先创建素材 ID，且该模型支持素材引用。	需要显式调用 `/v1/assets/uploads`，优先使用 `mode=asset`。

只有联调时同时需要 MoonNexAI OSS 测试 URL 和 Asset://asset_xxx 模型素材引用时，才使用 mode=both。OSS 上传和素材认证均免费，但 mode=both 会带来两类准备状态，不建议作为默认选择。

MoonNexAI OSS 不提供长期存储服务等级承诺，也不承诺文件保存期限或 URL 有效期。正式业务和长期任务必须由客户自行提供无需登录或额外请求头、可匿名公网访问且在任务执行期间持续有效的素材直链。

POST /v1/videos 是统一任务入口，不等于所有视频模型都支持同一套素材字段。已覆盖 MoonNexAI 通用素材写法的模型，新接入复杂素材推荐用 references[] + media_type + role + url + alias；images[] / videos[] / audios[] 和 content[] 继续作为兼容写法。

references[].alias 不包含 @，同一请求内应唯一。省略 alias 时，系统按媒体类型生成 图片1、图片2、视频1、音频1 等内置顺序别名。提示词可写 @图片1 或兼容写法 @图片 1，数字后可以直接继续正文，例如 @图片1保持主体外观；视频N、音频N 同理。自定义别名必须与后续正文用空格或标点分隔，例如 @主体保持外观。

Seedance-2 与 Moon-2 素材策略

分组速查表

分组	代表模型	公网 URL	MoonNexAI OSS 测试 URL	`Asset://` 素材引用	使用建议
seedance-2.0-kz 系列	`seedance-2.0-kz-fast`、`seedance-2.0-kz`	推荐	支持	支持	想用首尾帧、多模态参考、素材复用时优先选这组。
seedance-2.0-cl 系列	`seedance-2.0-cl-fast`、`seedance-2.0-cl`、`seedance-2.0-cl-mini`	推荐	支持	支持	标准兼容线路，支持按 CL 模型线创建和使用图片、视频素材引用；`seedance-2.0-cl-mini` 支持 480P / 720P、`4` - `15` 秒；视频参考建议先创建本模型线 `Asset://` 后再生成。
moon-2.0-dj 系列	`moon-2.0-dj-fast`	推荐	支持	不作为主路径	适合 720P 按秒、文生视频、图生视频和最多 9 张图片参考；参考图不要求必须是人脸图；不支持视频参考和独立音频。
moon-2.0-wc 系列	`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`	推荐	支持	不作为当前输入路径	适合 720P 按次任务；七个型号均支持真人。基础、B 和 B Fast 最多 9 图 + 3 视频 + 3 音频且总计最多 12 个，其中 B / B Fast 不支持纯文本；F 最多 9 图 + 3 视频 + 3 音频，总计最多 12 个且音频必须带图片；C 支持最多 9 图且禁止视频/音频；D / E 支持 4 图 + 3 视频 + 1 音频且禁止纯音频。
moon-2.0-ld 系列	`moon-2.0-ld-a`	推荐	支持	支持	适合 720P 按次、`5` 至 `15` 秒、多人物与姿势参考、多图片、多视频和背景音频组合；素材合计最多 15 个。
moon-2.0-am 系列	`moon-2.0-am-720p-fast`	推荐	支持	不作为当前输入路径	适合 720P 按次快速生成、单图、图片 + 背景音乐和多素材公网 URL 组合；推荐把公网 URL 写入 `references[]`。
moon-2.0-il 系列	`moon-2.0-il-720p`	推荐	支持	不作为当前输入路径	适合 720P 按秒、4 到 14 秒、多图片、多视频和音频组合；素材合计最多 12 个。
HappyHorse / Wan	`happyhorse-1.0`、`wan2.7`	推荐	支持	以模型支持为准	`happyhorse-1.0` 支持文生视频、首帧和参考图；`wan2.7` 额外支持尾帧和参考视频。

哪些组最适合素材复用

seedance-2.0-kz 系列最适合直接写进“素材引用 + 多模态参考”的工作流。
seedance-2.0-cl 系列支持直接传公网 URL，也支持通过素材接口创建本模型线可用的 Asset://asset_xxx；图片可以直接传稳定公网 URL，视频参考建议先创建 type=video、role=reference_video 的素材引用后再传给 video_url。seedance-2.0-cl-mini 使用相同参数体系，当前支持 480p / 720p。
moon-2.0-dj 系列使用 references[] 传图片参考，最多 9 张，时长只传 5、10、15 秒；参考图可用于人物全身、服装、产品、场景和风格等视觉参考，不要求必须是人脸图。
moon-2.0-wc 系列使用 references[] 传参考素材。基础、B 和 B Fast 单次最多 12 个参考文件，其中图片最多 9 张、视频最多 3 个、音频最多 3 个；F 支持纯文本和 4 到 15 秒，图片最多 9 张、视频最多 3 个、音频最多 3 个，总计最多 12 个且音频必须带图片；C 最多 9 张图片且不接受视频/音频；D / E 最多 4 图 + 3 视频 + 1 音频且禁止纯音频。复杂组合正式业务使用客户自有公网 URL；mode=oss 仅用于本地文件联调。
moon-2.0-ld-a 使用 references[] 传图片、视频和音频参考，支持 5 至 15 秒和 720P；图片最多 9 张、视频最多 3 个、音频最多 3 个，合计最多 15 个。人物参考图不要求必须是仅人脸图片，音频应与图片或视频一起使用。
moon-2.0-am 系列使用 references[] 传图片、视频和音频参考，适合 720P 按次快速任务；正式业务使用客户自有公网 URL，mode=oss 仅用于本地文件联调，不建议音频-only 任务。
moon-2.0-il 系列使用 references[] 传图片、视频和音频参考，支持 4 到 14 秒；图片最多 9 张、视频最多 3 个、音频最多 3 个，合计最多 12 个，音频必须与图片一起提交。
happyhorse-1.0 和 wan2.7 使用通用视频入口；happyhorse-1.0 不支持尾帧和参考视频，wan2.7 支持尾帧和参考视频，但不支持独立音频。

创建任务

bash

curl https://moonnexai.com/v1/videos \
  -H "Authorization: Bearer <MOONNEXAI_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-2.0-kz-fast",
    "prompt": "A cinematic close-up of a glass perfume bottle on a reflective table.",
    "duration": 5,
    "aspect_ratio": "16:9",
    "callback_url": "https://example.com/moonnexai/webhook"
  }'

常用参数：

字段	类型	说明
`model`	string	视频模型名。
`prompt`	string	视频描述。建议包含主体、场景、镜头、动作和风格。
`image` / `image_url`	string	可选。单张源图片 URL；模型支持时也可以是 `Asset://asset_xxx`。
`references`	array	可选。新接入复杂素材的推荐数组，条目包含 `media_type`、`role`、`url` 和可选 `alias`。
`images`	array	可选。按图片类型拆分的兼容数组，可放多张图片 URL 或素材引用。
`reference_image_url` / `reference_image_urls`	string / array	可选。参考图 URL 或素材引用。
`first_frame_url` / `last_frame_url`	string	可选。首帧图和尾帧图。
`video` / `video_url`	string	可选。参考视频或待延展视频 URL。
`reference_video_url` / `reference_video_urls`	string / array	可选。参考视频 URL 或素材引用。
`audio` / `audio_url`	string	可选。参考音频 URL 或素材引用。
`content`	array	可选。多媒体内容数组，支持图片、视频、音频和文本条目；以对应模型页说明为准。
`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	可选。模型支持时生成或保留音频。
`metadata`	object	可选。扩展参数；可放入模型支持的 `content`、`duration`、`resolution` 等字段。
`callback_url`	string	可选。任务完成后接收回调的 HTTPS 地址。

图生视频

图生视频需要传入 image、image_url、reference_image_url、reference_image_urls、images 或 content[] 中的图片条目。正式业务应直接传客户自有存储的稳定公网 URL；只有联调本地文件，或目标模型明确要求素材 ID 时，才先通过素材接口上传。

json

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

首尾帧和多媒体内容

对支持首尾帧的模型，可以直接使用 first_frame_url / last_frame_url，也可以在 references[]、images[] 或 content[] 中用 role 标记。未明确支持尾帧的模型不要传 last_frame_url。

json

{
  "model": "seedance-2.0-kz-fast",
  "prompt": "从第一张图自然过渡到第二张图，保持主体一致。",
  "duration": 5,
  "images": [
    {
      "url": "https://example.com/first-frame.jpg",
      "role": "first_frame"
    },
    {
      "url": "https://example.com/last-frame.jpg",
      "role": "last_frame"
    }
  ],
  "ratio": "16:9"
}

已覆盖通用素材写法或兼容 content[] 的模型，可以用多媒体内容组合图片、视频和音频参考。新接入优先看对应模型页是否推荐 references[]：

json

{
  "model": "seedance-2.0-kz",
  "prompt": "保留参考图中的人物外观，生成一段舞台演唱视频。",
  "duration": 5,
  "ratio": "16:9",
  "resolution": "720p",
  "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"
    }
  ]
}

使用 MoonNexAI 托管素材时：

json

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

视频参考素材

如果模型支持参考视频，可以直接传稳定公网视频 URL。对于 seedance-2.0-cl / seedance-2.0-cl-fast / seedance-2.0-cl-mini 这类支持素材引用的模型，建议先把参考视频创建为本模型线可用的 Asset://asset_xxx，再在生成请求中传给 video_url 或 reference_video_url。图片参考不强制创建素材 ID，稳定公网 URL 可以直接传给 image_url。

创建视频素材引用：

bash

curl https://moonnexai.com/v1/assets/uploads \
  -H "Authorization: Bearer <MOONNEXAI_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-2.0-cl",
    "mode": "asset",
    "type": "video",
    "purpose": "reference_video",
    "role": "reference_video",
    "url": "https://example.com/reference.mp4"
  }'

使用视频素材和图片 URL 创建任务：

json

{
  "model": "seedance-2.0-cl",
  "prompt": "将视频中人物上衣替换为参考图片上的图案，保持原视频动作和镜头节奏。",
  "video_url": "Asset://asset_video_xxx",
  "image_url": "https://example.com/reference-shirt.png",
  "duration": 5
}

查询任务

bash

curl https://moonnexai.com/v1/tasks/task_01HX... \
  -H "Authorization: Bearer <MOONNEXAI_API_KEY>"

任务状态：

状态	说明
`pending`	系统准备中。
`submitted`	已提交，等待处理。
`running`	正在生成。
`succeeded`	已完成，可读取结果 URL。
`failed`	任务失败，查看 `error` 字段。
`cancelled`	任务已取消。

取消任务

未完成的视频任务可以调用取消接口。取消成功后，MoonNexAI 会先将任务标记为取消并退还预扣额度；如果当前模型支持停止正在执行的生成，MoonNexAI 会额外尝试停止正在生成的任务。

bash

curl -X POST https://moonnexai.com/v1/videos/task_01HX.../cancel \
  -H "Authorization: Bearer <MOONNEXAI_API_KEY>"

取消响应示例：

json

{
  "id": "task_01HX...",
  "object": "video",
  "status": "cancelled",
  "cancelled": true,
  "refund_requested": true,
  "remote_cancel": {
    "attempted": true,
    "supported": false,
    "succeeded": false,
    "error": ""
  },
  "trace_id": "2026060301010100000000000000000000",
  "request_id": "2026060301010100000000000000000000",
  "task_chain": [
    {
      "step": "cancel",
      "status": "succeeded"
    },
    {
      "step": "billing",
      "status": "refunded"
    }
  ]
}

说明：

已成功任务不能取消。
已失败任务再次取消不会重复退款。
remote_cancel.supported=false 表示当前模型不支持或尚未确认支持停止进行中的生成；这不影响 MoonNexAI 侧取消和退款。
删除已生成视频或删除结果资产，不等同于取消进行中的生成任务。

查询响应中可能包含这些排障字段：

字段	说明
`trace_id` / `request_id`	MoonNexAI 本次请求链路 ID。联系 MoonNexAI 排障时请提供。
`task_chain`	任务链摘要，常见步骤包括生成状态、结果地址处理状态和素材准备状态。

结果 URL 策略会体现在 task_chain[].result_url_policy。客户侧只会收到 MoonNexAI 自有受控地址，例如 media-nex.windfimusic.com 官方转存媒体 URL 或标准内容下载入口；该媒体域名由 MoonNexAI 管理。客户端应原样保存并使用接口返回的完整地址，包括全部签名查询参数。

如果使用 GET /v1/videos/{task_id}/content 下载结果，请只在任务 succeeded 后调用，并让客户端跟随 302 重定向。该入口优先跳转到 MoonNexAI 媒体 URL，只有托管媒体不可用时才可能回退为代理视频流。

Prompt 建议

用一句话说明主体和动作，例如“香水瓶缓慢旋转，镜头从左向右推进”。
明确画幅和用途，例如“竖屏短视频广告”或“横屏产品展示”。
如果使用参考图，prompt 中说明希望保留的主体、材质、颜色和构图。
避免一次要求过多镜头切换，短视频更适合单一清晰动作。

更多参数和响应结构见 API Reference。

对话协议

向量

音频

模型

GPT Image

Ideogram 图像

Midjourney 任务

Seedance-2 视频

Moon-2 视频

视频生成

基本流程

输入素材边界

Seedance-2 与 Moon-2 素材策略

分组速查表

哪些组最适合素材复用

创建任务

图生视频

首尾帧和多媒体内容

视频参考素材

查询任务

取消任务

Prompt 建议

Ideogram 图像

Midjourney 任务

Seedance-2 视频

Moon-2 视频

视频生成 ​

基本流程 ​

输入素材边界 ​

Seedance-2 与 Moon-2 素材策略 ​

分组速查表 ​

哪些组最适合素材复用 ​

创建任务 ​

图生视频 ​

首尾帧和多媒体内容 ​

视频参考素材 ​

查询任务 ​

取消任务 ​

Prompt 建议 ​

视频生成

基本流程

输入素材边界

Seedance-2 与 Moon-2 素材策略

分组速查表

哪些组最适合素材复用

创建任务

图生视频

首尾帧和多媒体内容

视频参考素材

查询任务

取消任务

Prompt 建议