license: apache-2.0 datasets:

• ali-vilab/VACE-Benchmark language:
• en
• zh base_model:
• Wan-AI/Wan2.1-T2V-1.3B tags:
• 视频生成
• 视频到视频编辑
• 参考到视频

pipeline_tag: 图像到视频

VACE：一体化视频创作与编辑

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

简介

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

🎉 新闻

• [x] 2025年3月31日：🔥VACE-Wan2.1-1.3B-Preview和VACE-LTX-Video-0.9模型现已在HuggingFace和ModelScope上线！
• [x] 2025年3月31日：🔥发布模型推理、预处理和gradio演示的代码。
• [x] 2025年3月11日：我们提出了VACE，一款一体化视频创作与编辑模型。

🪄 模型

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

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

⚙️ 安装

代码库已在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中，用户可以输入文本提示和可选的视频、掩码和图像进行视频生成或编辑。 详细使用说明请参阅用户指南。

推理命令行

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

默认情况下，输出将保存到./proccessed/目录下。

💡注意： 请参考run_vace_pipeline.sh了解不同任务的预处理方法。 此外，请参考vace/configs/了解所有预定义任务和必要参数。 您还可以通过实现annotators并在configs中注册来自定义预处理器。

3) 模型推理

使用从预处理获得的输入数据，可以按以下方式执行模型推理过程：

# 对于Wan2.1单GPU推理
python vace/vace_wan_inference.py --ckpt_dir <path-to-model> --src_video <path-to-src-video> --src_mask <path-to-src-mask> --src_ref_images <paths-to-src-ref-images> --prompt "xxx"

# 对于Wan2.1多GPU加速推理
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 <path-to-model> --src_video <path-to-src-video> --src_mask <path-to-src-mask> --src_ref_images <paths-to-src-ref-images> --prompt "xxx"

# 对于LTX推理，运行
python vace/vace_ltx_inference.py --ckpt_path <path-to-model> --text_encoder_path <path-to-model> --src_video <path-to-src-video> --src_mask <path-to-src-mask> --src_ref_images <paths-to-src-ref-images> --prompt "xxx"

默认情况下，输出视频及中间视频、掩码和图像将保存到./results/目录下。

💡注意： (1) 请参考vace/vace_wan_inference.py和[vace/vace_ltx_inference.py](https://github.com