视频生成

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

基本流程

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

输入素材边界

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

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

只有同时需要 MoonApiX 托管 URL 和 Asset://asset_xxx 模型素材引用时，才使用 mode=both。mode=both 会带来两类准备状态和两类计费，不建议作为默认选择。

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

Seedance-2 素材策略

分组速查表

分组	代表模型	公网 URL	MoonApiX 托管 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://` 后再生成。
seedance-2.0-ld 系列	`seedance-2.0-ld-17`	推荐	支持	不作为主路径	适合按次生成、文生视频、多视觉参考和轻量音频参考。
seedance-2.0-dj 系列	`seedance-2.0-dj-fast`	推荐	支持	不作为主路径	适合 720P 按秒、文生视频、图生视频和最多 10 张图片参考；不支持视频参考和独立音频。
seedance-2.0-wc 系列	`seedance-2.0-wc-720p`	推荐	支持	不作为当前输入路径	适合 720P 按次、多图片、多视频、多音频组合；推荐把公网 URL 写入 `references[]`；`prompt` 最多 1000 个字符。
seedance-2.0-me	`seedance-2.0-me`	推荐	支持	不建议作为主路径	适合 720P / 1080P、首帧、参考图和参考图绑定音频；不支持视频参考、尾帧和独立音频。
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。
seedance-2.0-dj 系列使用 references[] 传图片参考，最多 10 张，时长只传 5、10、15 秒。
seedance-2.0-wc 系列使用 references[] 传图片、视频和音频参考，最多 9 图 + 3 视频 + 3 音频，复杂组合建议使用公网 URL；本地文件可先通过 mode=oss 获取 MoonApiX 托管 URL；prompt 最多 1000 个字符。
seedance-2.0-me 适合直接传公网 URL 或 MoonApiX 托管 URL；新接入优先使用 images[] 表达首帧或参考图，不支持 videos[]。参考图绑定音频使用 content[] 参考图条目上的 reference_voice。
happyhorse-1.0 和 wan2.7 使用通用视频入口；happyhorse-1.0 不支持尾帧和参考视频，wan2.7 支持尾帧和参考视频，但不支持独立音频。

创建任务

bash

curl https://moonapix.com/v1/videos \
  -H "Authorization: Bearer <MOONAPIX_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/moonapix/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，可以直接传 URL。只有图片会被多次复用、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-ld-17",
  "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"
    }
  ]
}

使用 MoonApiX 托管素材时：

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://moonapix.com/v1/assets/uploads \
  -H "Authorization: Bearer <MOONAPIX_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://moonapix.com/v1/tasks/task_01HX... \
  -H "Authorization: Bearer <MOONAPIX_API_KEY>"

任务状态：

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

取消任务

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

bash

curl -X POST https://moonapix.com/v1/videos/task_01HX.../cancel \
  -H "Authorization: Bearer <MOONAPIX_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 表示当前模型不支持或尚未确认支持停止进行中的生成；这不影响 MoonApiX 侧取消和退款。
删除已生成视频或删除结果资产，不等同于取消进行中的生成任务。

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

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

结果 URL 策略会体现在 task_chain[].result_url_policy。如果结果地址可直接访问，MoonApiX 可能直接返回该地址；如果结果需要鉴权或代理，MoonApiX 会返回托管地址或内容代理地址。

Prompt 建议

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

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

对话协议

向量

音频

模型

Ideogram 图像

Midjourney 任务

Seedance-2 视频

视频生成

基本流程

输入素材边界

Seedance-2 素材策略

分组速查表

哪些组最适合素材复用

创建任务

图生视频

首尾帧和多媒体内容

视频参考素材

查询任务

取消任务

Prompt 建议

Ideogram 图像

Midjourney 任务

Seedance-2 视频

视频生成 ​

基本流程 ​

输入素材边界 ​

Seedance-2 素材策略 ​

分组速查表 ​

哪些组最适合素材复用 ​

创建任务 ​

图生视频 ​

首尾帧和多媒体内容 ​

视频参考素材 ​

查询任务 ​

取消任务 ​

Prompt 建议 ​

视频生成

基本流程

输入素材边界

Seedance-2 素材策略

分组速查表

哪些组最适合素材复用

创建任务

图生视频

首尾帧和多媒体内容

视频参考素材

查询任务

取消任务

Prompt 建议