VACE：一站式视频创作与编辑

(ICCV 2025)

姜泽音子^* · 韩震^* · 毛超杰^*† · 张景峰 · 潘宇林 · 刘宇
通义实验室 -

简介

VACE 是一款专为视频创作与编辑设计的一站式模型。它涵盖了多种任务，包括参考文本到视频生成（R2V）、视频到视频编辑（V2V）以及带掩码的视频到视频编辑（MV2V），用户可以自由组合这些任务。这一功能使用户能够探索多样化的可能性，并有效简化工作流程，提供诸如“移动任意内容”、“替换任意内容”、“参考任意内容”、“扩展任意内容”、“动画化任意内容”等多种能力。

🎉 最新消息

• 2025年10月17日：VACE-Benchmark 已更新，纳入了评估数据。VACE-Page 也展示了社区创意案例，为研究人员和社区成员提供了更好的项目洞察和跟踪。
• 2025年6月26日：VACE 被 ICCV 2025 接受。
• 2025年5月14日：🔥Wan2.1-VACE-1.3B 和 Wan2.1-VACE-14B 模型现已在 HuggingFace 和 ModelScope 上线！
• 2025年3月31日：🔥VACE-Wan2.1-1.3B-Preview 和 VACE-LTX-Video-0.9 模型现已在 HuggingFace 和 ModelScope 上线！
• 2025年3月31日：🔥发布了模型推理、预处理及 Gradio 演示的代码。
• 2025年3月11日：我们提出了 VACE，一个用于视频创作和编辑的一站式模型。

🪄 模型

模型	下载链接	视频尺寸	许可证
VACE-Wan2.1-1.3B-Preview	Huggingface 🤗 ModelScope 🤖	~ 81 x 480 x 832	Apache-2.0
VACE-LTX-Video-0.9	Huggingface 🤗 ModelScope 🤖	~ 97 x 512 x 768	RAIL-M
Wan2.1-VACE-1.3B	Huggingface 🤗 ModelScope 🤖	~ 81 x 480 x 832	Apache-2.0
Wan2.1-VACE-14B	Huggingface 🤗 ModelScope 🤖	~ 81 x 720 x 1280	Apache-2.0

• 输入支持任意分辨率，但为了获得最佳效果，视频尺寸应控制在特定范围内。
• 所有模型均继承原始模型的许可证。

⚙️ 安装

该代码库已在 Python 3.10.13、CUDA 12.4 和 PyTorch >= 2.5.1 的环境下测试通过。

模型推理环境搭建

您可以通过以下步骤搭建 VACE 模型推理环境：

git clone https://github.com/ali-vilab/VACE.git && cd VACE
pip install torch==2.5.1 torchvision==0.20.1 --index-url https://download.pytorch.org/whl/cu124  # 如果尚未安装 PyTorch。
pip install -r requirements.txt
pip install wan@git+https://github.com/Wan-Video/Wan2.1  # 如果您希望使用基于 Wan2.1 的 VACE。
pip install ltx-video@git+https://github.com/Lightricks/LTX-Video@ltx-video-0.9.1 sentencepiece --no-deps # 如果您希望使用基于 LTX-Video-0.9 的 VACE。这可能会与 Wan 冲突。

请将您选择的基础模型下载至 <repo-root>/models/ 目录下。

预处理工具环境搭建

如果您需要预处理工具，请执行：

pip install -r requirements/annotator.txt

请将 VACE-Annotators 下载至 <repo-root>/models/ 目录下。

本地目录结构建议

建议将 VACE-Benchmark 下载至 <repo-root>/benchmarks/ 目录下，作为 run_vace_xxx.sh 中的示例数据。

我们推荐的本地目录结构如下：

VACE
├── ...
├── benchmarks
│   └── VACE-Benchmark
│       └── assets
│           └── examples
│               ├── animate_anything
│               │   └── ...
│               └── ...
├── models
│   ├── VACE-Annotators
│   │   └── ...
│   ├── VACE-LTX-Video-0.9
│   │   └── ...
│   └── VACE-Wan2.1-1.3B-Preview
│       └── ...
└── ...

🚀 使用方法

在 VACE 中，用户可以输入 文本提示，并可选地提供 视频、掩码 和 图像，以进行视频生成或编辑。 有关 VACE 的详细使用说明，请参阅 用户指南。

推理 CIL

1) 端到端运行

若想简单运行 VACE 而无需深入任何实现细节，我们建议使用端到端流程。例如：

# 运行 V2V 深度估计
python vace/vace_pipeline.py --base wan --task depth --video assets/videos/test.mp4 --prompt 'xxx'

# 通过提供边界框运行 MV2V 图像修复
python vace/vace_pipeline.py --base wan --task inpainting --mode bbox --bbox 50,50,550,700 --video assets/videos/test.mp4 --prompt 'xxx'

该脚本将依次运行视频预处理和模型推理， 您需要指定所有必要的预处理参数（--task、--mode、--bbox、--video 等）以及推理参数（--prompt 等）。输出视频连同中间视频、掩码和图像默认会保存到 ./results/ 目录下。

💡注意： 请参考 run_vace_pipeline.sh 以获取不同任务流程的使用示例。

2) 预处理

为了更灵活地控制输入，在进行 VACE 模型推理之前，用户输入需要先被预处理为 src_video、src_mask 和 src_ref_images。 我们为每个 预处理器 分配了一个任务名称，因此只需调用 vace_preprocess.py，并指定任务名称和任务参数即可。例如：

# 处理视频深度估计
python vace/vace_preproccess.py --task depth --video assets/videos/test.mp4

# 通过提供边界框处理视频图像修复
python vace/vace_preproccess.py --task inpainting --mode bbox --bbox 50,50,550,700 --video assets/videos/test.mp4

输出文件默认会保存到 ./processed/ 目录下。

💡注意： 请参考 run_vace_pipeline.sh 中针对不同任务的预处理方法。此外，可参阅 vace/configs/ 获取所有预定义的任务及其所需参数。您也可以通过在 annotators 中实现自定义预处理器，并将其注册到 configs 中。

3) 模型推理

利用从 预处理 步骤中获得的输入数据，模型推理过程可以按如下方式进行：

# 对于 Wan2.1 单 GPU 推理 (1.3B-480P)
python vace/vace_wan_inference.py --ckpt_dir <模型路径> --src_video <源视频路径> --src_mask <源掩码路径> --src_ref_images <源参考图像路径> --prompt "xxx"

# 对于 Wan2.1 多 GPU 加速推理 (1.3B-480P)
pip install "xfuser>=0.4.1"
torchrun --nproc_per_node=8 vace/vace_wan_inference.py --dit_fsdp --t5_fsdp --ulysses_size 1 --ring_size 8 --ckpt_dir <模型路径> --src_video <源视频路径> --src_mask <源掩码路径> --src_ref_images <源参考图像路径> --prompt "xxx"

# 对于 Wan2.1 多 GPU 加速推理 (14B-720P)
torchrun --nproc_per_node=8 vace/vace_wan_inference.py --dit_fsdp --t5_fsdp --ulysses_size 8 --ring_size 1 --size 720p --model_name 'vace-14B' --ckpt_dir <模型路径> --src_video <源视频路径> --src_mask <源掩码路径> --src_ref_images <源参考图像路径> --prompt "xxx"

# 对于 LTX 推理，运行
python vace/vace_ltx_inference.py --ckpt_path <模型路径> --text_encoder_path <模型路径> --src_video <源视频路径> --src_mask <源掩码路径> --src_ref_images <源参考图像路径> --prompt "xxx"

输出视频连同中间视频、掩码和图像默认会保存到 ./results/ 目录下。

💡注意： (1) 请参考 vace/vace_wan_inference.py 和 vace/vace_ltx_inference.py 以了解推理参数。 (2) 对于 LTX-Video 和英语语言的 Wan2.1 用户，需要使用提示扩展才能充分发挥模型性能。请遵循 Wan2.1 的说明，并在运行推理时设置 --use_prompt_extend。 (3) 在编辑任务中进行提示扩展时，务必注意纯文本扩展后的内容。由于输入的视觉信息未知，扩展后的输出可能与待编辑视频不匹配，从而影响最终效果。

Gradio 推理

对于预处理器，运行以下命令：

python vace/gradios/vace_preprocess_demo.py

对于模型推理，运行：

# 对于 Wan2.1 的 Gradio 推理
python vace/gradios/vace_wan_demo.py

# 对于 LTX 的 Gradio 推理
python vace/gradios/vace_ltx_demo.py

致谢

我们衷心感谢以下优秀项目，包括 Scepter、Wan 和 LTX-Video。此外，我们还要向所有社区创作者致以最深切的谢意。正是他们积极的探索、实验和无限的创造力，为本项目带来了巨大的灵感，促使基于此涌现出更加完善的流程和令人惊叹的视频生成内容。这其中包括但不限于：Kijai 的工作流、对 ComfyUI 和 Diffusers 的原生代码支持、关键的模型量化支持、多样化的 LoRA 适配器生态，以及社区成员不断演进的创新工作流。

BibTeX

@inproceedings{vace,
    title = {VACE: 全功能视频创作与编辑},
    author = {Jiang, Zeyinzi 和 Han, Zhen 和 Mao, Chaojie 和 Zhang, Jingfeng 和 Pan, Yulin 和 Liu, Yu},
    booktitle = {IEEE/CVF 国际计算机视觉会议论文集},
    pages = {17191-17202},
    year = {2025}
}

VACE 快速上手指南

VACE 是一款全能型视频创作与编辑模型（ICCV 2025），支持参考图生成视频 (R2V)、视频转视频编辑 (V2V) 及掩码视频编辑 (MV2V)。本指南将帮助您快速在本地部署并运行该工具。

环境准备

在开始之前，请确保您的开发环境满足以下要求：

• 操作系统: Linux (推荐)
• Python: 3.10.13
• CUDA: 12.4
• PyTorch: >= 2.5.1
• 显存要求:
  • 运行 1.3B 模型：建议单卡显存 >= 16GB (多卡可加速)
  • 运行 14B 模型：建议多卡并行 (如 8x A100/A800)

安装步骤

1. 克隆代码库

git clone https://github.com/ali-vilab/VACE.git && cd VACE

2. 安装基础依赖

首先安装指定版本的 PyTorch（针对 CUDA 12.4），然后安装项目依赖：

pip install torch==2.5.1 torchvision==0.20.1 --index-url https://download.pytorch.org/whl/cu124
pip install -r requirements.txt

3. 安装特定模型后端

根据您想要使用的基座模型，选择以下其中一种进行安装：

• 方案 A：使用 Wan2.1 系列模型 (推荐)

  pip install wan@git+https://github.com/Wan-Video/Wan2.1
  

• 方案 B：使用 LTX-Video 系列模型

  注意：LTX-Video 依赖可能与 Wan2.1 冲突，请勿同时安装。

  pip install ltx-video@git+https://github.com/Lightricks/LTX-Video@ltx-video-0.9.1 sentencepiece --no-deps
  

4. 下载模型权重

请将下载的模型文件放置于 <repo-root>/models/ 目录下。您可以从 ModelScope (魔搭社区) 或 HuggingFace 下载。

推荐国内用户使用 ModelScope 下载：

• VACE-Wan2.1-1.3B-Preview: ModelScope 下载地址
• Wan2.1-VACE-14B: ModelScope 下载地址
• 预处理工具 (VACE-Annotators): ModelScope 下载地址 (如需使用预处理功能)

目录结构建议如下：

VACE
├── models
│   ├── VACE-Annotators
│   ├── VACE-Wan2.1-1.3B-Preview
│   └── ...
└── ...

基本使用

VACE 支持端到端一键运行，自动完成视频预处理和模型推理。以下以 Wan2.1 基座为例。

场景一：视频深度编辑 (Video-to-Video Depth)

将输入视频转换为深度图风格，并根据提示词生成新视频。

python vace/vace_pipeline.py --base wan --task depth --video assets/videos/test.mp4 --prompt 'a cyberpunk city with neon lights'

场景二：视频局部重绘 (Inpainting via Bounding Box)

通过指定边界框 (bbox) 对视频特定区域进行重绘。 格式：--bbox x_min,y_min,x_max,y_max

python vace/vace_pipeline.py --base wan --task inpainting --mode bbox --bbox 50,50,550,700 --video assets/videos/test.mp4 --prompt 'replace the object with a golden statue'

输出说明

运行完成后，生成的视频、中间掩码及参考图像默认保存在 ./results/ 目录中。

进阶：启动 Web UI (Gradio)

如果您更喜欢图形化界面操作，可以运行以下命令启动 Demo：

# 启动 Wan2.1 版本的 Web 界面
python vace/gradios/vace_wan_demo.py

启动后在浏览器访问显示的本地地址即可上传视频、绘制掩码并生成结果。

提示: 对于英文提示词，为了获得最佳效果，建议在推理命令中添加 --use_prompt_extend 参数以启用提示词扩展功能（需遵循 Wan2.1 相关配置）。