创建视频任务

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

方法与路径

http

POST /v1/videos

兼容入口：

http

POST /v1/video/generations

标准请求

POST /v1/videos 是统一的视频任务创建入口；不同模型支持的输入素材字段并不完全相同。已覆盖 MoonApiX 通用素材写法的模型，推荐使用 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、seedance-2.0-ld-17、seedance-2.0-dj-fast、seedance-2.0-qm-720p 和 seedance-2.0-wc-720p。

seedance-2.0-cl 系列也可直接用 image_url / first_frame_url / video_url 提交公网 URL 或本模型线 ready 的 Asset://asset_xxx；seedance-2.0-cl-mini 支持 480p / 720p，时长 4 - 15 秒。
seedance-2.0-wc-720p 使用公网 URL 或 MoonApiX 托管 URL 写入 references[]；prompt 最多 1000 个字符，超过限制会在提交阶段被拒绝。
seedance-2.0-dj-fast 只支持图片参考，最多 10 张，时长仅支持 5、10、15 秒。
seedance-2.0-me 继续支持 images[] / content[] 图片条目，但不支持视频参考；首帧和参考图不要在同一次请求里混合。

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

bash

curl https://moonapix.com/v1/videos \
  -H "Authorization: Bearer <MOONAPIX_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-2.0-ld-17",
    "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": 5,
    "aspect_ratio": "16:9",
    "callback_url": "https://example.com/moonapix/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、MoonApiX 托管 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",
  "watermark": false
}

多素材输入

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

json

{
  "model": "seedance-2.0-kz-fast",
  "prompt": "保留参考图中的人物外观，生成一段舞台演唱视频，镜头稳定推进。",
  "duration": 5,
  "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": "seedance-2.0-ld-17",
  "prompt": "让 @hero 面向镜头自然挥手，保持主体一致。",
  "duration": 5,
  "references": [
    {
      "media_type": "image",
      "role": "reference_image",
      "url": "https://example.com/hero.jpg",
      "alias": "hero"
    }
  ],
  "ratio": "16:9"
}

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

json

{
  "model": "seedance-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"
    }
  ]
}

常用参数

字段	类型	说明
`model`	string	视频模型名。
`prompt`	string	视频描述。建议包含主体、场景、镜头、动作和风格。`seedance-2.0-wc-720p` 最多 1000 个字符。
`references`	array	可选。新接入复杂素材的推荐数组。条目格式为 `{ "media_type": "image", "role": "reference_image", "url": "...", "alias": "hero" }`。
`image` / `image_url`	string	可选。单张源图片 URL；兼容旧写法。已覆盖通用素材写法的模型新接入优先用 `references[]`。
`images`	array	可选。图片 URL 或素材引用数组。已覆盖通用素材写法的模型推荐条目格式为 `{ "url": "...", "role": "reference_image" }`。`seedance-2.0-me` 下不要混合 `first_frame` 和 `reference_image`。
`reference_image_url` / `reference_image_urls`	string / array	可选。参考图 URL 或素材引用。
`first_frame_url` / `last_frame_url`	string	可选。首帧图和尾帧图。
`video` / `video_url`	string	可选。参考视频或待延展视频 URL；兼容旧写法。已覆盖通用素材写法的模型新接入优先用 `videos[]`。
`reference_video_url` / `reference_video_urls`	string / array	可选。参考视频 URL 或素材引用。`seedance-2.0-me` 和 `happyhorse-1.0` 不支持视频参考。
`videos`	array	可选。视频素材数组。已覆盖通用素材写法的模型推荐条目格式为 `{ "url": "...", "role": "reference_video" }`。`seedance-2.0-me` 和 `happyhorse-1.0` 不支持视频参考。
`audio` / `audio_url`	string	可选。参考音频 URL 或素材引用；兼容旧写法。已覆盖通用素材写法且支持独立音频的模型新接入优先用 `audios[]`。`seedance-2.0-ld-17` 的音频参考需要与图片或视频参考一起使用。
`audios`	array	可选。音频素材数组。已覆盖通用素材写法且支持独立音频的模型推荐条目格式为 `{ "url": "...", "role": "reference_audio" }`。`seedance-2.0-ld-17` 不要只传音频素材。
`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	可选。模型支持时生成或保留音频。
`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`。`reference_audio` 用于 `seedance-2.0-ld-17` 时需要同时提供图片或视频参考。
`url`	string	公网 URL、MoonApiX 托管 URL，或模型明确支持时的 `Asset://asset_xxx`。
`alias`	string	可选。素材别名，便于在 prompt 中用 `@alias` 指代素材。
`asset_id` / `asset_ref`	string	可选。MoonApiX 素材 ID 或素材引用。是否可直接生成取决于模型支持。

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	可选。MoonApiX 素材 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`	联系 MoonApiX 排查时使用。
原始请求体	便于重试、对比和定位字段差异。

对话协议

向量

音频

模型

Ideogram 图像

Midjourney 任务

Seedance-2 视频

创建视频任务

方法与路径

标准请求

图生视频

多素材输入

常用参数

响应示例

提交后要保存

相关页面

Ideogram 图像

Midjourney 任务

Seedance-2 视频

创建视频任务 ​

方法与路径 ​

标准请求 ​

图生视频 ​

多素材输入 ​

常用参数 ​

响应示例 ​

提交后要保存 ​

相关页面 ​

创建视频任务

方法与路径

标准请求

图生视频

多素材输入

常用参数

响应示例

提交后要保存

相关页面