通用视频编辑 VACE

文档版本：v1.0.0 | 最后更新：2026-07-22
本平台已完整适配通义万相（Wan）官方视频生成接口，请求与响应均为透传，参数语义与官方一致。

万相 2.1 通用视频编辑统一模型（wanx2.1-vace-plus），支持文本 / 图像 / 视频多模态输入，通过 input.function 在同一接口内切换五种编辑能力。任务为异步调用：创建任务返回 output.task_id，再通过查询接口轮询结果，生成耗时通常约 5–10 分钟。

能力总览

function	能力	关键输入
`image_reference`	多图参考生视频	`ref_images_url`（1–3 张参考图，主体/背景）+ prompt，融合生成连贯视频
`video_repainting`	视频重绘	`video_url`，提取主体动作 / 构图轮廓 / 线稿结构（`control_condition`）后重新生成；可加 1 张参考图替换主体
`video_edit`	局部编辑	`video_url` + 掩码（`mask_image_url` / `mask_video_url` 二选一），对指定区域增加 / 修改 / 删除元素
`video_extension`	视频延展	首/尾帧图（`first_frame_url` / `last_frame_url`）或首/尾段视频（`first_clip_url` / `last_clip_url`），生成延续内容
`video_outpainting`	画面扩展	`video_url` + 四个方向扩展比例（`top_scale` 等），向画面外扩展内容

输出规格

项	规则
时长	固定 5 秒（`duration` 固定为 5，不可修改）。视频重绘 / 局部编辑 / 画面扩展：输出时长 = 输入时长，最长 5 秒（输入 3s → 输出 3s，输入 6s → 输出前 5s）
分辨率	仅 720P 档。`image_reference` 由 `size` 指定（默认 `1280*720`）；输入视频类能力：输入 ≤720P 保留原分辨率，>720P 按宽高比缩放至不超过 720P
格式	MP4（H.264 编码），下载 URL 有效期 24 小时，请及时转存
音频	仅生成无声视频，不支持音频输出

video_extension 时长提示（重点）：视频延展的输出总时长为 5 秒，是「输入片段 + 新生成内容」共 5 秒，并非在原视频基础上再延长 5 秒。例如传入 3 秒首段视频，仅新生成约 2 秒延续内容。

创建任务

POST https://platform.shuyanai.com/ali/api/v1/services/aigc/video-generation/video-synthesis

请求头

参数	类型	必填	默认值	说明
`Content-Type`	string	是	application/json	数据交换格式
`Authorization`	string	是		鉴权信息，`Bearer {API_KEY}`

官方要求的 X-DashScope-Async: enable 头由平台自动补充，调用时无需携带。

公共参数

所有 function 共用以下参数：

参数	类型	必填	默认值	说明
`model`	string	是		模型标识，固定为 `wanx2.1-vace-plus`
`input`	object	是		输入基本信息
`input.function`	string	是		能力开关：`image_reference`、`video_repainting`、`video_edit`、`video_extension`、`video_outpainting`
`input.prompt`	string	是		文本提示词，中英文均可，长度 ≤ 800 字符，超长自动截断
`parameters`	object	视 function 而定		处理参数；`video_repainting` 下必填（须含 `control_condition`），其余可选
`parameters.duration`	integer	否	5	输出视频时长（秒），固定 5，不支持修改
`parameters.prompt_extend`	boolean	否	true	是否开启提示词智能改写。输入含视频的能力推荐设为 false（文本与视频内容不一致时改写易产生误解）
`parameters.seed`	integer	否	随机	随机种子，范围 [0, 2147483647]，相同 seed 结果相对稳定
`parameters.watermark`	boolean	否	false	是否在视频右下角添加「AI生成」水印

以下按 function 分别列出专属字段。

image_reference（多图参考生视频）

input 专属字段：

参数	类型	必填	默认值	说明
`input.ref_images_url`	array[string]	是		参考图 URL 数组，1–3 张（超过 3 张仅取前 3 张）。建议：主体图每张仅含一个主体、纯色背景；背景图最多 1 张且不含主体

parameters 专属字段：

参数	类型	必填	默认值	说明
`parameters.obj_or_bg`	array[string]	否	单图时 `["obj"]`	与 `ref_images_url` 一一对应标识每张图用途：`obj` 主体图 / `bg` 背景图（`bg` 最多 1 个）。建议显式传入，且长度须与 `ref_images_url` 一致，否则报错。示例：`["obj","obj","bg"]`
`parameters.size`	string	否	1280*720	输出分辨率（仅 720P 档）：`1280720`(16:9)、`7201280`(9:16)、`960960`(1:1)、`8321088`(3:4)、`1088*832`(4:3)

video_repainting（视频重绘）

input 专属字段：

参数	类型	必填	默认值	说明
`input.video_url`	string	是		输入视频 URL，限制见「输入素材通用限制」
`input.ref_images_url`	array[string]	否		仅 1 张，建议为主体图，用于替换视频中的主体（换角色、保留动作）

parameters 专属字段（本能力下 parameters 必填）：

参数	类型	必填	默认值	说明
`parameters.control_condition`	string	是		从输入视频提取的控制条件： `posebodyface`：脸部表情 + 肢体动作 `posebody`：仅肢体动作 `depth`：构图与运动轮廓 `scribble`：线稿结构
`parameters.strength`	float	否	1.0	控制强度，范围 [0.0, 1.0]，越大越贴近原视频的动作与构图

video_edit（局部编辑）

input 专属字段：

参数	类型	必填	默认值	说明
`input.video_url`	string	是		输入视频 URL，限制见「输入素材通用限制」
`input.ref_images_url`	array[string]	否		仅 1 张，可作主体图或背景图，用于替换编辑区域内容
`input.mask_image_url`	string	否		掩码图 URL，与 `mask_video_url` 二选一（推荐优先本参数）。白色 [255,255,255] = 编辑区，黑色 [0,0,0] = 保留区。分辨率须与输入视频严格相同
`input.mask_frame_id`	integer	否	1	`mask_image_url` 非空时生效，掩码目标所在帧 ID。范围 [1, max_frame_id]，max_frame_id = 帧率 × 时长 + 1（如 16FPS × 5s → 81）
`input.mask_video_url`	string	否		掩码视频 URL，与 `mask_image_url` 二选一。格式 / 帧率 / 分辨率 / 长度须与输入视频完全一致，黑白语义同上

parameters 专属字段：

参数	类型	必填	默认值	说明
`parameters.control_condition`	string	否	空（不提取）	可选 `posebodyface`、`depth`；`posebodyface` 适用主体脸部占比大、特征清晰的场景
`parameters.mask_type`	string	否	tracking	`mask_image_url` 非空时生效：`tracking` 编辑区随目标运动轨迹跟随；`fixed` 编辑区固定不变
`parameters.expand_ratio`	float	否	0.05	`mask_type=tracking` 时生效，掩码向外扩展比例，范围 [0.0, 1.0]，推荐默认值
`parameters.expand_mode`	string	否	hull	`mask_type=tracking` 时生效，掩码区域形状：`hull`（多边形）/ `bbox`（矩形边界框）/ `original`（贴合原始形状）
`parameters.size`	string	否	1280*720	同 image_reference 的五档取值

video_extension（视频延展）

input 专属字段（首/尾帧图、首/尾段视频均可选，按需组合，至少提供一项）：

参数	类型	必填	说明
`input.first_frame_url`	string	否	首帧图 URL，由该帧向后延展
`input.last_frame_url`	string	否	尾帧图 URL，向该帧收束
`input.first_clip_url`	string	否	首段视频 URL，长度 ≤ 3 秒（超出取前 3 秒）；与尾段同时使用时两段总时长 ≤ 3 秒，建议帧率一致
`input.last_clip_url`	string	否	尾段视频 URL，限制同 `first_clip_url`
`input.video_url`	string	否	参考视频，用于提取运动特征指导生成，与首尾帧/首尾段配合使用。长度 ≤ 5 秒；帧率 ≥ 16FPS 且与首尾片段一致；分辨率与首尾帧/片段一致

parameters 专属字段：

参数	类型	必填	默认值	说明
`parameters.control_condition`	string	传 `video_url` 时必填	空（不提取）	可选 `posebodyface`、`depth`

再次提示：输出总时长固定 5 秒，包含传入的首/尾段视频本身，并非在原视频上追加 5 秒。

video_outpainting（画面扩展）

input 专属字段：

参数	类型	必填	默认值	说明
`input.video_url`	string	是		输入视频 URL，限制见「输入素材通用限制」

parameters 专属字段（四个方向比例均以画面居中为基准，1.0 = 不扩展）：

参数	类型	必填	默认值	说明
`parameters.top_scale`	float	否	1.0	向上扩展比例，范围 [1.0, 2.0]
`parameters.bottom_scale`	float	否	1.0	向下扩展比例，范围 [1.0, 2.0]
`parameters.left_scale`	float	否	1.0	向左扩展比例，范围 [1.0, 2.0]
`parameters.right_scale`	float	否	1.0	向右扩展比例，范围 [1.0, 2.0]

输入素材通用限制

素材	限制
图像（参考图 / 掩码图 / 首尾帧）	格式 JPG、JPEG、PNG、BMP、TIFF、WEBP；宽高在 [360, 2000] 像素；≤ 10MB；URL 不含中文字符。掩码图分辨率须与输入视频严格相同
视频（`video_url` 等）	格式 MP4；帧率 ≥ 16FPS；≤ 50MB；长度 ≤ 5 秒（超出取前 5 秒；video_extension 的 clip ≤ 3 秒）；URL 不含中文字符
URL 形式	公网可访问的 HTTP/HTTPS 地址
参考图张数	`image_reference`：1–3 张（bg 最多 1 张）；`video_repainting` / `video_edit`：仅 1 张

请求示例：多图参考生视频（image_reference）

curl --request POST \
  --url 'https://platform.shuyanai.com/ali/api/v1/services/aigc/video-generation/video-synthesis' \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "wanx2.1-vace-plus",
    "input": {
      "function": "image_reference",
      "prompt": "视频中，一位女孩自晨雾缭绕的古老森林深处款款走出，步伐轻盈",
      "ref_images_url": [
        "http://wanx.alicdn.com/material/20250318/image_reference_2_5_16.png",
        "http://wanx.alicdn.com/material/20250318/image_reference_1_5_16.png"
      ]
    },
    "parameters": {
      "prompt_extend": true,
      "obj_or_bg": ["obj", "bg"],
      "size": "1280*720"
    }
  }'

请求示例：视频重绘（video_repainting）

curl --request POST \
  --url 'https://platform.shuyanai.com/ali/api/v1/services/aigc/video-generation/video-synthesis' \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "wanx2.1-vace-plus",
    "input": {
      "function": "video_repainting",
      "prompt": "视频展示了一辆黑色的蒸汽朋克风格汽车，绅士驾驶，车辆装饰着齿轮和铜管",
      "video_url": "http://wanx.alicdn.com/material/20250318/video_repainting_1.mp4"
    },
    "parameters": {
      "prompt_extend": false,
      "control_condition": "depth"
    }
  }'

请求示例：视频延展（video_extension）

curl --request POST \
  --url 'https://platform.shuyanai.com/ali/api/v1/services/aigc/video-generation/video-synthesis' \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "wanx2.1-vace-plus",
    "input": {
      "function": "video_extension",
      "prompt": "一只戴着墨镜的狗在街道上滑滑板，3D卡通",
      "first_clip_url": "http://wanx.alicdn.com/material/20250318/video_extension_1.mp4"
    },
    "parameters": {
      "prompt_extend": false
    }
  }'

响应示例

{
  "output": {
    "task_status": "PENDING",
    "task_id": "0385dc79-5ff8-4d82-bcb6-xxxxxx"
  },
  "request_id": "4909100c-7b5a-9f92-bfe5-xxxxxx"
}

响应字段

字段	类型	说明
`output.task_id`	string	任务 ID，用于查询结果，有效期 24 小时
`output.task_status`	string	任务状态，创建成功时为 `PENDING`
`request_id`	string	请求唯一标识，用于溯源排查
`code` / `message`	string	仅创建失败时返回，错误码与详情（如 `InvalidParameter`：size 不匹配、`obj_or_bg` 长度与 `ref_images_url` 不一致等）

计费说明

按输出视频秒数计费（定性说明，单价以平台价格页为准）。任务成功后以查询结果中的 usage 字段为计费依据；输出固定 720P 档、最长 5 秒。任务失败不产生费用。

查询任务

通过创建任务返回的 task_id 轮询任务状态，成功后从 output.video_url 获取视频（有效期 24 小时）。

GET https://platform.shuyanai.com/ali/api/v1/tasks/{task_id}

详见 09-查询任务。

08-通用视频编辑-VACE

通用视频编辑 VACE#

能力总览#

输出规格#

创建任务#

请求头#

公共参数#

image_reference（多图参考生视频）#

video_repainting（视频重绘）#

video_edit（局部编辑）#

video_extension（视频延展）#

video_outpainting（画面扩展）#

输入素材通用限制#

请求示例：多图参考生视频（image_reference）#

请求示例：视频重绘（video_repainting）#

请求示例：视频延展（video_extension）#

响应示例#

响应字段#

计费说明#

查询任务#

通用视频编辑 VACE

能力总览

输出规格

创建任务

请求头

公共参数

image_reference（多图参考生视频）

video_repainting（视频重绘）

video_edit（局部编辑）

video_extension（视频延展）

video_outpainting（画面扩展）

输入素材通用限制

请求示例：多图参考生视频（image_reference）

请求示例：视频重绘（video_repainting）

请求示例：视频延展（video_extension）

响应示例

响应字段

计费说明

查询任务