### Install Wan2.2 with Poetry

Source: https://github.com/wan-video/wan2.2/blob/main/INSTALL.md

Install all project dependencies using Poetry.

```bash
poetry install
```

--------------------------------

### Install Wan2.2 Dependencies

Source: https://context7.com/wan-video/wan2.2/llms.txt

Clone the repository and install core dependencies. Optional dependencies for Speech-to-Video and character animation can also be installed.

```bash
git clone https://github.com/Wan-Video/Wan2.2.git
cd Wan2.2

pip install -r requirements.txt

pip install -r requirements_s2v.txt

pip install -r requirements_animate.txt

pip install -e .
```

--------------------------------

### Install Wan2.2 with pip

Source: https://github.com/wan-video/wan2.2/blob/main/INSTALL.md

Use pip to install the project and its development dependencies.

```bash
pip install .
```

```bash
pip install .[dev]  # Installe aussi les outils de dev
```

--------------------------------

### Install flash-attn from Git

Source: https://github.com/wan-video/wan2.2/blob/main/INSTALL.md

Install flash-attn directly from its GitHub repository as an alternative.

```bash
poetry run pip install git+https://github.com/Dao-AILab/flash-attention.git
```

--------------------------------

### Install Dependencies for Wan2.2

Source: https://github.com/wan-video/wan2.2/blob/main/README.md

Install the required Python packages for Wan2.2. Ensure torch is at least version 2.4.0. If flash_attn installation fails, try installing it last.

```sh
# Ensure torch >= 2.4.0
# If the installation of `flash_attn` fails, try installing the other packages first and install `flash_attn` last
pip install -r requirements.txt
```

```sh
# If you want to use CosyVoice to synthesize speech for Speech-to-Video Generation, please install requirements_s2v.txt additionally
pip install -r requirements_s2v.txt
```

--------------------------------

### Initialize and Generate Video with WanTI2V (Text-to-Video)

Source: https://context7.com/wan-video/wan2.2/llms.txt

Initializes the unified WanTI2V 5B model, which supports both text-to-video and image-to-video. This example demonstrates text-to-video mode (img=None) on consumer-grade GPUs (24 GB VRAM), requiring T5 to be on CPU and enabling dtype conversion.

```python
import wan
from wan.configs import WAN_CONFIGS, SIZE_CONFIGS, MAX_AREA_CONFIGS
from wan.utils.utils import save_video
from PIL import Image

cfg = WAN_CONFIGS['ti2v-5B']

pipe = wan.WanTI2V(
    config=cfg,
    checkpoint_dir='./Wan2.2-TI2V-5B',
    device_id=0,
    rank=0,
    t5_cpu=True,              # required on 24 GB cards
    convert_model_dtype=True,
)

# --- Text-to-Video mode (img=None) ---
video_t2v = pipe.generate(
    input_prompt="Two anthropomorphic cats in boxing gear fight on a stage.",
    img=None,
    size=SIZE_CONFIGS['1280*704'],   # 720P for TI2V is 1280×704 or 704×1280
    frame_num=121,
    shift=5.0,
    sampling_steps=50,
    guide_scale=5.0,
    seed=42,
    offload_model=True,
)
save_video(video_t2v[None], 'output_ti2v_t2v.mp4', fps=24, nrow=1,
           normalize=True, value_range=(-1, 1))
```

--------------------------------

### Initialize and Generate Video with WanI2V (Image-to-Video)

Source: https://context7.com/wan-video/wan2.2/llms.txt

Initializes the WanI2V pipeline for animating a reference image guided by a text prompt. It preserves the input image's aspect ratio and auto-scales it within a max_area budget. The VAE encodes the reference image, and generation uses a masked conditioning strategy.

```python
import wan
from wan.configs import WAN_CONFIGS, MAX_AREA_CONFIGS
from wan.utils.utils import save_video
from PIL import Image

cfg = WAN_CONFIGS['i2v-A14B']

pipe = wan.WanI2V(
    config=cfg,
    checkpoint_dir='./Wan2.2-I2V-A14B',
    device_id=0,
    rank=0,
    convert_model_dtype=True,
)

img = Image.open('examples/i2v_input.JPG').convert('RGB')

video = pipe.generate(
    input_prompt="Summer beach vacation style, a white cat wearing sunglasses sits on a surfboard.",
    img=img,
    max_area=MAX_AREA_CONFIGS['1280*720'],  # 921600 pixels max; aspect ratio preserved
    frame_num=81,
    shift=5.0,          # for 480P videos, use shift=3.0
    sample_solver='unipc',
    sampling_steps=40,
    guide_scale=5.0,
    seed=42,
    offload_model=True,
)
# video shape: torch.Tensor (C=3, N=81, H=*, W=*) — dimensions match input aspect ratio

save_video(video[None], save_file='output_i2v.mp4', fps=16, nrow=1,
           normalize=True, value_range=(-1, 1))
print("Saved output_i2v.mp4")
```

--------------------------------

### Run Wan Animation Generation (CLI)

Source: https://context7.com/wan-video/wan2.2/llms.txt

Execute the animation generation process via the command line. Supports single-GPU or multi-GPU setups with options for replacement mode and relighting LoRA.

```bash
# Animation mode — single GPU
python generate.py \
    --task animate-14B \
    --ckpt_dir ./Wan2.2-Animate-14B \
    --src_root_path ./examples/wan_animate/animate/process_results \
    --refert_num 1

# Replacement mode — multi-GPU with relighting LoRA
python -m torch.distributed.run --nnodes 1 --nproc_per_node 8 generate.py \
    --task animate-14B \
    --ckpt_dir ./Wan2.2-Animate-14B \
    --src_root_path ./examples/wan_animate/replace/process_results \
    --refert_num 1 \
    --replace_flag \
    --use_relighting_lora \
    --dit_fsdp --t5_fsdp --ulysses_size 8
```

--------------------------------

### Run Animation with Single-GPU (CLI)

Source: https://github.com/wan-video/wan2.2/blob/main/README.md

Execute video animation using the command line for a single-GPU setup. Specify the task, checkpoint directory, and source path.

```bash
python generate.py --task animate-14B --ckpt_dir ./Wan2.2-Animate-14B/ --src_root_path ./examples/wan_animate/replace/process_results/ --refert_num 1 --replace_flag --use_relighting_lora 
```

--------------------------------

### Download Wan2.2 Models

Source: https://context7.com/wan-video/wan2.2/llms.txt

Download the required models for different generation tasks using huggingface-cli or ModelScope. Ensure you have the respective libraries installed.

```bash
pip install "huggingface_hub[cli]"
huggingface-cli download Wan-AI/Wan2.2-T2V-A14B   --local-dir ./Wan2.2-T2V-A14B
huggingface-cli download Wan-AI/Wan2.2-I2V-A14B   --local-dir ./Wan2.2-I2V-A14B
huggingface-cli download Wan-AI/Wan2.2-TI2V-5B    --local-dir ./Wan2.2-TI2V-5B
huggingface-cli download Wan-AI/Wan2.2-S2V-14B    --local-dir ./Wan2.2-S2V-14B
huggingface-cli download Wan-AI/Wan2.2-Animate-14B --local-dir ./Wan2.2-Animate-14B
```

```bash
pip install modelscope
modelscope download Wan-AI/Wan2.2-T2V-A14B --local_dir ./Wan2.2-T2V-A14B
```

--------------------------------

### Extend Prompts with Dashscope API

Source: https://github.com/wan-video/wan2.2/blob/main/README.md

Use this method to leverage the Dashscope API for prompt extension. Ensure you have a Dashscope API key configured as an environment variable. This example uses the 'qwen-plus' model for text-to-video tasks.

```sh
DASH_API_KEY=your_key torchrun --nproc_per_node=8 generate.py  --task t2v-A14B --size 1280*720 --ckpt_dir ./Wan2.2-T2V-A14B --dit_fsdp --t5_fsdp --ulysses_size 8 --prompt "Two anthropomorphic cats in comfy boxing gear and bright gloves fight intensely on a spotlighted stage" --use_prompt_extend --prompt_extend_method 'dashscope' --prompt_extend_target_lang 'zh'
```

--------------------------------

### Run Wan-Animate (Multi-GPU FSDP + DeepSpeed Ulysses)

Source: https://github.com/wan-video/wan2.2/blob/main/README.md

Performs multi-GPU inference for Wan-Animate using FSDP and DeepSpeed Ulysses. This command is for distributed training setups.

```bash
python -m torch.distributed.run --nnodes 1 --nproc_per_node 8 generate.py --task animate-14B --ckpt_dir ./Wan2.2-Animate-14B/ --src_root_path ./examples/wan_animate/animate/process_results/ --refert_num 1 --dit_fsdp --t5_fsdp --ulysses_size 8
```

--------------------------------

### Run Multi-GPU Inference (TI2V)

Source: https://github.com/wan-video/wan2.2/blob/main/README.md

Utilize this command for multi-GPU inference with FSDP and DeepSpeed Ulysses for the Wan2.2-TI2V-5B model. This setup is suitable for large-scale generation tasks.

```sh
torchrun --nproc_per_node=8 generate.py --task ti2v-5B --size 1280*704 --ckpt_dir ./Wan2.2-TI2V-5B --dit_fsdp --t5_fsdp --ulysses_size 8 --image examples/i2v_input.JPG --prompt "Summer beach vacation style, a white cat wearing sunglasses sits on a surfboard. The fluffy-furred feline gazes directly at the camera with a relaxed expression. Blurred beach scenery forms the background featuring crystal-clear waters, distant green hills, and a blue sky dotted with white clouds. The cat assumes a naturally relaxed posture, as if savoring the sea breeze and warm sunlight. A close-up shot highlights the feline's intricate details and the refreshing atmosphere of the seaside."
```

--------------------------------

### Multi-GPU Image-to-Video Inference with FSDP + DeepSpeed Ulysses

Source: https://github.com/wan-video/wan2.2/blob/main/README.md

Perform Image-to-Video generation using multiple GPUs with FSDP and DeepSpeed Ulysses. This setup is suitable for distributed inference.

```sh
torchrun --nproc_per_node=8 generate.py --task i2v-A14B --size 1280*720 --ckpt_dir ./Wan2.2-I2V-A14B --image examples/i2v_input.JPG --dit_fsdp --t5_fsdp --ulysses_size 8 --prompt "Summer beach vacation style, a white cat wearing sunglasses sits on a surfboard. The fluffy-furred feline gazes directly at the camera with a relaxed expression. Blurred beach scenery forms the background featuring crystal-clear waters, distant green hills, and a blue sky dotted with white clouds. The cat assumes a naturally relaxed posture, as if savoring the sea breeze and warm sunlight. A close-up shot highlights the feline's intricate details and the refreshing atmosphere of the seaside."
```

--------------------------------

### CLI for Pose + Audio Driven Speech-to-Video

Source: https://context7.com/wan-video/wan2.2/llms.txt

Command-line interface for speech-to-video generation driven by both audio and a pose video. This enables precise control over character body motion. Requires FSDP for distributed training.

```bash
torchrun --nproc_per_node=8 generate.py \
    --task s2v-14B --size 1024*704 \
    --ckpt_dir ./Wan2.2-S2V-14B \
    --dit_fsdp --t5_fsdp --ulysses_size 8 \
    --prompt "a person is singing" \
    --image examples/pose.png \
    --audio examples/sing.MP3 \
    --pose_video examples/pose.mp4
```

--------------------------------

### Generate Video with WanI2V (CLI with Prompt Extension)

Source: https://context7.com/wan-video/wan2.2/llms.txt

Command-line interface for WanI2V generation on a single GPU, enabling prompt extension via DashScope. Requires setting DASH_API_KEY, specifying task, size, checkpoint directory, and enabling offload and dtype conversion.

```bash
DASH_API_KEY=your_key python generate.py \
    --task i2v-A14B \
    --size 1280*720 \
    --ckpt_dir ./Wan2.2-I2V-A14B \
    --offload_model True \
    --convert_model_dtype \
    --image examples/i2v_input.JPG \
    --prompt "" \
    --use_prompt_extend \
    --prompt_extend_method dashscope
```

--------------------------------

### CLI for Image-to-Video Generation (24 GB GPU)

Source: https://context7.com/wan-video/wan2.2/llms.txt

Command-line interface for image-to-video generation, optimized for single high-end GPUs. Use `--convert_model_dtype` and `--t5_cpu` for potential performance gains.

```bash
python generate.py \
    --task ti2v-5B \
    --size 1280*704 \
    --ckpt_dir ./Wan2.2-TI2V-5B \
    --offload_model True \
    --convert_model_dtype \
    --t5_cpu \
    --prompt "Two anthropomorphic cats fight on a spotlighted stage."
```

--------------------------------

### Extend Prompts Locally with Qwen (Python)

Source: https://context7.com/wan-video/wan2.2/llms.txt

Utilize `QwenPromptExpander` for on-device prompt expansion using a local Qwen model. Supports text-to-video and image-to-video tasks, with an option to use Qwen-VL for image+text input.

```python
from wan.utils.prompt_extend import DashScopePromptExpander, QwenPromptExpander
from PIL import Image
import os

# --- Local Qwen expander (no API key required) ---
expander_qwen = QwenPromptExpander(
    model_name='Qwen2.5_7B',   # predefined alias or HF model name or local path
    task='i2v-A14B',
    is_vl=True,                # True enables Qwen2.5-VL for image+text
    device=0,
)

img = Image.open('examples/i2v_input.JPG').convert('RGB')
result = expander_qwen(
    prompt="",          # empty prompt -> model generates description from image
    image=img,
    tar_lang="en",
)
if result.status:
    print("Extended prompt:", result.prompt)
# PromptOutput(status=True, prompt='...', seed=..., system_prompt='...', message='...')
```

--------------------------------

### Initialize WanT2V Pipeline

Source: https://context7.com/wan-video/wan2.2/llms.txt

Initialize the text-to-video pipeline by loading the configuration for the 't2v-A14B' model. This pipeline requires dual MoE expert models, a T5 text encoder, and a VAE decoder.

```python
import wan
from wan.configs import WAN_CONFIGS, SIZE_CONFIGS
from wan.utils.utils import save_video

cfg = WAN_CONFIGS['t2v-A14B']
```

--------------------------------

### Run Wan-Animate (Single-GPU)

Source: https://github.com/wan-video/wan2.2/blob/main/README.md

Runs Wan-Animate in animation mode using a single GPU. Requires specifying the task, checkpoint directory, and source root path.

```bash
python generate.py --task animate-14B --ckpt_dir ./Wan2.2-Animate-14B/ --src_root_path ./examples/wan_animate/animate/process_results/ --refert_num 1
```

--------------------------------

### Initialize and Generate Video with WanT2V (Single GPU)

Source: https://context7.com/wan-video/wan2.2/llms.txt

Initializes the WanT2V pipeline with CPU offload for T5 and converts model dtype to bfloat16 to save VRAM. Generates an 81-frame video with specified prompt, size, and sampling parameters. Offloads experts to CPU between steps.

```python
pipe = wan.WanT2V(
    config=cfg,
    checkpoint_dir='./Wan2.2-T2V-A14B',
    device_id=0,
    rank=0,
    t5_fsdp=False,
    dit_fsdp=False,
    use_sp=False,
    t5_cpu=False,               # set True to keep T5 on CPU (<24 GB)
    convert_model_dtype=True,   # convert weights to bfloat16 to save VRAM
)

# Generate 81-frame 720P video (4n+1 frames required)
video = pipe.generate(
    input_prompt="Two anthropomorphic cats in comfy boxing gear and bright gloves fight intensely on a spotlighted stage.",
    size=SIZE_CONFIGS['1280*720'],   # (W, H) = (1280, 720)
    frame_num=81,
    shift=12.0,                      # flow-matching schedule shift
    sample_solver='unipc',           # 'unipc' or 'dpm++'
    sampling_steps=40,
    guide_scale=(3.0, 4.0),          # (low-noise CFG, high-noise CFG)
    n_prompt="",                     # uses config default negative prompt if ""
    seed=42,
    offload_model=True,              # offload experts to CPU between steps
)
# video shape: torch.Tensor (C=3, N=81, H=720, W=1280), range [-1, 1]

# Save to .mp4
save_video(video[None], save_file='output_t2v.mp4', fps=16, nrow=1,
           normalize=True, value_range=(-1, 1))
print("Saved output_t2v.mp4")
```

--------------------------------

### Extend Prompts with DashScope API (Python)

Source: https://context7.com/wan-video/wan2.2/llms.txt

Use `DashScopePromptExpander` to enrich short prompts for video generation by calling Alibaba Cloud's DashScope API. Requires setting the `DASH_API_KEY` environment variable.

```python
from wan.utils.prompt_extend import DashScopePromptExpander, QwenPromptExpander
from PIL import Image
import os

# --- DashScope API expander ---
os.environ['DASH_API_KEY'] = 'your_dashscope_api_key'
# For international users:
# os.environ['DASH_API_URL'] = 'https://dashscope-intl.aliyuncs.com/api/v1'

expander_ds = DashScopePromptExpander(
    model_name=None,     # None -> 'qwen-plus' for text, 'qwen-vl-max' for image+text
    task='t2v-A14B',     # used to select the correct system prompt
    is_vl=False,         # True when passing an image for I2V tasks
    retry_times=4,
)

result = expander_ds(
    prompt="A cat surfing.",
    tar_lang="zh",       # target language: 'zh' or 'en'
    seed=42,
)
if result.status:
    print("Extended prompt:", result.prompt)
else:
    print("Failed:", result.message)
```

--------------------------------

### Generate Video with WanT2V (Multi-GPU CLI)

Source: https://context7.com/wan-video/wan2.2/llms.txt

Command-line interface for generating videos using WanT2V with multiple GPUs via torchrun and FSDP. Requires specifying task, size, checkpoint directory, and enabling FSDP for both DiT and T5.

```bash
torchrun --nproc_per_node=8 generate.py \
    --task t2v-A14B \
    --size 1280*720 \
    --ckpt_dir ./Wan2.2-T2V-A14B \
    --dit_fsdp --t5_fsdp \
    --ulysses_size 8 \
    --prompt "Two anthropomorphic cats in comfy boxing gear fight on a spotlighted stage."
```

--------------------------------

### Run Wan Animation Preprocessing (CLI)

Source: https://context7.com/wan-video/wan2.2/llms.txt

Use this command to preprocess video data for animation mode. Specify checkpoint, video, reference image, and save paths, along with resolution and iteration parameters.

```bash
python ./wan/modules/animate/preprocess/preprocess_data.py \
    --ckpt_path ./Wan2.2-Animate-14B/process_checkpoint \
    --video_path ./examples/wan_animate/replace/video.mp4 \
    --refer_path ./examples/wan_animate/replace/image.jpeg \
    --save_path ./examples/wan_animate/replace/process_results \
    --resolution_area 1280 720 \
    --replace_flag \
    --iterations 3 --k 7 --w_len 1 --h_len 1
```

--------------------------------

### Preprocess Data for Wan-Animate (Replacement Mode)

Source: https://github.com/wan-video/wan2.2/blob/main/README.md

Preprocesses input video and character image for Wan-Animate in replacement mode. Includes parameters for iterations, k, w_len, and h_len.

```bash
python ./wan/modules/animate/preprocess/preprocess_data.py \
    --ckpt_path ./Wan2.2-Animate-14B/process_checkpoint \
    --video_path ./examples/wan_animate/replace/video.mp4 \
    --refer_path ./examples/wan_animate/replace/image.jpeg \
    --save_path ./examples/wan_animate/replace/process_results \
    --resolution_area 1280 720 \
    --iterations 3 \
    --k 7 \
    --w_len 1 \
    --h_len 1 \
    --replace_flag
```

--------------------------------

### Run Image-to-Video Generation (TI2V)

Source: https://github.com/wan-video/wan2.2/blob/main/README.md

This command performs single-GPU Image-to-Video inference using the Wan2.2-TI2V-5B model. The `--image` parameter enables Image-to-Video generation. The `size` parameter defines the video resolution, and the aspect ratio follows the input image.

```sh
python generate.py --task ti2v-5B --size 1280*704 --ckpt_dir ./Wan2.2-TI2V-5B --offload_model True --convert_model_dtype --t5_cpu --image examples/i2v_input.JPG --prompt "Summer beach vacation style, a white cat wearing sunglasses sits on a surfboard. The fluffy-furred feline gazes directly at the camera with a relaxed expression. Blurred beach scenery forms the background featuring crystal-clear waters, distant green hills, and a blue sky dotted with white clouds. The cat assumes a naturally relaxed posture, as if savoring the sea breeze and warm sunlight. A close-up shot highlights the feline's intricate details and the refreshing atmosphere of the seaside."
```

--------------------------------

### Run Text-to-Video Generation (TI2V)

Source: https://github.com/wan-video/wan2.2/blob/main/README.md

Use this command for single-GPU Text-to-Video inference with the Wan2.2-TI2V-5B model. Requires a GPU with at least 24GB VRAM. Options like `--offload_model True`, `--convert_model_dtype`, and `--t5_cpu` can be removed on GPUs with 80GB VRAM for faster execution.

```sh
python generate.py --task ti2v-5B --size 1280*704 --ckpt_dir ./Wan2.2-TI2V-5B --offload_model True --convert_model_dtype --t5_cpu --prompt "Two anthropomorphic cats in comfy boxing gear and bright gloves fight intensely on a spotlighted stage"
```

--------------------------------

### Run Wan Animation Generation (Python API)

Source: https://context7.com/wan-video/wan2.2/llms.txt

Generate animations using the WanAnimate pipeline. Configure model, device, and generation parameters. Set `use_relighting_lora=True` for replacement mode lighting fixes.

```python
import wan
from wan.configs import WAN_CONFIGS
from wan.utils.utils import save_video

cfg = WAN_CONFIGS['animate-14B']

pipe = wan.WanAnimate(
    config=cfg,
    checkpoint_dir='./Wan2.2-Animate-14B',
    device_id=0,
    rank=0,
    convert_model_dtype=True,
    use_relighting_lora=False,  # set True for replacement mode lighting fix
)

# Animation mode — src_root_path must contain src_pose.mp4, src_face.mp4, src_ref.png
video = pipe.generate(
    src_root_path='./examples/wan_animate/animate/process_results',
    replace_flag=False,     # True for replacement mode
    clip_len=77,            # frames per clip (4n+1); default 77
    refert_num=1,           # temporal reference frames: 1 or 5
    shift=5.0,
    sample_solver='dpm++',
    sampling_steps=20,
    guide_scale=1.0,        # >1 only needed for expression control
    seed=42,
    offload_model=True,
)
# video shape: torch.Tensor (C=3, N=total_frames, H, W)

save_video(video[None], 'output_animate.mp4', fps=30, nrow=1,
           normalize=True, value_range=(-1, 1))
print("Saved output_animate.mp4")
```

--------------------------------

### Run Wan2.2 Model Generation

Source: https://github.com/wan-video/wan2.2/blob/main/INSTALL.md

Execute the model generation script with specified task, size, checkpoint directory, and prompt.

```bash
poetry run python generate.py --task t2v-A14B --size '1280*720' --ckpt_dir ./Wan2.2-T2V-A14B --prompt "Two anthropomorphic cats in comfy boxing gear and bright gloves fight intensely on a spotlighted stage."
```

--------------------------------

### Testing Wan2.2 Models with Bash Script

Source: https://context7.com/wan-video/wan2.2/llms.txt

Execute this bash script to run all test suites for T2V, I2V, and TI2V models. Specify the model root path and the number of GPUs to use.

```bash
# Run all tasks (multi-GPU)
bash tests/test.sh /path/to/model/root 8

# The script runs the following test suites:
# - t2v_A14B: 480P, 720P landscape, 720P portrait + prompt extension
# - i2v_A14B: 480P, 720P, DashScope prompt extension (if DASH_API_KEY is set)
# - ti2v_5B: T2V 720P, I2V 720P + prompt extension
```

--------------------------------

### Download Models using Hugging Face CLI

Source: https://github.com/wan-video/wan2.2/blob/main/README.md

Download pre-trained models using the huggingface-cli tool. Specify the model name and the local directory to save it.

```sh
pip install "huggingface_hub[cli]"
huggingface-cli download Wan-AI/Wan2.2-T2V-A14B --local-dir ./Wan2.2-T2V-A14B
```

--------------------------------

### Run Wan2.2 Model Tests

Source: https://github.com/wan-video/wan2.2/blob/main/tests/README.md

Execute test scripts for Wan2.2 models. Specify the local directory containing your models and the maximum number of GPUs to utilize.

```bash
bash ./tests/test.sh <local model dir> <gpu number>
```

--------------------------------

### Run Tests

Source: https://github.com/wan-video/wan2.2/blob/main/INSTALL.md

Execute the project's test suite using the provided shell script.

```bash
bash tests/test.sh
```

--------------------------------

### Replacement Mode via Diffusers Pipeline

Source: https://context7.com/wan-video/wan2.2/llms.txt

This snippet demonstrates video replacement by providing source image, pose video, face video, background video, and a mask video. Set 'mode' to 'replace'.

```python
background_video = load_video("/path/to/src_bg.mp4")
mask_video = load_video("/path/to/src_mask.mp4")

frames = pipe(
    image=image,
    pose_video=pose_video,
    face_video=face_video,
    background_video=background_video,
    mask_video=mask_video,
    prompt="People in the video are doing actions.",
    mode="replace",
    segment_frame_length=77,
    prev_segment_conditioning_frames=1,
    guidance_scale=1.0,
    num_inference_steps=20,
    generator=torch.Generator(device=device).manual_seed(42),
).frames[0]
export_to_video(frames, "diffusers_replace.mp4", fps=30)
```

--------------------------------

### Preprocess Data for Wan-Animate (Animation Mode)

Source: https://github.com/wan-video/wan2.2/blob/main/README.md

Preprocesses input video and character image for Wan-Animate in animation mode. Requires specifying paths, resolution, and enabling retargeting and flux.

```bash
python ./wan/modules/animate/preprocess/preprocess_data.py \
    --ckpt_path ./Wan2.2-Animate-14B/process_checkpoint \
    --video_path ./examples/wan_animate/animate/video.mp4 \
    --refer_path ./examples/wan_animate/animate/image.jpeg \
    --save_path ./examples/wan_animate/animate/process_results \
    --resolution_area 1280 720 \
    --retarget_flag \
    --use_flux
```

--------------------------------

### Generate.py CLI Reference

Source: https://context7.com/wan-video/wan2.2/llms.txt

Provides a unified command-line interface for various generation tasks. Key arguments cover task selection, size, checkpoint directory, prompts, and advanced options like FSDP and sequence parallelism.

```bash
# General structure
python generate.py \
    --task        {t2v-A14B, i2v-A14B, ti2v-5B, animate-14B, s2v-14B} \
    --size        {720*1280, 1280*720, 480*832, 832*480, 704*1280, 1280*704, 1024*704, 704*1024} \
    --frame_num   INT          # 4n+1 (e.g. 81, 121); default from config \
    --ckpt_dir    PATH         # local checkpoint directory \
    --prompt      "TEXT"       # user prompt \
    --image       PATH         # input image (i2v, ti2v, s2v tasks) \
    --base_seed   INT          # -1 = random \
    --sample_steps INT         # diffusion steps; default from config \
    --sample_shift FLOAT       # flow shift; default from config \
    --sample_guide_scale FLOAT # CFG scale \
    --sample_solver {unipc, dpm++} \
    --offload_model {True, False} \
    --convert_model_dtype      # cast weights to bfloat16 (saves VRAM) \
    --t5_cpu                   # keep T5 on CPU (saves ~8 GB VRAM) \
    --save_file   PATH.mp4     # output path; auto-named if omitted \
    \
    # Prompt extension
    --use_prompt_extend \
    --prompt_extend_method {dashscope, local_qwen} \
    --prompt_extend_model  {model name or path} \
    --prompt_extend_target_lang {zh, en} \
    \
    # Multi-GPU (with torchrun)
    --dit_fsdp                 # shard DiT via FSDP \
    --t5_fsdp                  # shard T5 via FSDP \
    --ulysses_size INT         # sequence parallelism degree (== world_size) \
    \
    # S2V-specific
    --audio       PATH         # .wav or .mp3 audio file \
    --enable_tts               # synthesize audio via CosyVoice2 \
    --tts_prompt_audio PATH    # 5–15 s reference voice clip (>= 16 kHz) \
    --tts_prompt_text "TEXT"   # transcript of tts_prompt_audio \
    --tts_text "TEXT"          # text to synthesize \
    --pose_video  PATH         # DWPose sequence video for body control \
    --num_clip    INT          # number of video clips (None = auto from audio) \
    --infer_frames INT         # frames per clip; 48 or 80 (multiple of 4) \
    --start_from_ref           # use ref image as first frame \
    \
    # Animate-specific
    --src_root_path PATH       # preprocessed data directory \
    --refert_num  {1, 5}       # temporal reference frames \
    --replace_flag             # replacement mode (vs animation mode) \
    --use_relighting_lora      # apply relighting LoRA for replacement
```

--------------------------------

### Run Replacement Pipeline

Source: https://github.com/wan-video/wan2.2/blob/main/README.md

Use this Python code for video replacement tasks. This mode requires additional inputs such as background, mask videos, and specific flags for replacement.

```python
# create pipeline as in the Animation code ☝️

# Replacement
image = load_image("/path/to/replace/reference/image/src_ref.png")
pose_video = load_video("/path/to/replace/pose/video/src_pose.mp4")
face_video = load_video("/path/to/replace/face/video/src_face.mp4")
background_video = load_video("/path/to/replace/background/video/src_bg.mp4")
mask_video = load_video("/path/to/replace/mask/video/src_mask.mp4")

replace_video = pipe(
    image=image,
    pose_video=pose_video,
    face_video=face_video,
    background_video=background_video,
    mask_video=mask_video,
    prompt=prompt,
    mode="replace",
    segment_frame_length=77,  # clip_len in original code
    prev_segment_conditioning_frames=1,  # refert_num in original code
    guidance_scale=1.0,
    num_inference_steps=20,
    generator=torch.Generator(device=device).manual_seed(seed),
).frames[0]
export_to_video(replace_video, "diffusers_replace.mp4", fps=30)
```

--------------------------------

### Pose + Audio Driven Generation

Source: https://github.com/wan-video/wan2.2/blob/main/README.md

Generates video driven by pose and audio input, with an optional text prompt and reference image. The `--pose_video` parameter enables pose-driven generation.

```sh
torchrun --nproc_per_node=8 generate.py --task s2v-14B --size 1024*704 --ckpt_dir ./Wan2.2-S2V-14B/ --dit_fsdp --t5_fsdp --ulysses_size 8 --prompt "a person is singing" --image "examples/pose.png" --audio "examples/sing.MP3" --pose_video "./examples/pose.mp4" 
```

--------------------------------

### Run Speech-to-Video Generation (S2V)

Source: https://github.com/wan-video/wan2.2/blob/main/README.md

This command enables single-GPU Speech-to-Video inference with the Wan2.2-S2V-14B model. It supports both 480P and 720P resolutions. The generated video length automatically adjusts to the input audio length if `--num_clip` is not specified.

```sh
python generate.py  --task s2v-14B --size 1024*704 --ckpt_dir ./Wan2.2-S2V-14B/ --offload_model True --convert_model_dtype --prompt "Summer beach vacation style, a white cat wearing sunglasses sits on a surfboard."  --image "examples/i2v_input.JPG" --audio "examples/talk.wav"
```

--------------------------------

### Inspect Wan2.2 Configuration System

Source: https://context7.com/wan-video/wan2.2/llms.txt

Access and inspect configuration objects for different tasks, supported sizes, and lookup tables. This helps in understanding model parameters and generation constraints.

```python
from wan.configs import (
    WAN_CONFIGS,      # dict mapping task name -> config EasyDict
    SIZE_CONFIGS,     # dict mapping "WxH" string -> (W, H) tuple
    MAX_AREA_CONFIGS, # dict mapping "WxH" string -> pixel area int
    SUPPORTED_SIZES,  # dict mapping task name -> tuple of valid size strings
)

print(list(WAN_CONFIGS.keys()))

print(SUPPORTED_SIZES['t2v-A14B'])

cfg = WAN_CONFIGS['t2v-A14B']
print(cfg.sample_steps)
print(cfg.sample_shift)
print(cfg.boundary)
print(cfg.sample_guide_scale)
print(cfg.num_train_timesteps)
print(cfg.frame_num)
print(cfg.sample_fps)
print(cfg.param_dtype)
print(cfg.text_len)

print(SIZE_CONFIGS['1280*720'])
print(MAX_AREA_CONFIGS['1280*720'])
```

--------------------------------

### CLI for Speech-to-Video with TTS

Source: https://context7.com/wan-video/wan2.2/llms.txt

Command-line interface for speech-to-video generation incorporating TTS using CosyVoice2 for zero-shot voice cloning. Requires specifying TTS prompts for voice matching.

```bash
python generate.py \
    --task s2v-14B \
    --size 1024*704 \
    --ckpt_dir ./Wan2.2-S2V-14B \
    --offload_model True \
    --convert_model_dtype \
    --image examples/i2v_input.JPG \
    --enable_tts \
    --tts_prompt_audio examples/zero_shot_prompt.wav \
    --tts_prompt_text "希望你以后能够做的比我还好呦。" \
    --tts_text "收到好友从远方寄来的生日礼物，那份意外的惊喜与深深的祝福让我心中充满了甜蜜的快乐。"
```

--------------------------------

### Image-to-Video Generation without Prompt using Prompt Extension

Source: https://github.com/wan-video/wan2.2/blob/main/README.md

Generate videos solely from an input image without providing an explicit prompt. Utilizes prompt extension methods like 'dashscope' to derive a prompt from the image.

```sh
DASH_API_KEY=your_key torchrun --nproc_per_node=8 generate.py --task i2v-A14B --size 1280*720 --ckpt_dir ./Wan2.2-I2V-A14B --prompt '' --image examples/i2v_input.JPG --dit_fsdp --t5_fsdp --ulysses_size 8 --use_prompt_extend --prompt_extend_method 'dashscope'
```

--------------------------------

### Run Animation with Multi-GPU (CLI)

Source: https://github.com/wan-video/wan2.2/blob/main/README.md

Perform video animation using multiple GPUs with FSDP and DeepSpeed Ulysses. This command requires specifying the number of nodes and processes per node, along with distributed training flags.

```bash
python -m torch.distributed.run --nnodes 1 --nproc_per_node 8 generate.py --task animate-14B --ckpt_dir ./Wan2.2-Animate-14B/ --src_root_path ./examples/wan_animate/replace/process_results/src_pose.mp4  --refert_num 1 --replace_flag --use_relighting_lora --dit_fsdp --t5_fsdp --ulysses_size 8
```

--------------------------------

### Extend Prompts with Local Qwen Model

Source: https://github.com/wan-video/wan2.2/blob/main/README.md

Utilize a local Qwen model for prompt extension. This method allows flexibility in choosing models based on GPU memory. Specify the model path or Hugging Face identifier using `--prompt_extend_model`.

```sh
torchrun --nproc_per_node=8 generate.py  --task t2v-A14B --size 1280*720 --ckpt_dir ./Wan2.2-T2V-A14B --dit_fsdp --t5_fsdp --ulysses_size 8 --prompt "Two anthropomorphic cats in comfy boxing gear and bright gloves fight intensely on a spotlighted stage" --use_prompt_extend --prompt_extend_method 'local_qwen' --prompt_extend_target_lang 'zh'
```

--------------------------------

### Image-to-Video Generation

Source: https://context7.com/wan-video/wan2.2/llms.txt

Generates video from a reference image and a text prompt. Ensure the image is in RGB format. The `offload_model` parameter can be used for memory management.

```python
img = Image.open('examples/i2v_input.JPG').convert('RGB')
video_i2v = pipe.generate(
    input_prompt="The cat gently waves its paw at the camera.",
    img=img,
    max_area=MAX_AREA_CONFIGS['1280*704'],
    frame_num=121,
    shift=5.0,
    sampling_steps=40,
    guide_scale=5.0,
    seed=42,
    offload_model=True,
)
save_video(video_i2v[None], 'output_ti2v_i2v.mp4', fps=24, nrow=1,
           normalize=True, value_range=(-1, 1))
```

--------------------------------

### Download Models using ModelScope CLI

Source: https://github.com/wan-video/wan2.2/blob/main/README.md

Download pre-trained models using the modelscope CLI tool. Specify the model name and the local directory to save it.

```sh
pip install modelscope
modelscope download Wan-AI/Wan2.2-T2V-A14B --local_dir ./Wan2.2-T2V-A14B
```

--------------------------------

### Clone Wan2.2 Repository

Source: https://github.com/wan-video/wan2.2/blob/main/README.md

Clone the Wan2.2 repository from GitHub to your local machine.

```sh
git clone https://github.com/Wan-Video/Wan2.2.git
cd Wan2.2
```

--------------------------------

### Troubleshoot flash-attn with No-Build-Isolation

Source: https://github.com/wan-video/wan2.2/blob/main/INSTALL.md

Fix PEP 517 build issues for flash-attn by disabling build isolation and reinstalling.

```bash
poetry run pip install --upgrade pip setuptools wheel
```

```bash
poetry run pip install flash-attn --no-build-isolation
```

```bash
poetry install
```

--------------------------------

### generate.py CLI

Source: https://context7.com/wan-video/wan2.2/llms.txt

The generate.py script provides a single unified CLI for all five tasks. Key arguments are shown below; all parameters map directly to the Python API.

```APIDOC
## CLI Reference — `generate.py`

The `generate.py` script provides a single unified CLI for all five tasks. Key arguments are shown below; all parameters map directly to the Python API.

```bash
# General structure
python generate.py \
    --task        {t2v-A14B, i2v-A14B, ti2v-5B, animate-14B, s2v-14B} \
    --size        {720*1280, 1280*720, 480*832, 832*480, 704*1280, 1280*704, 1024*704, 704*1024} \
    --frame_num   INT          # 4n+1 (e.g. 81, 121); default from config \
    --ckpt_dir    PATH         # local checkpoint directory \
    --prompt      "TEXT"       # user prompt \
    --image       PATH         # input image (i2v, ti2v, s2v tasks) \
    --base_seed   INT          # -1 = random \
    --sample_steps INT         # diffusion steps; default from config \
    --sample_shift FLOAT       # flow shift; default from config \
    --sample_guide_scale FLOAT # CFG scale \
    --sample_solver {unipc, dpm++} \
    --offload_model {True, False} \
    --convert_model_dtype      # cast weights to bfloat16 (saves VRAM) \
    --t5_cpu                   # keep T5 on CPU (saves ~8 GB VRAM) \
    --save_file   PATH.mp4     # output path; auto-named if omitted \
    \
    # Prompt extension
    --use_prompt_extend \
    --prompt_extend_method {dashscope, local_qwen} \
    --prompt_extend_model  {model name or path} \
    --prompt_extend_target_lang {zh, en} \
    \
    # Multi-GPU (with torchrun)
    --dit_fsdp                 # shard DiT via FSDP \
    --t5_fsdp                  # shard T5 via FSDP \
    --ulysses_size INT         # sequence parallelism degree (== world_size) \
    \
    # S2V-specific
    --audio       PATH         # .wav or .mp3 audio file \
    --enable_tts               # synthesize audio via CosyVoice2 \
    --tts_prompt_audio PATH    # 5–15 s reference voice clip (>= 16 kHz) \
    --tts_prompt_text "TEXT"   # transcript of tts_prompt_audio \
    --tts_text "TEXT"          # text to synthesize \
    --pose_video  PATH         # DWPose sequence video for body control \
    --num_clip    INT          # number of video clips (None = auto from audio) \
    --infer_frames INT         # frames per clip; 48 or 80 (multiple of 4) \
    --start_from_ref           # use ref image as first frame \
    \
    # Animate-specific
    --src_root_path PATH       # preprocessed data directory \
    --refert_num  {1, 5}       # temporal reference frames \
    --replace_flag             # replacement mode (vs animation mode) \
    --use_relighting_lora      # apply relighting LoRA for replacement
```
```

--------------------------------

### Wan-Animate Diffusers Pipeline

Source: https://github.com/wan-video/wan2.2/blob/main/README.md

Loads and uses the WanAnimatePipeline from the diffusers library for animation tasks. Requires specifying the model ID and device.

```python
from diffusers import WanAnimatePipeline
from diffusers.utils import export_to_video, load_image, load_video

device = "cuda:0"
dtype = torch.bfloat16
model_id = "Wan-AI/Wan2.2-Animate-14B-Diffusers"
pipe = WanAnimatePipeline.from_pretrained(model_id, torch_dtype=dtype)
pipe.to(device)

seed = 42
prompt = "People in the video are doing actions."


```

--------------------------------

### Single-GPU Text-to-Video Inference

Source: https://github.com/wan-video/wan2.2/blob/main/README.md

Run text-to-video generation on a single GPU using the Wan2.2-T2V-A14B model. This command requires at least 80GB of VRAM. Use options like --offload_model True, --convert_model_dtype, and --t5_cpu to reduce memory usage if OOM errors occur.

```sh
python generate.py  --task t2v-A14B --size 1280*720 --ckpt_dir ./Wan2.2-T2V-A14B --offload_model True --convert_model_dtype --prompt "Two anthropomorphic cats in comfy boxing gear and bright gloves fight intensely on a spotlighted stage."
```

--------------------------------

### Multi-GPU Text-to-Video Inference with FSDP + DeepSpeed Ulysses

Source: https://github.com/wan-video/wan2.2/blob/main/README.md

Accelerate text-to-video inference using PyTorch FSDP and DeepSpeed Ulysses across multiple GPUs. Specify the number of processes per node and other relevant flags.

```sh
torchrun --nproc_per_node=8 generate.py --task t2v-A14B --size 1280*720 --ckpt_dir ./Wan2.2-T2V-A14B --dit_fsdp --t5_fsdp --ulysses_size 8 --prompt "Two anthropomorphic cats in comfy boxing gear and bright gloves fight intensely on a spotlighted stage."
```

--------------------------------

### Model Checkpoint Directory Structure

Source: https://github.com/wan-video/wan2.2/blob/main/wan/modules/animate/preprocess/UserGuider.md

Organize necessary models for preprocessing into the specified directory structure. This includes pose detection, mask extraction, and image editing models.

```text
    /path/to/your/ckpt_path/
    ├── det/
    │ └── yolov10m.onnx
    ├── pose2d/
    │ └── vitpose_h_wholebody.onnx
    ├── sam2/
    │ └── sam2_hiera_large.pt
    └── FLUX.1-Kontext-dev/
```

--------------------------------

### Load WanAnimatePipeline from HuggingFace

Source: https://context7.com/wan-video/wan2.2/llms.txt

Loads a WanAnimatePipeline from a HuggingFace model ID using the diffusers library. This pipeline can be moved to a CUDA device and uses bfloat16 precision for efficiency.

```python
import torch
from diffusers import WanAnimatePipeline
from diffusers.utils import export_to_video, load_image, load_video

device = "cuda:0"
dtype = torch.bfloat16
model_id = "Wan-AI/Wan2.2-Animate-14B-Diffusers"

pipe = WanAnimatePipeline.from_pretrained(model_id, torch_dtype=dtype)
pipe.to(device)

```