# 通用视频编辑

**方法**: `POST`
**路径**: `/qwen/api/v1/services/aigc/video-generation/video-synthesis`

[官方api 文档](https://bailian.console.aliyun.com/?spm=5176.12818093_47.resourceCenter.1.3a9d2cc9l8f5UQ&userCode=okjhlpr5&tab=api#/api/?type=model&url=2922183)

基于输入的文本提示词、图片和视频，可执行多种视频编辑任务。例如，通过提取输入视频的运动特征，并结合提示词生成新的视频。
文档介绍通义万相-视频编辑统一模型的输入输出参数。该模型支持文本、图像、视频等多种模态输入，可执行多种视频生成与编辑任务。

## 请求参数

### Header 参数

```text
X-DashScope-Async
string
必需
示例:
enable
Content-Type
string
必需
示例:
application/json
Authorization
string
可选
默认值:
Bearer {{YOUR_API_KEY}}
```

### Body 参数 application/json 必填

```text
model
string
必需
input
object
必需
function
string
必需
功能名称。局部编辑设置为 video_edit。
局部编辑支持对输入视频的指定区域进行增加、修改或删除元素，还可以对编辑区域的主体或背景进行替换，实现精细化的视频编辑。
prompt
string
必需
提示词，用来描述生成视频中期望包含的元素和视觉特点。
支持中英文，长度不超过800个字符，每个汉字/字母占一个字符，超过部分会自动截断。
提示词技巧请参见文生视频/图生视频Prompt指南。
video_url
string
必需
输入视频的URL地址。
URL 需为公网可访问地址，支持 HTTP 或 HTTPS 协议。如需获取本地文件的公网URL，请参见上传文件获取临时URL 。
视频限制：
视频格式：MP4。
视频帧率：大于等于16FPS。
视频大小：不超过50MB。
视频长度：不超过5秒，否则取视频的前5秒。
URL地址中不能包含中文字符。
关于输出视频的分辨率：
若输入视频分辨率 ≤ 720P，输出将保留原始分辨率；
若输入视频分辨率 > 720P，则在保持原视频宽高比的前提下，按比例缩放至不超过 720P。
关于输出视频的时长：
输出视频时长与输入视频一致，最长不超过 5 秒。
示例：若输入视频为 3 秒，则输出也为 3 秒；若输入为 6 秒，则输出为前 5 秒。
ref_images_url
array
[string]
可选
输入参考图像的URL数组。
URL 需为公网可访问地址，支持 HTTP 或 HTTPS 协议。如需获取本地文件的公网URL，请参见上传文件获取临时URL 。
当前仅支持传入 1 张 参考图像 ，该图像可作为主体或背景使用，用于替换输入视频中的对应内容。
图像限制：
图像格式：JPG、JPEG、PNG、BMP、TIFF、WEBP。
图像分辨率：图像的宽度和高度范围为[360, 2000]，单位为像素。
图像大小：不超过10MB。
URL地址中不能包含中文字符。
使用建议：
若使用参考图像中的主体时，建议每张图像中仅包含一个主体。背景建议为纯色（如白色或单一颜色），以便更好地突出主体。
若使用参考图像的背景时，背景图像中不包含任何主体对象。
mask_image_url
string
可选
掩码图像的URL地址。URL 需为公网可访问地址，支持 HTTP 或 HTTPS 协议。您也可在此获取临时公网URL。
该参数用于指定视频的编辑区域。与 mask_video_url 参数二选一填写，推荐优先使用此参数 。
掩码图像的白色区域（像素值严格为 [255, 255, 255]）表示需要编辑的部分；黑色区域（像素值严格为 [0, 0, 0]）表示保留不变的区域。
图像限制：
图像格式：JPG、JPEG、PNG、BMP、TIFF、WEBP。
图像分辨率：和输入视频（video_url）分辨率严格相同。
图像大小：不超过10MB。
URL地址中不能包含中文字符。
mask_frame_id
string
可选
当 mask_image_url 不为空时，该参数生效，用于标识掩码目标出现在视频中的哪一帧，以“帧 ID”表示。
默认值为 1，单位为帧，表示视频的第一帧（首帧）。
取值范围为[1, max_frame_id]，其中max_frame_id=输入视频帧率*输入视频时长+1。
例如，输入视频（video_url）帧率为16FPS，表示每秒 16 帧，视频时长为5秒，因此输入视频的总帧数为16*5+1=81，即max_frame_id=81。
mask_video_url
string
可选
掩码视频的URL地址。URL 需为公网可访问地址，支持 HTTP 或 HTTPS 协议。您也可在此获取临时公网URL。
该参数用于指定视频的编辑区域。与mask_image_url参数，二选一填写。
掩码视频的视频格式、帧率、分辨率、长度需与输入视频（video_url）完全一致。
掩码视频的白色区域（像素值严格为 [255, 255, 255]）表示需要编辑的部分；黑色区域（像素值严格为 [0, 0, 0]）表示保留不变的区域。
parameters
object
必需
prompt_extend
boolean
可选
是否开启prompt智能改写。开启后使用大模型对输入prompt进行智能改写。对于较短的prompt生成效果提升明显，但会增加耗时。
true（默认值）：开启智能改写。
false：关闭智能改写。（推荐）
当文本描述与输入的视频内容不一致时，模型可能产生误解。建议手动关闭智能扩写，并在 prompt 中提供清晰、具体的画面描述，以提升生成一致性与准确性。
obj_or_bg
array
[string]
必需
size
string
可选
生成视频的分辨率（宽*高）。目前支持生成720P 视频，分辨率的取值为：
1280*720（默认值）：视频宽高比为16:9。其中，1280代表宽度，720代表高度。
720*1280：视频宽高比为9:16。
960*960：视频宽高比为1:1。
832*1088：视频宽高比为3:4。
1088*832：视频宽高比为4:3。
control_condition
string
可选
设置视频特征提取的方式。默认为""，表示不做任何提取。
posebodyface：提取输入视频的主体的脸部表情和肢体动作，适用于主体脸部在画面中占比较大、特征清晰可见的场景。
depth：提取输入视频的构图和运动轮廓。
mask_type
string
可选
当 mask_image_url 不为空时，该参数生效，用于指定编辑区域的行为方式。
tracking（默认值）：编辑区域将根据目标物体的运动轨迹动态跟随，适用于主体运动场景。
fixed ：编辑区域保持固定不变，不会随画面内容变化。
expand_ratio
string
可选
当 mask_type 为 tracking 时，该参数生效，表示对掩码区域进行向外扩展的比例。
取值范围为 [0.0, 1.0]，默认值为 0.05。推荐使用默认值。
取值越小，掩码区域越贴合目标物体；取值越大，掩码区域的扩展范围越广。
expand_mode
string
可选
当 mask_type 为 tracking 时，该参数生效，表示掩码区域的形状。
算法会根据选择的expand_mode，基于输入的掩码图像生成对应形状的掩码视频。支持的取值如下：
hull（默认值）：多边形模式，表示使用一个多边形包裹掩码目标。
bbox：边界框模式，表示使用一个矩形包裹掩码目标。
original：原始模式，表示尽量保持与原始掩码目标的形状一致。
duration
integer
可选
视频生成时长，单位为秒。当前参数值固定为5，且不支持修改。模型将始终生成5秒时长的视频。
seed
integer
可选
随机数种子，用于控制模型生成内容的随机性。seed参数取值范围是[0, 2147483647]。
如果不提供，则算法自动生成一个随机数作为种子。如果您希望生成内容保持相对稳定，请使用相同的seed参数值。
watermark
boolean
可选
是否添加水印标识，水印位于图片右下角，文案为“AI生成”。
false（默认值）：不添加水印。
true：添加水印。
示例
{
"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"
}
}
```

## 请求示例代码

### Shell

```bash
curl --location --request POST '/qwen/api/v1/services/aigc/video-generation/video-synthesis' \
--header 'X-DashScope-Async: enable' \
--header 'Authorization: Bearer {{YOUR_API_KEY}}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "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"
    }
}'
```

## 返回响应

### 🟢 200 成功

**内容类型**: `application/json`

#### 响应结构

```text
object
```

#### 示例

```json
{}
```