ComfyUI_RH_Helios

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.