---

name: "inference" description: "Routes HunyuanVideo-I2V image-to-video generation tasks, including stable/dynamic motion recipes, LoRA-augmented sampling, xDiT multi-GPU inference, and the checkpoint checks needed before a real render." disable-model-invocation: true metadata: disco-role: operating license: NOASSERTION

Inference

Use this sub-skill when the user wants to turn a single image into a video, compare stable versus dynamic motion, run LoRA-augmented sampling, or understand the xDiT parallel inference path.

What Belongs Here

• Single-image I2V generation commands.
• Stable vs dynamic motion settings (--i2v-stability, --flow-shift).
• LoRA inference (--use-lora, --lora-path, --lora-scale).
• xDiT/sequence-parallel generation (--ulysses-degree, --ring-degree, ALLOW_RESIZE_FOR_SP).
• Output naming, save-path handling, and sampler-level constraints.

What Does Not Belong Here

• Training a new LoRA model. Use ../lora-training/SKILL.md.
• Building the latent dataset from raw videos. Use ../data-preparation/SKILL.md.
• Downloading checkpoints or validating the asset tree. Use ../../references/checkpoints.md and ../../scripts/check_checkpoint_layout.py.

Read First

• references/workflows.md for stable, dynamic, LoRA, and xDiT command patterns.
• references/cli-reference.md for the verified CLI flags and their main defaults.
• references/api-reference.md for the sampler class, predict() signature, and load helpers.
• references/troubleshooting.md for CUDA, flash-attn, checkpoint, memory, and xDiT failures.

Bundled Scripts

• scripts/run_sample_image2video.py — build or execute the canonical inference command safely. This helper is under $SKILL_ROOT; run it from $CHECKOUT_ROOT with --repo-root "$CHECKOUT_ROOT". Run with --dry-run first, then add --execute only after checkpoint and GPU checks pass.

Typical Workflow

Commands run from the real checkout root. $SKILL_ROOT is the generated skill directory, not the checkout:

1. Confirm the checkpoint tree with $SKILL_ROOT/scripts/check_checkpoint_layout.py --ckpts-root "$CHECKOUT_ROOT/ckpts" --mode inference.
2. Decide whether the request is stable, dynamic, LoRA-augmented, or xDiT parallel inference.
3. Use $SKILL_ROOT/sub-skills/inference/scripts/run_sample_image2video.py --repo-root "$CHECKOUT_ROOT" to print the exact command.
4. If the user approves execution, rerun the wrapper with --execute.
5. Inspect the mp4 files written under the chosen --save-path.

Constraints to Remember

• video_length - 1 must be a multiple of 4.
• i2v_resolution is limited to 360p, 540p, or 720p.
• The code aligns height and width to 16.
• The inspected model path uses flash-attn by default.
• xDiT needs ring_degree * ulysses_degree to equal the active GPU count.
• The README documents large-memory requirements for full 720p runs; use --use-cpu-offload or a lower resolution if the host cannot fit the model.