ComfyUI_RH_Helios

ComfyUI custom nodes for Helios — a breakthrough 14B real-time long video generation model that achieves minute-scale, high-quality video synthesis at 19.5 FPS on a single H100 GPU.

Supports Text-to-Video, Image-to-Video, and Video-to-Video generation within ComfyUI.

✨ Features

• Text-to-Video (T2V) — Generate videos from text prompts
• Image-to-Video (I2V) — Animate a static image into video with text guidance
• Video-to-Video (V2V) — Transform existing videos with text prompts
• Low VRAM Mode — Group offloading support, runs with as low as ~6GB VRAM
• Pipeline Caching — Automatic model caching to avoid redundant loading
• Progress Bar — Real-time ComfyUI progress tracking during generation

🛠️ Installation

1. Clone this repository into ComfyUI custom nodes directory

cd ComfyUI/custom_nodes
git clone https://github.com/HM-RunningHub/ComfyUI_RH_Helios.git

2. Install dependencies

cd ComfyUI_RH_Helios
pip install -r requirements.txt

Note

: Requires PyTorch >= 2.7.1 with CUDA support. Make sure your PyTorch is installed with the correct CUDA version before installing requirements.

📦 Model Download & Installation

Model Directory Structure

The Helios-Distilled model must be placed in ComfyUI/models/Helios-Distilled/ with the following structure:

ComfyUI/
└── models/
    └── Helios-Distilled/
        ├── transformer/          # Transformer model weights
        ├── vae/                  # VAE model weights
        ├── scheduler/            # Scheduler configuration
        ├── tokenizer/            # Tokenizer files
        ├── text_encoder/         # Text encoder weights
        └── model_index.json      # Model index file

Download Methods

Method 1: Download from HuggingFace (Recommended)

pip install "huggingface_hub[cli]"
huggingface-cli download BestWishYsh/Helios-Distilled --local-dir ComfyUI/models/Helios-Distilled

Method 2: Download from ModelScope (For China users)

pip install modelscope
modelscope download BestWishYSH/Helios-Distilled --local_dir ComfyUI/models/Helios-Distilled

Method 3: Manual Download

Model	Link	Description
Helios-Distilled	HuggingFace / ModelScope	Best efficiency, x0-prediction with custom HeliosDMDScheduler. Recommended for ComfyUI.
Helios-Base	HuggingFace / ModelScope	Best quality, v-prediction with standard CFG.
Helios-Mid	HuggingFace / ModelScope	Intermediate checkpoint, may not meet expected quality.

Model Selection Guide

Your GPU VRAM	Low VRAM Mode	Recommended Model	Notes
≤ 8GB	✅ Enable (leaf_level)	Helios-Distilled	~6GB VRAM with group offloading
8-16GB	✅ Enable (block_level)	Helios-Distilled	Balanced speed and memory
≥ 24GB	❌ Disable	Helios-Distilled / Helios-Base	Full speed inference

🚀 Usage

Example Workflow

Download the example workflow from workflows/example_workflow.json and import it into ComfyUI.

The example demonstrates:

1. Text-to-Video — Generate a tropical fish video from a text prompt
2. Image-to-Video — Animate a reference image with a text description
3. Video-to-Video — Transform an input video with a new prompt

Quick Start

1. Add a RunningHub HeliosModelLoader node to load the model
2. Connect it to a RunningHub HeliosT2V / HeliosI2V / HeliosV2V node
3. Connect the output to a Save Video node
4. Enter your prompt and run!

📝 Node Reference

RunningHub HeliosModelLoader

Loads the Helios pipeline with configurable options.

Parameter	Type	Default	Description
weight_dtype	bf16 / fp16	bf16	Model weight precision
enable_low_vram_mode	Boolean	True	Enable group offloading to save VRAM
group_offloading_type	block_level / leaf_level	block_level	Offloading granularity (leaf_level uses less VRAM)

Output: HELIOS_PIPE — The loaded pipeline object

RunningHub HeliosT2V

Generates video from a text prompt.

Parameter	Type	Default	Description
prompt	String	—	Text description of the video to generate
width	Int	640	Video width (128-1920, step 16)
height	Int	384	Video height (128-1088, step 16)
num_frames	Int	99	Number of frames to generate (1-480)
num_inference_steps	Int	50	Denoising steps
guidance_scale	Float	1.0	Classifier-free guidance scale (0-20)
seed	Int	42	Random seed for reproducibility
is_enable_stage2	Boolean	True	Enable pyramid stage2 acceleration
pyramid_steps	String	"2,2,2"	Comma-separated pyramid inference steps
is_amplify_first_chunk	Boolean	True	Amplify first chunk quality
negative_prompt	String	""	(Optional) Negative prompt

Output: VIDEO

RunningHub HeliosI2V

Generates video from an image + text prompt. Same parameters as T2V plus:

Parameter	Type	Description
image	IMAGE	Input reference image

RunningHub HeliosV2V

Transforms a video with text guidance. Same parameters as T2V plus:

Parameter	Type	Description
video	VIDEO	Input video to transform

Frame Count Guide

Helios generates 33 frames per chunk. For optimal results, use multiples of 33:

num_frames	Actual Frames	Duration @24fps	Duration @16fps
99	99 (33×3)	~4s	~6s
132	132 (33×4)	~5.5s	~8s
264	264 (33×8)	~11s	~16s

📄 License

This project is released under the Apache 2.0 License.

🔗 Links

• RunningHub
• Original Helios Project
• Helios Paper (arXiv)
• HuggingFace Models
• ModelScope Models

🙏 Acknowledgements

This project is based on Helios, developed by PKU-YuanGroup. We thank them for their outstanding contribution to real-time long video generation.