ComfyUI Ref2VA VSA: Character Video Setup Guide

From a reference image to your first short video: model downloads, Windows and Linux setup, workflow settings and fixes.

Start here: what you will make

Turn a character reference image and a written scene into a short video with the MiniMax H3 Ref2VA workflow. This custom node adds a VSA attention patch to an existing ComfyUI setup; it is not a standalone video editor or a one-click hosted service.

Who this guide is for Use this walkthrough if you already have ComfyUI working on an NVIDIA CUDA machine and are comfortable downloading model weights. It explains each step, but the underlying node is experimental. A CPU-only VPS, Mac or non-CUDA GPU is not a supported substitute for this particular kernel path.

Your first successful run

Check GPU and ComfyUI
Install the custom node
Put six model files in the right folders
Load one reference image and the workflow
Queue one video
Play the output and check the result

Source review: 14 September 2026. Commands, filenames and defaults were checked against the repository and workflow. RexxuLabs has not performed a clean-machine installation or a GPU generation run for this article.

Before downloading: check your machine

Check	What to confirm
GPU	The repository targets 24GB-class NVIDIA GPUs and reports results on an RTX 4090. Its reported 13.5GB peak is not a guarantee that this whole workflow fits a smaller card.
ComfyUI	Use a current compatible build with native MiniMax H3 nodes. Confirm a normal workflow already runs; back up settings before updating.
Python environment	Use the same Python that launches ComfyUI. Windows portable uses python_embeded, not your system Python.
CUDA kernels	CUDA-enabled PyTorch, BF16 support and the comfy-kitchen CUDA backend with sol_attn are required by the node's code.
Memory and disk	The six listed files total about 48.28GB (44.96GiB), before caches, Python packages and outputs. Allow additional free space and enough system RAM for loading/offloading. No universal RAM minimum is established by this guide.
Reference rights	Use an image you own or have permission to animate. Do not present synthetic footage as a real recording.

Do not copy an old CUDA version blindly The node README's PyTorch 2.4+/CUDA 12.1+ shorthand is not a complete compatibility matrix. Current [comfy-kitchen requirements](https://github.com/Comfy-Org/comfy-kitchen#installation) can be newer. Match ComfyUI, PyTorch, kitchen wheels and the NVIDIA driver together; do not run a blind global upgrade.

If ComfyUI is not installed yet, complete the [official Windows portable setup](https://docs.comfy.org/installation/comfyui_portable_windows) or [manual installation](https://docs.comfy.org/installation/manual_install) first. General ComfyUI support on an operating system does not prove that this CUDA custom node works there.

1. Install the custom node in the correct folder

Stop ComfyUI first. Open your terminal in the folder that contains ComfyUI's main.py, models and custom_nodes. That is the ComfyUI root, not the outer portable folder. Run the clone once; if that destination already exists, inspect and back it up rather than replacing it.

git clone https://github.com/Kablex/ComfyUI-Ref2VA-VSA.git custom_nodes/ComfyUI-Ref2VA-VSA
git -C custom_nodes/ComfyUI-Ref2VA-VSA rev-parse HEAD

The command prints the installed node revision. Compare it with the source-review commit in the final section. Custom nodes execute Python on your machine, so review the repository before installing.

Windows portable: from the inner ComfyUI folder, use its bundled interpreter to install this node's requirements:

..\python_embeded\python.exe -m pip install -r .\custom_nodes\ComfyUI-Ref2VA-VSA\requirements.txt
..\python_embeded\python.exe -m pip check

Manual Linux or Windows installation: activate the same virtual environment used for ComfyUI, then run:

python -c "import sys; print(sys.executable)"
python -m pip install -r custom_nodes/ComfyUI-Ref2VA-VSA/requirements.txt
python -m pip check

These requirements declare torch and safetensors. They do not by themselves guarantee a working CUDA kitchen build. If pip proposes replacing a working GPU stack, stop and resolve the version mismatch first.

2. Verify the CUDA attention backend

Save the following as check_ref2va.py in the ComfyUI root using your text editor. It checks the actual environment without loading a video model or generating a clip.

import sys
import torch
import comfy_kitchen as ck

print("Python:", sys.executable)
print("PyTorch:", torch.__version__, "CUDA runtime:", torch.version.cuda)
assert torch.cuda.is_available(), "CUDA is not available in this Python environment"
print("GPU:", torch.cuda.get_device_name(0))
print("VRAM GiB:", round(torch.cuda.get_device_properties(0).total_memory / 2**30, 1))
assert torch.cuda.is_bf16_supported(), "This setup needs CUDA BF16 support"
backend = ck.list_backends().get("cuda", {})
print("Kitchen CUDA backend:", backend)
assert backend.get("available"), "comfy-kitchen CUDA backend is unavailable"
assert "sol_attn" in backend.get("capabilities", []), "CUDA sol_attn is unavailable"
print("PREFLIGHT PASSED: run the workflow next; generation is not yet verified")

..\python_embeded\python.exe .\check_ref2va.py

python check_ref2va.py

Pass this check before model downloads Expected final line: PREFLIGHT PASSED. An import error, unavailable CUDA backend or missing sol_attn means the environment is not ready. Follow the [official kitchen installation guidance](https://github.com/Comfy-Org/comfy-kitchen#installation) for a compatible wheel/build; a Python import alone is not evidence that the CUDA operation is available. Even a passed preflight is not a completed generation.

3. Download the six required model files

Open each publisher file page, check its size and any license/access terms, then download the actual .safetensors file. Keep the exact filename. All destinations below are relative to ComfyUI/models/. Do not put the diffusion model in checkpoints/.

Updated download locations The repository README's old Comfy-Org/MiniMax_H3_repackaged links returned an access error during this review. The table uses the current public Comfy-Org/MiniMax-H3 distribution with the same required filenames. All six corresponding download endpoints passed a header-only check on 14 September 2026; no model weights were downloaded for this guide.

Component and publisher	Exact filename	Folder under models/
[Reference-to-video model](https://huggingface.co/Comfy-Org/MiniMax-H3/blob/main/diffusion_models/minimax_h3_ref2va_pruned_int8_convrot.safetensors)	minimax_h3_ref2va_pruned_int8_convrot.safetensors	diffusion_models/
[VSA gate](https://huggingface.co/barelymining/ComfyUI-MiniMax-H3-FastVideo/blob/main/fasth3_vsa_gate.safetensors)	fasth3_vsa_gate.safetensors	loras/
[Four-step Turbo LoRA](https://huggingface.co/lightx2v/Minimax-h3-Turbo/blob/main/minimax_h3_ref2v_turbo_4step_v0.1_comfyui_bf16.safetensors)	minimax_h3_ref2v_turbo_4step_v0.1_comfyui_bf16.safetensors	loras/
[Text encoder](https://huggingface.co/Comfy-Org/MiniMax-H3/blob/main/text_encoders/qwen3vl_32b_minimax_h3_nvfp4_awq.safetensors)	qwen3vl_32b_minimax_h3_nvfp4_awq.safetensors	text_encoders/
[Video VAE](https://huggingface.co/Comfy-Org/MiniMax-H3/blob/main/vae/minimax_h3_video_vae_fp16.safetensors)	minimax_h3_video_vae_fp16.safetensors	vae/
[Audio VAE](https://huggingface.co/Comfy-Org/MiniMax-H3/blob/main/vae/minimax_h3_audio_vae_fp32.safetensors)	minimax_h3_audio_vae_fp32.safetensors	vae/

The two VAEs are separate: one decodes video, the other audio. Keep both for the supplied video-and-audio workflow. The gate file is not the Turbo LoRA, and neither replaces the main Ref2VA checkpoint.

Approximate download sizes: diffusion 20.97GB, encoder 15.69GB, video VAE 5.21GB, audio VAE 0.61GB, gate 3.85GB and Turbo LoRA 1.96GB. The [Comfy-Org model card](https://huggingface.co/Comfy-Org/MiniMax-H3) explains the quantized variants and model license; its NVFP4_AWQ encoder does not require a Blackwell GPU.

Keep the first run consistent This guide uses the bundled four-step workflow and its matching four-step Turbo LoRA. A newer eight-step LoRA or another H3 task checkpoint is not a drop-in replacement. Change one component at a time only after the baseline works.

An HTML login/error page saved with a .safetensors suffix is not a model. If a file is tiny, incomplete or missing from a picker, check the download and folder before retrying generation.

4. Add your reference image and restart

Put your own JPG or PNG into ComfyUI/input/. For the repository's supplied example, use the command for your shell below. These paths assume you are still in the ComfyUI root and will not overwrite an existing example file.

if (!(Test-Path .\input\example_character.jpg)) {
    Copy-Item .\custom_nodes\ComfyUI-Ref2VA-VSA\assets\example_character.jpg .\input\example_character.jpg
}

if [ ! -e input/example_character.jpg ]; then
  cp custom_nodes/ComfyUI-Ref2VA-VSA/assets/example_character.jpg input/example_character.jpg
fi

Restart ComfyUI using its normal launcher. For portable Windows, return to the outer portable folder and use your existing NVIDIA launcher. For a manual installation, run python main.py in the active ComfyUI environment. Open the local address printed by the server, usually http://127.0.0.1:8188.

Search the node menu for Ref2VA VSA Gate Transplant (EXPERIMENTAL), under FastH3/VSA. If it is absent, read the terminal's custom-node import error before moving on.

5. Open the workflow and check every picker

In ComfyUI, open or drag in [ref2va_vsa_4step_rtx4090.json](https://github.com/Kablex/ComfyUI-Ref2VA-VSA/blob/92e3f8357c626f63cfe3813ec914f2cf3fbc500c/workflows/ref2va_vsa_4step_rtx4090.json) from custom_nodes/ComfyUI-Ref2VA-VSA/workflows/. This file is API-format JSON. The current ComfyUI frontend can import it and build a graph, so the initial layout may look different from a hand-arranged tutorial canvas.

Before pressing Run / Queue

No missing-node or import errors remain. In particular, the native MiniMax H3 and Ref2VAVSAGatePatch nodes exist.
UNETLoader selects the Ref2VA diffusion model, not a text-to-video or first/last-frame checkpoint.
CLIPLoader selects the listed Qwen encoder and its type is minimax.
Both VAE loaders, the Turbo LoRA and the gate picker select the downloaded files.
LoadImage shows the reference you intend to animate. Replace the default example_character.jpg selection if using your own file.
The model path is connected in the order shown below; do not apply the same VSA patch twice.

Model connection order

UNETLoader — Ref2VA model
LoraLoaderModelOnly — Four-step Turbo, strength 1.0
Ref2VAVSAGatePatch — Gate file, sparsity 0.75
MiniMaxH3SigmaShift — Video 12, audio 3
Scheduler and guider feed the sampler

A picker may contain subfolder-prefixed names if you store models in subdirectories. Select the actual file rather than renaming an unrelated checkpoint. If API JSON import fails, check the frontend version and missing node definitions; do not paste it into an arbitrary workflow-format converter.

6. Run one controlled test

Keep the bundled settings for the baseline. Enter a short prompt with a subject, one action, a setting and a camera instruction. For example:

The character in the reference image smiles and slowly turns toward the camera in a softly lit room. A steady medium shot, gentle natural movement, consistent clothing and background.

Setting	Bundled value
Size	1344 × 768
Frames / output FPS	124 frames / 24 fps, about 5.17 seconds
Sampling	4 steps; euler sampler; simple scheduler; denoise 1.0
Turbo LoRA strength	1.0
VSA sparsity	0.75
Sigma shift	video 12; audio 3
Seed	981445682258077
Reference sizing	match

Queue one job and watch the server log. The first run can include model loading and initialization. Do not start a large batch or repeatedly click Run while diagnosing a failure. Save your working workflow before changing resolution, frame count, models or sparsity.

7. Find the saved video and judge success

The bundled SaveVideo prefix is video/FastH3_VSA_Ref2VA_Comparison. With ComfyUI's default output directory, look under ComfyUI/output/video/ for a counter-suffixed file starting with FastH3_VSA_Ref2VA_Comparison. The format and codec are set to auto, so check the actual saved extension rather than assuming a fixed filename.

A useful first-run result

The queue finishes without a red node or traceback, and a non-empty video file exists.
The video plays through, has the expected dimensions and roughly five-second duration, and its audio can be inspected.
The intended reference image was used. Review identity, clothing, motion, flicker and any visual artifacts yourself.
Record the ComfyUI/node revisions, model filenames, settings, GPU, seed and elapsed time.
For a second timing test, rerun after models have loaded and record warm timing separately from first-run timing.

Speed is not the installation test The repository author reports about 95 seconds for the first run and 72 seconds warm on an RTX 4090 with this example configuration. Those are upstream benchmark claims, not RexxuLabs measurements or a deadline your machine must meet. Successful generation and acceptable output quality matter more than matching a stopwatch.

Troubleshooting: start with the first error

Symptom	What to check next
Custom node is missing	Confirm the folder is directly under custom_nodes, restart, and read the first import traceback. Install requirements with ComfyUI's Python, not another interpreter.
No module named comfy_kitchen	Verify which Python launched the app, then install a compatible kitchen build using its official instructions.
CUDA backend unavailable / no sol_attn	Run the preflight. Match the kitchen wheel/build, PyTorch, CUDA runtime and NVIDIA driver. Import success is not sufficient.
CUDA BF16 / head_dim=128 error	The node enforces its CUDA BF16 attention path. Use the native H3 model/workflow; do not force an arbitrary model, dtype or CPU fallback.
Model not found / invalid safetensors	Check exact filename, model folder, download completion and picker selection. An error/login page is not a model file.
Expected 50 blocks / gate mismatch	Check that the Ref2VA model and 50-block VSA gate match the supplied workflow, and that the file is not a LoRA selected as a gate.
Patch already installed	Start from the original workflow/model chain and ensure VSA is applied once. Do not stack attention patches for the baseline.
Out of memory	Close other GPU-heavy apps and queue only one job. Keep a copy, then try a smaller supported resolution or frame count. Offloading can require more RAM and time; the advertised peak is not a lower-VRAM guarantee.
Reference image not found	Put the file in the configured input folder and reselect it in LoadImage. Check the actual ComfyUI root instead of appending ComfyUI/input from custom_nodes.
Workflow will not import	Use the actual JSON file, not a GitHub HTML page. Update the frontend compatibly and resolve missing native/custom node definitions.
Runs, but looks wrong or is slower	Check the reference, correct model family, prompt, four-step LoRA, wiring and baseline settings. Compare first-run and warm timing separately; record changes one at a time.

When asking for help, include the first traceback, OS, GPU/VRAM, package versions, node commit and workflow settings. Remove private file paths, tokens and personal images from shared logs.

Optional: one prompt for a coding assistant

Prefer guided setup? Open a terminal-capable coding assistant in a local work folder and copy this prompt. It should check compatibility and ask before large downloads or paid GPU use, not claim an unattended installation will always work.

Help me set up https://github.com/Kablex/ComfyUI-Ref2VA-VSA for local ComfyUI reference-to-video generation.
Start with an audit, not downloads or system changes.

1. Locate my existing ComfyUI folder, installation type and actual Python executable.
   Check NVIDIA GPU, VRAM, driver, free RAM/disk, CUDA-enabled PyTorch, BF16,
   native MiniMax H3 nodes and comfy-kitchen's CUDA sol_attn capability.
2. Read the current README, requirements.txt, nodes.py and bundled workflow.
   This guide reviewed commit 92e3f8357c626f63cfe3813ec914f2cf3fbc500c. Report any changes.
3. Explain unsupported hardware or dependency conflicts before proceeding.
   Do not replace my CUDA/PyTorch setup or modify another Python environment.
4. Back up my workflow/settings. Install the custom node into the existing
   custom_nodes folder without overwriting a checkout or my model files.
5. List the six exact model files, publisher links, destinations, current sizes
   and model licenses. Ask before large downloads or using paid GPU time.
6. Put a reference image I own or have permission to use into ComfyUI/input.
   Import ref2va_vsa_4step_rtx4090.json; API-format import is supported by the
   current ComfyUI frontend. Check for missing nodes and choose all model files.
7. Start with the bundled four-step Euler/simple settings and one reference image.
   Keep the four-step LoRA; do not silently substitute an eight-step model.
8. After I approve running a test, queue one job. Inspect the saved video and
   audio, input reference, duration, resolution, errors and actual elapsed time.
9. Save a report with versions, node commit, workflow, seed, output path and
   first-run versus repeated-run timing. Do not claim the author's 72-second
   benchmark was reproduced unless this machine actually reproduces it.

Keep ComfyUI local. Do not open public ports, delete user data, change security
settings, install unrelated extensions, or continue past an unresolved error.

Questions before you commit time or money

Is this free to use?

The custom-node code is Apache-2.0 licensed. That does not make GPU hardware, electricity or cloud GPU rental free, and each model distribution can have its own license and access terms. The local workflow does not require buying a RexxuLabs plan.

Can I run it on a small free VPS or a Mac?

Not through the CUDA-only path implemented by this node. General ComfyUI installation support does not make this particular attention kernel compatible with a CPU-only server or Apple Metal.

Will it always preserve the character's identity?

No guarantee is established here. The patch treats reference conditioning differently from generated-video attention, but you still need to inspect the actual output for identity drift and other artifacts.

Should I use the newest model or the newest eight-step LoRA?

Not for this baseline. Reproduce the bundled model and four-step workflow first. A different LoRA, sampler or checkpoint is a separate configuration that needs its own testing.

Sources, versions and verification scope

Reviewed node revision: [92e3f8357c62](https://github.com/Kablex/ComfyUI-Ref2VA-VSA/tree/92e3f8357c626f63cfe3813ec914f2cf3fbc500c) on 14 September 2026. Use the revision you actually installed when reporting errors.

[Repository README and reported benchmark](https://github.com/Kablex/ComfyUI-Ref2VA-VSA/blob/92e3f8357c626f63cfe3813ec914f2cf3fbc500c/README.md)
[Node implementation and runtime checks](https://github.com/Kablex/ComfyUI-Ref2VA-VSA/blob/92e3f8357c626f63cfe3813ec914f2cf3fbc500c/nodes.py)
[Dependency declarations](https://github.com/Kablex/ComfyUI-Ref2VA-VSA/blob/92e3f8357c626f63cfe3813ec914f2cf3fbc500c/requirements.txt)
[Exact four-step workflow](https://github.com/Kablex/ComfyUI-Ref2VA-VSA/blob/92e3f8357c626f63cfe3813ec914f2cf3fbc500c/workflows/ref2va_vsa_4step_rtx4090.json)
[Custom-node Apache-2.0 license](https://github.com/Kablex/ComfyUI-Ref2VA-VSA/blob/92e3f8357c626f63cfe3813ec914f2cf3fbc500c/LICENSE)
[Current comfy-kitchen installation and backend capabilities](https://github.com/Comfy-Org/comfy-kitchen)
[Current Comfy-Org model distribution and license](https://huggingface.co/Comfy-Org/MiniMax-H3)
[Official ComfyUI manual setup](https://docs.comfy.org/installation/manual_install)
[Official frontend API-JSON import handling](https://github.com/Comfy-Org/ComfyUI_frontend/blob/main/src/scripts/metadata/json.ts)

Verified here: repository source, workflow fields, file destinations and publication/rendering checks. Not verified here: a clean-machine install, CUDA execution, video/audio quality, compatibility with every GPU or the author's performance numbers. Dependencies and publisher downloads can change after this review.