---

name: "hunyuanvideo-i2v" description: "Guides HunyuanVideo-I2V image-to-video inference, LoRA training, and latent-extraction workflows, including checkpoint setup, CUDA/flash-attn requirements, and the safe bundled checks for this repository." disable-model-invocation: true metadata: disco-role: operating license: NOASSERTION

HunyuanVideo-I2V

Use this skill for Tencent HunyuanVideo-I2V image-to-video workflows: single-GPU sampling, LoRA-based special-effects training, latent extraction for training data, checkpoint layout checks, and the repo-specific troubleshooting around CUDA, flash-attn, and DeepSpeed.

Start Here

1. Read references/repo-provenance.md if you need to confirm this skill matches the current checkout.
2. Read references/checkpoints.md before any real generation or training run.
3. Read references/model-overview.md for supported model/config choices and the resolution/length constraints.
4. Read references/troubleshooting.md when imports, CUDA, flash-attn, checkpoint, or data-layout checks fail.

Install and Smoke Check

The checkout root is the directory containing sample_image2video.py, train_image2video_lora.py, hyvideo/, and ckpts/. The generated skill is stored separately under skills/disco/hunyuanvideo-i2v; it is not the checkout root. In the commands below, set CHECKOUT_ROOT to the real checkout and SKILL_ROOT to this skill directory, then run from CHECKOUT_ROOT:

export CHECKOUT_ROOT=<checkout-root>
export SKILL_ROOT="$CHECKOUT_ROOT/skills/disco/hunyuanvideo-i2v"
cd "$CHECKOUT_ROOT"
# decord 0.6.0 has limited pip wheels on newer Python versions; prefer conda-forge first.
conda install -c conda-forge decord=0.6.0
python -m pip install -r requirements.txt

requirements.txt is the fresh-install base: it pins transformers==4.48.0 with compatible tokenizers==0.21.0 and declares the direct HyVAE imports decord==0.6.0 and omegaconf==2.3.0. On CPython versions without a matching decord wheel, install that dependency from conda-forge before running pip; do not silently substitute a fake package. PyTorch/CUDA wheels are intentionally not guessed here. Install a wheel matching the host separately; install requirements-optional.txt only for the matching GPU workflow (DeepSpeed, flash-attn, or xDiT).

The repository is CUDA-first. A lightweight import check that does not allocate CUDA is:

python "$SKILL_ROOT/scripts/check_runtime.py" --repo-root "$CHECKOUT_ROOT" --check-imports --check-decord --check-omegaconf

Add --check-cuda --check-flash-attn --check-deepspeed only after those optional backends are installed. Checkpoint validation is separate and does not download or invent weights:

python "$SKILL_ROOT/scripts/check_checkpoint_layout.py" --ckpts-root "$CHECKOUT_ROOT/ckpts" --mode inference

If pip check or import smoke fails, read the troubleshooting reference before changing anything else.

Choose a Route

inference

Read sub-skills/inference/SKILL.md when the task is to generate a video from one image, compare stable vs dynamic motion, enable LoRA inference, or use xDiT sequence-parallel inference.

Typical signals:

• sample_image2video.py
• --i2v-mode
• --i2v-image-path
• --i2v-resolution 360p|540p|720p
• --i2v-stability
• --use-lora
• --ulysses-degree / --ring-degree
• --use-cpu-offload

lora-training

Read sub-skills/lora-training/SKILL.md when the task is to train or resume a LoRA effect model, tune DeepSpeed settings, or inspect training-data expectations.

Typical signals:

• train_image2video_lora.py
• --task-flag
• --output-dir
• --data-jsons-path
• --use-lora
• --lora-rank
• deepspeed --include localhost:0

data-preparation

Read sub-skills/data-preparation/SKILL.md when the task is to build VAE latents from raw videos, validate meta_file.list / raw caption JSON files, or inspect the processed latent JSON layout used by training.

Typical signals:

• hyvideo/hyvae_extract/
• start.sh
• vae.yaml
• meta_file.list
• raw video_path + raw_caption.long caption
• processed json_path/*.json + .npy

Shared References and Scripts

• references/checkpoints.md — checkpoint tree, download commands, and missing-asset symptoms.
• references/model-overview.md — model/config/resolution summary and output constraints.
• references/troubleshooting.md — cross-cutting install, CUDA, flash-attn, checkpoint, and data-layout fixes.
• scripts/check_runtime.py — import and backend smoke checker.
• scripts/check_checkpoint_layout.py — validates the expected ckpts/ tree before you try to run a workflow.

Notes

• Real inference and LoRA training both need the repo checkpoints in ckpts/; the repo does not ship them.
• flash-attn is required for the inspected runtime path because the model attention code uses it by default.
• The repository supports xDiT multi-GPU inference through xfuser, but that dependency is optional and not part of the minimum inspection environment.