--- base_model: VideoRebirthAI/hyperflow-h3-flash base_model_relation: quantized license: other license_name: minimax-h3-community-license license_link: LICENSE pipeline_tag: text-to-video library_name: mlx tags: - mlx - moonbox - minimax-h3 - hyperflow - text-to-video - video-generation - audio-generation --- # HyperFlow H3 Flash MLX MLX builds of [HyperFlow H3 Flash](https://huggingface.co/VideoRebirthAI/hyperflow-h3-flash), made by Moonbox for Apple Silicon Macs. Each precision is a folder; keep a folder's files together. Only the parts listed below are converted: the rest of the pipeline comes from the original repository unless the section below says otherwise. ## Files The last column is how far each build is from the original PyTorch model on the same inputs (see the section below for what was measured). | Precision | File | Size | sha256 | Checked against the original | |---|---|---|---|---| | bf16 | [`bf16/LICENSE`](https://huggingface.co/moonbox-ai/hyperflow-h3-flash-MLX/blob/main/bf16/LICENSE) | 0.00 GB | `59b99642b95e` | block cosine >= 0.9992 | | bf16 | [`bf16/NOTICE`](https://huggingface.co/moonbox-ai/hyperflow-h3-flash-MLX/blob/main/bf16/NOTICE) | 0.00 GB | `12be6d1eeaa7` | block cosine >= 0.9992 | | bf16 | [`bf16/config.json`](https://huggingface.co/moonbox-ai/hyperflow-h3-flash-MLX/blob/main/bf16/config.json) | 0.00 GB | `c84feb34369c` | block cosine >= 0.9992 | | bf16 | [`bf16/model-00001-of-00007.safetensors`](https://huggingface.co/moonbox-ai/hyperflow-h3-flash-MLX/blob/main/bf16/model-00001-of-00007.safetensors) | 4.46 GB | `399181cfc93c` | block cosine >= 0.9992 | | bf16 | [`bf16/model-00002-of-00007.safetensors`](https://huggingface.co/moonbox-ai/hyperflow-h3-flash-MLX/blob/main/bf16/model-00002-of-00007.safetensors) | 4.36 GB | `ea58b71c034a` | block cosine >= 0.9992 | | bf16 | [`bf16/model-00003-of-00007.safetensors`](https://huggingface.co/moonbox-ai/hyperflow-h3-flash-MLX/blob/main/bf16/model-00003-of-00007.safetensors) | 4.33 GB | `21f4ae93434b` | block cosine >= 0.9992 | | bf16 | [`bf16/model-00004-of-00007.safetensors`](https://huggingface.co/moonbox-ai/hyperflow-h3-flash-MLX/blob/main/bf16/model-00004-of-00007.safetensors) | 4.34 GB | `ddc3694af30c` | block cosine >= 0.9992 | | bf16 | [`bf16/model-00005-of-00007.safetensors`](https://huggingface.co/moonbox-ai/hyperflow-h3-flash-MLX/blob/main/bf16/model-00005-of-00007.safetensors) | 4.42 GB | `171398ffff9d` | block cosine >= 0.9992 | | bf16 | [`bf16/model-00006-of-00007.safetensors`](https://huggingface.co/moonbox-ai/hyperflow-h3-flash-MLX/blob/main/bf16/model-00006-of-00007.safetensors) | 4.49 GB | `3c885b2821c2` | block cosine >= 0.9992 | | bf16 | [`bf16/model-00007-of-00007.safetensors`](https://huggingface.co/moonbox-ai/hyperflow-h3-flash-MLX/blob/main/bf16/model-00007-of-00007.safetensors) | 1.16 GB | `8928c1a19b2f` | block cosine >= 0.9992 | | bf16 | [`bf16/model.safetensors.index.json`](https://huggingface.co/moonbox-ai/hyperflow-h3-flash-MLX/blob/main/bf16/model.safetensors.index.json) | 0.00 GB | `c8d091c69ca5` | block cosine >= 0.9992 | | 8bit | [`8bit/LICENSE`](https://huggingface.co/moonbox-ai/hyperflow-h3-flash-MLX/blob/main/8bit/LICENSE) | 0.00 GB | `59b99642b95e` | block cosine >= 0.9991, step-0 0.037, clip PSNR vs bf16 18.9 dB | | 8bit | [`8bit/NOTICE`](https://huggingface.co/moonbox-ai/hyperflow-h3-flash-MLX/blob/main/8bit/NOTICE) | 0.00 GB | `12be6d1eeaa7` | block cosine >= 0.9991, step-0 0.037, clip PSNR vs bf16 18.9 dB | | 8bit | [`8bit/config.json`](https://huggingface.co/moonbox-ai/hyperflow-h3-flash-MLX/blob/main/8bit/config.json) | 0.00 GB | `8eae8486c79e` | block cosine >= 0.9991, step-0 0.037, clip PSNR vs bf16 18.9 dB | | 8bit | [`8bit/model-00001-of-00004.safetensors`](https://huggingface.co/moonbox-ai/hyperflow-h3-flash-MLX/blob/main/8bit/model-00001-of-00004.safetensors) | 4.30 GB | `cb03cb1bc0fe` | block cosine >= 0.9991, step-0 0.037, clip PSNR vs bf16 18.9 dB | | 8bit | [`8bit/model-00002-of-00004.safetensors`](https://huggingface.co/moonbox-ai/hyperflow-h3-flash-MLX/blob/main/8bit/model-00002-of-00004.safetensors) | 4.41 GB | `ae5fdac10334` | block cosine >= 0.9991, step-0 0.037, clip PSNR vs bf16 18.9 dB | | 8bit | [`8bit/model-00003-of-00004.safetensors`](https://huggingface.co/moonbox-ai/hyperflow-h3-flash-MLX/blob/main/8bit/model-00003-of-00004.safetensors) | 4.31 GB | `02951a594b6b` | block cosine >= 0.9991, step-0 0.037, clip PSNR vs bf16 18.9 dB | | 8bit | [`8bit/model-00004-of-00004.safetensors`](https://huggingface.co/moonbox-ai/hyperflow-h3-flash-MLX/blob/main/8bit/model-00004-of-00004.safetensors) | 1.73 GB | `7b3021d820d3` | block cosine >= 0.9991, step-0 0.037, clip PSNR vs bf16 18.9 dB | | 8bit | [`8bit/model.safetensors.index.json`](https://huggingface.co/moonbox-ai/hyperflow-h3-flash-MLX/blob/main/8bit/model.safetensors.index.json) | 0.00 GB | `b620e0bf7dbf` | block cosine >= 0.9991, step-0 0.037, clip PSNR vs bf16 18.9 dB | | 6bit | [`6bit/LICENSE`](https://huggingface.co/moonbox-ai/hyperflow-h3-flash-MLX/blob/main/6bit/LICENSE) | 0.00 GB | `59b99642b95e` | block cosine >= 0.9987, step-0 0.052, clip PSNR vs bf16 15.6 dB | | 6bit | [`6bit/NOTICE`](https://huggingface.co/moonbox-ai/hyperflow-h3-flash-MLX/blob/main/6bit/NOTICE) | 0.00 GB | `12be6d1eeaa7` | block cosine >= 0.9987, step-0 0.052, clip PSNR vs bf16 15.6 dB | | 6bit | [`6bit/config.json`](https://huggingface.co/moonbox-ai/hyperflow-h3-flash-MLX/blob/main/6bit/config.json) | 0.00 GB | `6abd3af18230` | block cosine >= 0.9987, step-0 0.052, clip PSNR vs bf16 15.6 dB | | 6bit | [`6bit/model-00001-of-00003.safetensors`](https://huggingface.co/moonbox-ai/hyperflow-h3-flash-MLX/blob/main/6bit/model-00001-of-00003.safetensors) | 4.30 GB | `bfffdee7327d` | block cosine >= 0.9987, step-0 0.052, clip PSNR vs bf16 15.6 dB | | 6bit | [`6bit/model-00002-of-00003.safetensors`](https://huggingface.co/moonbox-ai/hyperflow-h3-flash-MLX/blob/main/6bit/model-00002-of-00003.safetensors) | 4.33 GB | `4ca30db6a245` | block cosine >= 0.9987, step-0 0.052, clip PSNR vs bf16 15.6 dB | | 6bit | [`6bit/model-00003-of-00003.safetensors`](https://huggingface.co/moonbox-ai/hyperflow-h3-flash-MLX/blob/main/6bit/model-00003-of-00003.safetensors) | 2.70 GB | `7b7233f8fd09` | block cosine >= 0.9987, step-0 0.052, clip PSNR vs bf16 15.6 dB | | 6bit | [`6bit/model.safetensors.index.json`](https://huggingface.co/moonbox-ai/hyperflow-h3-flash-MLX/blob/main/6bit/model.safetensors.index.json) | 0.00 GB | `2c048c02c583` | block cosine >= 0.9987, step-0 0.052, clip PSNR vs bf16 15.6 dB | | 4bit | [`4bit/LICENSE`](https://huggingface.co/moonbox-ai/hyperflow-h3-flash-MLX/blob/main/4bit/LICENSE) | 0.00 GB | `59b99642b95e` | below threshold (experimental): block cosine >= 0.9872, step-0 0.159, clip PSNR vs bf16 12.0 dB | | 4bit | [`4bit/NOTICE`](https://huggingface.co/moonbox-ai/hyperflow-h3-flash-MLX/blob/main/4bit/NOTICE) | 0.00 GB | `12be6d1eeaa7` | below threshold (experimental): block cosine >= 0.9872, step-0 0.159, clip PSNR vs bf16 12.0 dB | | 4bit | [`4bit/config.json`](https://huggingface.co/moonbox-ai/hyperflow-h3-flash-MLX/blob/main/4bit/config.json) | 0.00 GB | `e886f2665002` | below threshold (experimental): block cosine >= 0.9872, step-0 0.159, clip PSNR vs bf16 12.0 dB | | 4bit | [`4bit/model-00001-of-00002.safetensors`](https://huggingface.co/moonbox-ai/hyperflow-h3-flash-MLX/blob/main/4bit/model-00001-of-00002.safetensors) | 4.30 GB | `298baedf8c62` | below threshold (experimental): block cosine >= 0.9872, step-0 0.159, clip PSNR vs bf16 12.0 dB | | 4bit | [`4bit/model-00002-of-00002.safetensors`](https://huggingface.co/moonbox-ai/hyperflow-h3-flash-MLX/blob/main/4bit/model-00002-of-00002.safetensors) | 3.62 GB | `e336e68a2ac7` | below threshold (experimental): block cosine >= 0.9872, step-0 0.159, clip PSNR vs bf16 12.0 dB | | 4bit | [`4bit/model.safetensors.index.json`](https://huggingface.co/moonbox-ai/hyperflow-h3-flash-MLX/blob/main/4bit/model.safetensors.index.json) | 0.00 GB | `31551aa23d44` | below threshold (experimental): block cosine >= 0.9872, step-0 0.159, clip PSNR vs bf16 12.0 dB | ## How to run These folders hold the transformer only (`fl2va`: text and first/last-keyframe to video). The text encoder (Qwen3-VL) and the video and audio VAEs are the base [MiniMax-H3](https://huggingface.co/MiniMaxAI/MiniMax-H3) ones. Load a folder with `mlx_model.py` from the Moonbox lab (`lab/zoo/hyperflow-h3-flash/`), which ports the publisher's `hyperflow_h3_flash_transformer.py` to MLX. Sample with the publisher's 6-step HyperFlow schedule at CFG 1. **Where the weights come from.** The publisher released no bf16 weights, only int8 ("convrot") and GGUF. These builds start from `fl2va_int8_convrot`: the int8 weights are dequantized and their Hadamard rotation undone (exact), then stored as bf16 or quantized by MLX (affine, group size 64; attention and feed-forward linears only, everything else as in `bf16/`). So `bf16/` is the int8 model dequantized, not a better-than-int8 model. There is no fp16 build: the residual stream reaches 2.4e5, beyond fp16's range. **How they were checked.** Block by block against the PyTorch model (each block fed the same input; a build passes when every block's cosine is at least 0.995 and the first step's video velocity is within rel-L2 0.10 of the reference; the publisher's own int8 runtime is at 0.022), then a real clip (768x448, 124 frames, same prompt and noise) decoded with the base VAE and compared with `bf16/`: | Precision | Size | Worst block cosine | Step-0 video rel-L2 | Clip PSNR vs bf16 | Status | |---|---|---|---|---|---| | `bf16/` | 27.6 GB | 0.9992 | - | reference | passes | | `8bit/` | 14.7 GB | 0.9991 | 0.037 | 18.9 dB | passes; nearly the same clip as bf16 | | `6bit/` | 11.3 GB | 0.9987 | 0.052 | 15.6 dB | passes; same composition, small details drift | | `4bit/` | 7.9 GB | 0.9872 | 0.159 | 12.0 dB | **below threshold, experimental**: follows the prompt, different scene | On an Apple M5, a 768x448 124-frame clip takes about 100 to 120 s per step at every precision: the smaller builds save memory, not time. `bf16/` needs more than 24 GB of memory (it streams on a 24 GB Mac). ## How these were made From [HyperFlow H3 Flash](https://huggingface.co/VideoRebirthAI/hyperflow-h3-flash) at revision `c8f74e481b`: the original weights loaded in MLX and stored as bf16, or quantized with MLX's affine quantization (`8bit`, `6bit`, `4bit`). Every build was checked against the original before upload; the `sha256` column above is what the files must hash to. ## License MiniMax H3 Community License (derivative; code Apache-2.0). These files are a derivative of the original model and carry its license: it is copied in this repository, and it governs your use of these files. The original model card follows unchanged. --- # Original model card # HyperFlow H3 Flash (14B) > By downloading or using these weights, you accept the [MiniMax H3 Community License Agreement](LICENSE). The Agreement restricts territory (not licensed in the EU, UK, South Korea, or the US without prior authorization from MiniMax) and includes an Acceptable Use Policy. See [License](#license). This repository is not an official MiniMax product. HyperFlow H3 Flash is [Video Rebirth](https://www.videorebirth.com/)'s compressed, few-step version of [MiniMax-H3](https://huggingface.co/MiniMaxAI/MiniMax-H3). It generates video and synchronized stereo audio together. **Showcase:** See [HyperFlow H3 Flash generated video and audio examples](https://www.videorebirth.com/lp/hyperflow-flash). - **Output:** a 5.2 to 15 s video at 24 fps (1344×768 by default) with a 32 kHz stereo soundtrack. - **Sampling:** 4, 6, or 8 steps without classifier-free guidance (CFG). The default is 6 steps. - **Speed (5.2 s clip, 6 steps):** 8.7 s on 4× B200, 36 s on 1× H200, and 92 s on an RTX 5090. - **Real time on 4× Blackwell GPUs:** [NVIDIA SOL-H3](https://github.com/NVlabs/Sana/tree/sol-engine/models/minimax_h3/HyperFlow-Flash) runs HyperFlow H3 Flash in real time on 4× B-series GPUs. SOL-H3 is our inference-acceleration partner and supports this model from day 0. - **Model size:** 13.7B (`fl2va`) or 13.9B (`ref2va`) parameters, less than half of the ~31B MiniMax-H3 transformer. - **Minimum footprint:** `Q4_K_M` is **9.1 GB** (`Q8_0` is **14.9 GB**). It runs on 24 GB and 32 GB GPUs in PCs with 16 GB of system RAM. 16 GB GPUs are not measured yet. Code, setup guides, and ComfyUI workflows are in [`Video-Rebirth/hyperflow-h3-flash`](https://github.com/Video-Rebirth/hyperflow-h3-flash). For the 8-step LoRA on the full-size MiniMax-H3 transformer, see [`VideoRebirthAI/hyperflow`](https://huggingface.co/VideoRebirthAI/hyperflow) ([GitHub](https://github.com/Video-Rebirth/hyperflow)). ### Supported Tasks | Task | Input | Hub partition | ComfyUI template | GGUF support | ComfyUI INT8 support | Python INT8 support | |---|---|---|---|---|---|---| | `t2va` | Text prompt | `fl2va_*` | `hyperflow_t2v` | Yes | Yes | Yes | | `fl2va` | Prompt + first keyframe, or first and last keyframes | `fl2va_*` | `hyperflow_i2v`, `hyperflow_flf2v` | Yes | Yes | Yes | | `ref2va` | Prompt + up to 12 references | `ref2va_*` | `hyperflow_ref2v` | Images only | Images only | Images, videos, and audio | Each ComfyUI template also comes as `*_int8` with the INT8 safetensors. --- ## Choose a Weight Format **Decision rule:** In ComfyUI on 24 GB+ RTX GPUs, use the **INT8 safetensors** (`*_int8_convrot_comfyui/`; 16 GB+ of system RAM; a PyTorch built for CUDA 13.0 or newer, or `--enable-triton-backend`). Use **GGUF** on smaller GPUs and in stable-diffusion.cpp or Unsloth Studio. Use the **INT8 convrot** Python package on data-center GPUs, or on 24 GB+ RTX GPUs with at least 69 GiB of system RAM. | Feature | GGUF | INT8 convrot | |---|---|---| | **Hub folders** | `fl2va_gguf/`, `ref2va_gguf/` | `fl2va_int8_convrot/`, `ref2va_int8_convrot/`; single-file ComfyUI copies in `fl2va_int8_convrot_comfyui/`, `ref2va_int8_convrot_comfyui/` | | **Precision & size** | `Q3_K_M` to `Q8_0` (7.2–15.2 GB) | W8A8 INT8 + low-rank (~16 GB) | | **Runtime** | ComfyUI, Unsloth Studio, `stable-diffusion.cpp` | [`hyperflow-h3-flash`](https://github.com/Video-Rebirth/hyperflow-h3-flash) CLI and `diffusers`; ComfyUI (`*_comfyui/` files) | | **Target GPU** | Consumer GPUs; measured on **24 GB and 32 GB** RTX GPUs (16 GB GPUs not measured yet) | **H100 / H200 / B200 / B300** (1–8 GPUs), or **24 GB+ RTX GPUs** | | **System RAM** | **16 GB+** | **16 GB+** in ComfyUI. Python package: **~16 GiB** without offload; **≥ 69 GiB** (`fp8` text encoder) or **≥ 91 GiB** (`bf16`) with offload | | **`ref2va` inputs** | Images | Images, videos, and audio | --- ## Repository Layout and Companion Files ```text fl2va_int8_convrot/ config.json, diffusion_pytorch_model-0000{1..3}-of-00003.safetensors (+ index), model code ref2va_int8_convrot/ config.json, diffusion_pytorch_model-0000{1..4}-of-00004.safetensors (+ index), model code fl2va_int8_convrot_comfyui/ minimax_h3_fl2va_hyperflow_flash_14b-int8_convrot.safetensors (ComfyUI, 16.0 GB) ref2va_int8_convrot_comfyui/ minimax_h3_ref2va_hyperflow_flash_14b-int8_convrot.safetensors (ComfyUI, 16.4 GB) fl2va_gguf/ minimax_h3_fl2va_hyperflow_flash_14b-.gguf (6 quant levels) ref2va_gguf/ minimax_h3_ref2va_hyperflow_flash_14b-.gguf (6 quant levels) ``` This repository stores only the compressed transformers (`transformer` for `fl2va`, `transformer_ref` for `ref2va`). Each runtime loads the shared text encoder, video VAE, audio VAE, tokenizer, and processor from their upstream repositories: | Runtime | Companion text encoder and VAEs | |---|---| | **`hyperflow-h3-flash` (Python)** | Downloads automatically from [`MiniMaxAI/MiniMax-H3`](https://huggingface.co/MiniMaxAI/MiniMax-H3), or from [`Qwen/Qwen3-VL-32B-Instruct-FP8`](https://huggingface.co/Qwen/Qwen3-VL-32B-Instruct-FP8) with `--text-encoder-precision fp8`. Never downloads the 62 GB base transformer. | | **ComfyUI & stable-diffusion.cpp** | [`Comfy-Org/MiniMax-H3`](https://huggingface.co/Comfy-Org/MiniMax-H3): `text_encoders/qwen3vl_32b_minimax_h3_*.safetensors` (`nvfp4_awq` 15.7 GB, `int8_convrot` 27.1 GB, or `bf16` 51.5 GB), `vae/minimax_h3_video_vae_fp16.safetensors`, `vae/minimax_h3_audio_vae_fp32.safetensors` | | **Unsloth Studio** | Downloads automatically from [`unsloth/MiniMax-H3-GGUF`](https://huggingface.co/unsloth/MiniMax-H3-GGUF) | --- ## GGUF (ComfyUI, Unsloth Studio, stable-diffusion.cpp) | Quant | `fl2va_gguf/` | `ref2va_gguf/` | Recipe | When to use | |---|---:|---:|---|---| | **`Q4_K_M`** | **9.1 GB** | **9.2 GB** | `Q4_K` (lifted layers `Q6_K`) | **Recommended GGUF quant** | | `Q8_0` | 14.9 GB | 15.2 GB | `Q8_0` | Closest to full precision when VRAM and RAM fit | | `Q6_K` | 11.6 GB | 11.8 GB | `Q6_K` | High quality, smaller than `Q8_0` | | `Q5_K_M` | 10.3 GB | 10.5 GB | `Q5_K` (lifted layers `Q6_K`) | Balanced intermediate quant | | `Q4_K_S` | 8.0 GB | 8.1 GB | `Q4_K` | Compact 4-bit quant | | `Q3_K_M` | 7.2 GB | 7.4 GB | `Q3_K` (lifted layers `Q5_K`) | Smallest footprint | Full setup instructions are in [`integrations/README.md`](https://github.com/Video-Rebirth/hyperflow-h3-flash/blob/main/integrations/README.md). Summary: - **ComfyUI:** 1. Clone [ComfyUI-GGUF](https://github.com/city96/ComfyUI-GGUF) and [ComfyUI-HyperFlow-Flash](https://github.com/Video-Rebirth/ComfyUI-HyperFlow-Flash) into `ComfyUI/custom_nodes/`. 2. Put the `.gguf` file in `models/diffusion_models/` and download the 15.7 GB `qwen3vl_32b_minimax_h3_nvfp4_awq` text encoder. 3. On 16 GB or 32 GB RAM PCs, start ComfyUI with `python main.py --fast-disk`. 4. Open **Workflow > Browse Templates > ComfyUI-HyperFlow-Flash** and select `hyperflow_t2v`, `hyperflow_i2v`, `hyperflow_flf2v`, or `hyperflow_ref2v`. 5. On 24 GB+ GPUs, skip ComfyUI-GGUF and use the INT8 safetensors from `fl2va_int8_convrot_comfyui/` or `ref2va_int8_convrot_comfyui/` with the `*_int8` templates; see [INT8 convrot in ComfyUI](#int8-convrot-in-comfyui). - **Unsloth Studio:** Point `SD_CLI_PATH` at the patched `sd-cli` binary (`export SD_CLI_PATH=/path/to/stable-diffusion.cpp/build/bin/sd-cli`), run `unsloth studio`, and load `VideoRebirthAI/hyperflow-h3-flash` (`fl2va_gguf/` or `ref2va_gguf/`). Studio downloads the companion files and runs the 6-step schedule at `CFG = 1`. - **stable-diffusion.cpp:** Apply [`integrations/stable-diffusion.cpp/hyperflow-two-time.patch`](https://github.com/Video-Rebirth/hyperflow-h3-flash/tree/main/integrations/stable-diffusion.cpp) to upstream commit `3be2378`, build, and run: ```bash sd-cli -M vid_gen \ --diffusion-model minimax_h3_fl2va_hyperflow_flash_14b-Q4_K_M.gguf \ --llm qwen3vl_32b_minimax_h3_bf16.safetensors \ --vae minimax_h3_video_vae_fp16.safetensors \ --audio-vae minimax_h3_audio_vae_fp32.safetensors \ --sampling-method euler --cfg-scale 1.0 --steps 6 \ -W 1344 -H 768 --video-frames 124 --fps 24 -s 42 \ -p "A chef slides a steaming bowl of ramen across a wooden counter; rain taps on the window." \ -o output.webm ``` Add `-i first.png` (and `--end-img last.png`) for keyframes. Use `minimax_h3_ref2va_...` with `--ref-image a.png --ref-image b.png` for reference images. Add `--offload-to-cpu` on smaller GPUs. --- ## INT8 convrot (`hyperflow-h3-flash` & `diffusers`) ### Install ```bash pip install git+https://github.com/Video-Rebirth/hyperflow-h3-flash pip install "hyperflow-h3-flash[hopper] @ git+https://github.com/Video-Rebirth/hyperflow-h3-flash" # H100 / H200: FlashAttention-3 pip install "hyperflow-h3-flash[fp8] @ git+https://github.com/Video-Rebirth/hyperflow-h3-flash" # --text-encoder-precision fp8 ``` - **Requirements:** Python 3.10+, PyTorch 2.6+ with CUDA and Triton (`pip install triton-windows` on native Windows), an Ampere or newer NVIDIA GPU, and `diffusers >= 0.40`. Multi-GPU (`--gpus` > 1) requires Linux or WSL2. - **First run:** Downloads ~90 GB (~68 GB with `--text-encoder-precision fp8`), covering the text encoder, VAEs, and the 16 GB INT8 transformer for the selected task. Triton INT8 kernels compile on first use (~1 min). ### Command Line ```bash # Text to video + audio (t2va) hyperflow-h3-flash --prompt "A chef slides a steaming bowl of ramen across a wooden counter; rain taps on the window." \ --output ramen.mp4 # First keyframe, or first + last keyframe (fl2va) hyperflow-h3-flash --prompt "..." --image first.png --last-image last.png --output clip.mp4 # Reference images, videos, and audio clips in prompt order (ref2va) hyperflow-h3-flash --prompt " walks through the scene of ..." \ --reference person.png --reference scene.png --output clip.mp4 # 15 s clip across 4 GPUs; or fp8 text encoder to save ~22 GiB system RAM when offloading hyperflow-h3-flash --prompt "..." --num-frames 360 --gpus 4 hyperflow-h3-flash --prompt "..." --steps 4 --text-encoder-precision fp8 ``` | Option | Values (default) | Description | |---|---|---| | `--steps` | `4`, `6` (`6`), `8` | `4` for speed, `6` balanced, `8` for quality | | `--num-frames` | `124`–`362` (`124`) | 5.2 to 15 s at 24 fps; rounds up to `17n + 5` | | `--gpus` | `1`, `2`, `4`, `7`, `8`, `auto` | Context and VAE tile parallelism under `torchrun` | | `--offload` | `auto` (`auto`), `none`, `model`, `stream` | `none` needs ≥ 90 GiB VRAM; `model`/`stream` need ≥ 91 GiB RAM (`bf16`) or ≥ 69 GiB (`fp8`) | | `--text-encoder-precision` | `bf16` (`bf16`), `fp8` | `fp8` saves ~22 GiB system RAM when offloading (requires `[fp8]`) | | `--attention` | `auto` (`auto`), `sdpa`, `fa3` | Uses FlashAttention-3 (`fa3`) on Hopper when `kernels` is installed | | `--block-chunk` | `0` (`0`), `16384`, ... | Slice token-wise block ops (`--block-chunk 16384` fits 15 s mixed `ref2va` on 24 GB GPUs) | ### Python API (`load_pipeline`) ```python import torch from diffusers.utils.export_utils import encode_video from hyperflow_h3_flash import load_pipeline pipe = load_pipeline("t2va") # "fl2va": pass image=... (and last_image=...); "ref2va": pass references=[...] out = pipe( prompt="A chef slides a steaming bowl of ramen across a wooden counter; rain taps on the window.", num_frames=124, num_inference_steps=6, # 4, 6, or 8 generator=torch.Generator().manual_seed(0), output=["videos", "audio", "sampling_rate"], ) encode_video( out["videos"][0], fps=24, output_path="ramen.mp4", audio=out["audio"][0], audio_sample_rate=out["sampling_rate"], ) ``` ### Standalone Transformer (`AutoModel`) Each INT8 folder ships `hyperflow_h3_flash_transformer.py` and `hyperflow_h3_flash_int8.py`. `AutoModel` loads the transformer without installing `hyperflow-h3-flash`: ```python import torch from diffusers import AutoModel model = AutoModel.from_pretrained( "VideoRebirthAI/hyperflow-h3-flash", subfolder="fl2va_int8_convrot", # or "ref2va_int8_convrot" trust_remote_code=True, torch_dtype=torch.bfloat16, ) model.pad_lowrank_ranks() # pad low-rank dimensions to multiples of 64 for aligned GEMMs model.to("cuda") # Optional on Hopper GPUs (requires `pip install kernels`): model.set_attention_backend("_flash_3_hub") ``` > Note: The transformer requires `endpoint_timestep` on every forward pass for two-time `(t, r)` conditioning. Use `load_pipeline` or `hyperflow_h3_flash.flash_blocks` to run the full sampling loop. ### INT8 convrot in ComfyUI `fl2va_int8_convrot_comfyui/` and `ref2va_int8_convrot_comfyui/` hold the same INT8 transformers as single safetensors files in ComfyUI's tensor layout: the INT8 linears are ComfyUI `int8_tensorwise` + convrot layers with unchanged INT8 codes and scales, and the low-rank linears stay bf16. 1. Install [ComfyUI-HyperFlow-Flash](https://github.com/Video-Rebirth/ComfyUI-HyperFlow-Flash) 1.1.0 or newer (ComfyUI-GGUF is not needed), put the file in `models/diffusion_models/`, and download the same text encoder and VAEs as for a GGUF. 2. Open `hyperflow_t2v_int8`, `hyperflow_i2v_int8`, `hyperflow_flf2v_int8`, or `hyperflow_ref2v_int8`. **HyperFlow Loader** reads the file; stock loaders do not support the two-time embedder or factorized linear layers. 3. Start ComfyUI with `--enable-triton-backend`, or use a PyTorch built for CUDA 13.0 or newer; ComfyUI's PyTorch INT8 fallback is about 50% slower. See [timings](#comfyui-int8-benchmarks). 4. It runs on PCs with 16 GB of system RAM: measured with 12 GiB left to ComfyUI 0.44.0 on the RTX 5090 and 4090. --- ## Benchmarks and Memory All benchmarks measure end-to-end generation (text encoding, 6-step transformer, and video and audio VAE decode) at **1344×768 and 6 steps**. Clip lengths: `5.2 s` = 124 frames; `15 s` = 362 frames. ### 1. RTX GPUs (`5.2 s / 15 s` total time) | GPU | INT8 (ComfyUI)
`*_comfyui/` file | GGUF `Q4_K_M` (ComfyUI)
≥ 64 GB RAM | GGUF `--fast-disk`
32 GB PC | GGUF `--fast-disk`
16 GB PC | INT8 (`hyperflow-h3-flash`)¹
`--offload stream` | |---|---|---|---|---|---| | **RTX PRO 6000 (96 GB)** | 53 s / 333 s | — | — | — | 61 s / 357 s | | **RTX 5090 (32 GB)** | 83 s / 518 s | 99 s / 575 s | 118 s / 618 s | 130 s / 615 s | 92 s / 551 s | | **RTX 4090 (24 GB)** | 152 s / 747 s | 157 s / 830 s | 151 s / 815 s | 153 s / 812 s | 130 s / 750 s | | **RTX 3090 (24 GB)** | — | 315 s / 1835 s | 318 s / 1869 s | 325 s / 1866 s | 266 s / 1684 s | | *Peak VRAM (5.2 s / 15 s)* | *PRO 6000: 39 / 49 GiB; 5090: 31 GiB; 24 GB: 21 GiB (5.2 s)* | *5090: 28 / 27 GiB; 24 GB: 23 / 22 GiB* | *same as ≥ 64 GB* | *same as ≥ 64 GB* | *PRO 6000: 77 / 86 GiB; others: 12.0–12.5 / 21.8–22.4 GiB* | - **ComfyUI INT8 column:** ComfyUI 0.44.0 with PyTorch 2.13 + CUDA 13.0 and the `nvfp4_awq` text encoder, on separate RunPod pods (188 GB / 60 GB / 31 GB of system RAM on the PRO 6000 / 5090 / 4090), without saving the MP4. On the same pods, `Q4_K_M` took 96 s / 562 s (5090) and 160 s / 834 s (4090), so INT8 is 5–15% faster. With 12 GiB of system RAM left to ComfyUI (a 16 GB PC) and no `--fast-disk`, INT8 took 88 s (5090) and 153 s / 821 s (4090) ([details](https://github.com/Video-Rebirth/hyperflow-h3-flash/blob/main/integrations/README.md#int8-performance)). - **GGUF columns:** Use the 15.7 GB `nvfp4_awq` text encoder. `--fast-disk` streams unresident weights from the OS file page cache instead of pinned RAM, keeping anonymous RSS at ~8–16 GiB. - **¹ `hyperflow-h3-flash` INT8 column:** Requires ≥ 91 GiB system RAM with the `bf16` text encoder, or ~69 GiB with `--text-encoder-precision fp8`. On the RTX PRO 6000, `--offload auto` selects `none` instead: all components stay in VRAM, and the process peaks at 39 GiB of system RAM. **Reference to video (`ref2va`) on one RTX GPU (`5.2 s / 15 s` total time):** | GPU | Python INT8, 2 images | Python INT8, mixed² | GGUF `match`, 2 images | GGUF `max`, 2 images | |---|---|---|---|---| | **RTX 5090 (32 GB)** | 266 s / 914 s | 503 s / 1318 s | 135 s / 660 s | 295 s / 995 s³ | | **RTX 4090 (24 GB)** | 319 s / 1167 s | 630 s / 1702 s⁴ | 194 s / 885 s | 398 s / 1275 s³ | | **RTX 3090 (24 GB)** | 726 s / 2763 s | 1441 s / 4033 s⁴ | 401 s / 2059 s | 885 s / 2995 s³ | - **² Mixed:** One reference image, one 5.2 s reference video with soundtrack, and one audio clip. **³** Start ComfyUI with `--disable-cuda-malloc` for `max` at 15 s. **⁴** Pass `--block-chunk 16384` on 24 GB GPUs for 15 s mixed `ref2va`. On 32 GB / 16 GB PCs with `--fast-disk`, 2-image `ref2v` (`match`) runs in `139 s / 663 s` and `157 s / 684 s` on RTX 5090, `180 s / 866 s` and `178 s / 876 s` on RTX 4090, and `385 s / 2010 s` and `384 s / 2025 s` on RTX 3090. ### 2. Data-Center GPUs (`hyperflow-h3-flash` INT8) | GPUs | `--offload` | 5.2 s (124 frames) | 15 s (362 frames) | Peak VRAM / GPU (5.2 s / 15 s) | System RAM / GPU | |---|---|---|---|---|---| | 1× H200 (141 GB) | `none` | 36 s | 229 s | 80 / 91 GiB | 16 GiB | | 2× H200 (141 GB) | `none` | 24 s | 119 s | — / 71 GiB | 16 GiB | | 4× H200 (141 GB) | `none` | 12.6 s | 66 s | 47 / 59 GiB | 16 GiB | | 4× B200 | `none` | 8.7 s | — | 46 GiB | 16 GiB | The table measures the `hyperflow-h3-flash` package. For real time on 4× B-series GPUs, use [NVIDIA SOL-H3](https://github.com/NVlabs/Sana/tree/sol-engine/models/minimax_h3/HyperFlow-Flash). --- ## Step Schedules and Prompting ### Step Grids Both partitions and both weight formats share three unshifted sigma grids (`video_shift = 12`, `audio_shift = 3`): | Steps | Mode | Raw sigmas | |---:|---|---| | `4` | Speed | `1, 0.681872, 0.205019, 0.036496, 0` | | `6` | Balanced (default) | `1, 0.825217, 0.471725, 0.147401, 0.049626, 0.015517, 0` | | `8` | Quality | `1, 0.931506, 0.839236, 0.703462, 0.5, 0.296538, 0.160764, 0.068494, 0` | ### Prompts - Describe the subject, action, setting, camera movement, and sound in one prompt. Do not use a negative prompt (`CFG = 1.0`). - For `ref2va`, name inputs in prompt order as ``, `