hao-ai-lab-FastVideo/docs/cookbook/wan.md

hide

hide
toc

Wan recipes

← All model families

Maintained family · Inference

Wan inference recipes

CUDA covers FastWan and Wan2.1/2.2 text and image recipes. Apple Silicon uses the released FastMetal 1.3B, 5B, and 14B MLX T2V paths. The speed flags below are switches on those same scripts, not extra recipes.

7 maintained recipes

Inference live Distillation planned Fine-tuning planned Training planned Evaluation planned Optimization planned Deployment planned

Builder Setup Troubleshooting Evidence

Compare Wan modes and options

Supported modes

FastMetal MLX is T2V in the checked-in examples. Image-to-video and TI2V stay on the CUDA recipes. Temporal --fast composes with either spatial path. --refine and --fast-spatial cannot run together. --refine wins if both are set. basic_mps.py is the older PyTorch MPS demo and is not a FastMetal recipe.

Mode	CUDA	MLX FastMetal
T2V	FastWan2.1 1.3B, Wan2.2 A14B	1.3B, 5B, and 14B
I2V	Wan2.1 14B 480P	Not in the released examples
TI2V	Wan2.2 TI2V 5B	FastMetal 5B is T2V in mlx_wan22_generate.py
Temporal --fast	No cookbook recipe	RIFE. Fewer frames, then interpolate to --num-frames
Spatial --fast-spatial	No cookbook recipe	Denoise and decode at half resolution, then upsample. No second denoise
Two-pass --refine	No cookbook recipe	Denoise at base resolution, upsample, re-noise, denoise again. Wins over --fast-spatial

Pick a recipe and runtime

Choose the result you want, then use a maintained CUDA or native MLX path.

<div class="cookbook-builder__layout">
  <div class="cookbook-controls">
    <div class="cookbook-selection-row">
      <div class="cookbook-selection-row__label">
        <strong>Recipe</strong>
        <span>Task and checkpoint</span>
      </div>
      <div class="cookbook-option-grid cookbook-option-grid--models" data-cookbook-model-options role="group" aria-label="Recipe">
        <button type="button" disabled>Loading Wan recipes...</button>
      </div>
    </div>

    <div class="cookbook-selection-row">
      <div class="cookbook-selection-row__label">
        <strong>Runtime</strong>
        <span>Maintained paths only</span>
      </div>
      <div class="cookbook-option-grid cookbook-option-grid--hardware" data-cookbook-hardware-options role="group" aria-label="Runtime">
        <button type="button" disabled>Loading runtimes...</button>
      </div>
    </div>

    <p class="cookbook-selection-description" data-cookbook-description>Loading recipe details...</p>
    <p class="cookbook-hardware-note">Exact device and memory details appear only when a recorded run supports them.</p>

    <div class="cookbook-hardware-state" data-cookbook-hardware-state role="status" aria-live="polite">
      Reading recipe evidence...
    </div>
  </div>

  <article class="cookbook-result">
    <div class="cookbook-result__header">
      <h3 data-cookbook-label>Loading...</h3>
      <div class="cookbook-result__badges">
        <span class="cookbook-badge">Maintained</span>
        <span class="cookbook-badge" data-cookbook-evidence>Source-backed</span>
        <span class="cookbook-badge cookbook-badge--neutral" data-cookbook-hardware-badge>Source config</span>
      </div>
    </div>

    <dl class="cookbook-result__facts">
      <div><dt>Model</dt><dd data-cookbook-model>Loading...</dd></div>
      <div><dt>Workload</dt><dd data-cookbook-task>Loading...</dd></div>
      <div><dt>Hardware</dt><dd data-cookbook-gpus>Loading...</dd></div>
      <div><dt>Expected output</dt><dd data-cookbook-artifact>Loading...</dd></div>
    </dl>

    <div class="cookbook-command">
      <div class="cookbook-command__bar">
        <span>Terminal</span>
      </div>
      <pre><code class="language-bash" data-cookbook-command>Loading...</code></pre>
    </div>

    <div class="cookbook-result__footer">
      <a data-cookbook-source href="../../inference/examples/basic/">Open example source</a>
      <a data-cookbook-model-link href="https://huggingface.co/Wan-AI">View model card</a>
    </div>
    <p class="cookbook-picker__status" role="status" aria-live="polite" data-cookbook-status></p>
  </article>
</div>

<noscript>
  <div class="cookbook-noscript">
    JavaScript is needed for the guided selector. You can still browse the
    <a href="../../inference/examples/examples_inference_index/">maintained inference examples</a>.
  </div>
</noscript>

Setup

The generated commands expect a local clone:

git clone https://github.com/hao-ai-lab/FastVideo.git
cd FastVideo

Use Configuration for supported Python and CLI settings, Optimizations for attention and memory tradeoffs, and the support matrix for the supported model and optimization surface.

Troubleshooting

• Out of memory on the A14B recipes: the checked-in sources already enable CPU offload; see Configuration for the offload surface before reducing resolution or frames.
• The FastWan2.1 recipe requires VIDEO_SPARSE_ATTN; confirm the environment variable in the command was set in the same shell.
• FastMetal MLX: install with the MLX install guide, then pick a FastMetal recipe in the builder. CUDA FastWan-QAD checkpoints are refused on the MLX runtime.
• FastMetal 5B uses mlx_wan22_generate.py. 1.3B and 14B use mlx_wan_prompt_to_video.py.
• Gated or missing checkpoints: run huggingface-cli login and confirm you accepted the model's license on Hugging Face.

Evidence status

Every recipe on this page maps to a checked-in FastVideo source. The FastMetal MLX releases include the recorded M4 Max system memory, documented unified-memory floor, and measured peak MLX memory. CUDA entries remain Source-backed where the examples record a GPU count but no exact GPU model or VRAM. Unlisted hardware is unknown, not unsupported.