README.md

---
license: other
license_name: minimax-h3-community-license-agreement
license_link: LICENSE
base_model: MiniMaxAI/MiniMax-H3
base_model_relation: adapter
pipeline_tag: image-text-to-video
library_name: minimax-h3
tags:
  - hyperflow-h3
  - lora
  - minimax-h3
  - video-generation
  - audio-video-generation
  - text-to-video
  - image-to-video
  - image-text-to-video
  - text-to-audio-video
  - image-to-audio-video
  - reference-to-audio-video
  - flow-matching
  - distillation
  - self-distillation
  - few-step
---

# HyperFlow for MiniMax-H3

> By downloading or using these weights you accept the [MiniMax H3 Community License Agreement](LICENSE), including
> its territorial scope (not licensed in the EU, UK, South Korea or the US without MiniMax's separate authorization)
> and its Acceptable Use Policy. See [License](#license). Not an official MiniMax product.

HyperFlow is [Video Rebirth](https://www.videorebirth.com/)'s 8-step LoRA for
[MiniMax-H3](https://huggingface.co/MiniMaxAI/MiniMax-H3), obtained by data-free flow self-distillation and running
on the official [diffusers Modular Pipeline](https://huggingface.co/docs/diffusers/main/api/pipelines/minimax_h3).
Diffusers' default 50-point sigma schedule performs 49 model forwards; HyperFlow performs 8. The base weights, VAEs,
conditioner and workflows (`t2va`, `fl2va`, `ref2va`, all video + audio) stay the official ones. This repository
holds the LoRA only; the loader and examples live at
[github.com/Video-Rebirth/hyperflow](https://github.com/Video-Rebirth/hyperflow).

**Showcase.** See [HyperFlow generated video examples and comparisons](https://www.videorebirth.com/lp/hyperflow).

| | |
|---|---|
| Base model | [`MiniMaxAI/MiniMax-H3`](https://huggingface.co/MiniMaxAI/MiniMax-H3) (revision recorded in the file header) |
| Adapter | PEFT LoRA, rank 256 / alpha 256, on attention, feed-forward and both time embedders (316 modules); 2.8 GB |
| Sampling | 8 forward passes on a fixed sigma grid stored in the file (video shift 12, audio shift 3) |
| Workflows | `t2va`, `fl2va` and `ref2va`, one file for all three (`ref2va` loads it onto `transformer_ref/`) |
| Speed-up | about 3x end to end against the 49-NFE Diffusers baseline (about 60 s vs about 175 s per clip on 4x H200) |
| Optional | Ulysses context parallel on up to 4 GPUs; FlashAttention-3; NVIDIA Sol-Attn sparse attention |
| License | [MiniMax H3 Community License Agreement](LICENSE); code on GitHub is Apache-2.0. See [License](#license) |

**Not a generic LoRA.** The file carries keys for a second time embedder that only exists once the HyperFlow loader
has installed it, and the step count comes from the file. Load it with `load_hyperflow_lora` from the
`hyperflow-h3` package, not with diffusers' `load_lora_weights` / `load_lora_adapter`.

## Files

| File | `hyperflow_version` | Notes |
|---|---|---|
| `minimax_h3_hyperflow_8step_v1.0.safetensors` | `1.0` | **default**: what a bare repo id loads. First release |
| `hyperflow.json` | | Manifest: the `default` file and every file's `hyperflow_version` and `sha256` |
| `LICENSE`, `NOTICE` | | MiniMax H3 Community License Agreement and the notice it requires |

A published file name is never reused: pin one with `filename=` (or `--weights-filename`) and it stays what it is.
A bare repo id follows the manifest's `default`, so it picks up new versions as they ship; `revision=` pins a tag or
commit of this repository.

## Usage

```bash
pip install "hyperflow-h3[examples] @ git+https://github.com/Video-Rebirth/hyperflow.git"
```

Python ≥ 3.10, diffusers ≥ 0.40.0 (the first release with the MiniMax-H3 Modular Pipeline and its context parallel
plan), transformers ≥ 4.57 (Qwen3-VL). The `examples` extra adds PyAV for writing the output video.

```python
import torch
from diffusers import ComponentsManager
from diffusers.utils import load_image
from hyperflow_h3 import hyperflow_blocks, load_hyperflow_lora

manager = ComponentsManager()
blocks = hyperflow_blocks("fl2va")                              # official workflow, two blocks swapped
pipe = blocks.init_pipeline("MiniMaxAI/MiniMax-H3", components_manager=manager)
pipe.load_components(dtype=torch.bfloat16)
load_hyperflow_lora(pipe, "videorebirth/hyperflow")  # LoRA + two-time embedder + 8-step grid

# The official single-GPU recipe (auto CPU offload), armed only now: registering a component resets the margin.
# 24 GB is the margin validated on H200; the official recipe's 12 GB starves the denoiser there. See Performance.
manager.enable_auto_cpu_offload(device="cuda", memory_reserve_margin="24GB")

out = pipe(
    prompt="A red fox trotting through a snowy pine forest",
    image=load_image("first.png"),
    num_frames=124,
    generator=torch.Generator().manual_seed(42),
    output=["videos", "audio", "sampling_rate"],
)
```

- Do not pass `num_inference_steps`: the step count and sigma grid come from the weights file; another count raises.
- Every other input (`prompt`, `image`, `last_image`, `references`, `height`, `width`, `num_frames`, `generator`)
  is the official pipeline's.
- Other workflows: `hyperflow_blocks("t2va")` (no `image`) and `hyperflow_blocks("ref2va")` (`references=`; the
  same weights file is loaded onto `transformer_ref`).
- Prompting: MiniMax's hosted H3-Context-IR prompt refinement is not part of the open weights, so prompts follow the
  base model's [prompting guidance](https://huggingface.co/MiniMaxAI/MiniMax-H3#prompting-guidance) as they do in
  the base Diffusers pipeline.

**Pinning and offline use.** `load_hyperflow_lora` takes this repo id, a local directory or a `.safetensors` file.
Manifest and weights are fetched once into the `huggingface_hub` cache and keep working under `HF_HUB_OFFLINE=1`.

```python
load_hyperflow_lora(pipe, "videorebirth/hyperflow", filename="minimax_h3_hyperflow_8step_v1.0.safetensors")
load_hyperflow_lora(pipe, "/weights/hyperflow")  # from `hf download videorebirth/hyperflow --local-dir /weights/hyperflow`
```

**Example commands, several GPUs, Sol-Attn.** The package installs `hyperflow-h3-fl2va` and
`hyperflow-h3-ref2va`; the GitHub repository also has [`examples/`](https://github.com/Video-Rebirth/hyperflow/tree/main/examples)
source-tree launchers. They provide Ulysses sequence parallel over up to 4 GPUs (the degree MiniMax serves the model
with), FlashAttention-3, NVIDIA Sol-Attn and `--baseline` (Diffusers' default 50 sigma points / 49 NFE on the same
seed, for an A/B). Fully offline runs take a local weights file and a local MiniMax-H3 snapshot.

```bash
hyperflow-h3-fl2va --prompt "..." --image first.png            # first frame -> video+audio, up to 4 GPUs
hyperflow-h3-ref2va --prompt "..." --ref subject.png --ref clip.mp4 --ref voice.wav
hyperflow-h3-fl2va --prompt "..." --image first.png --gpus 1   # the official single-GPU recipe
```

## Performance

HyperFlow (8 NFE, 9 sigma points) against the base pipeline at Diffusers' default (49 NFE, 50 sigma points) on the
same clip: `fl2va`, 124 frames, 1344x768, seed 0, dense SDPA attention. Pipeline time covers text encoding, denoising
and decoding; process start-up and weight loading add about 30 s.

| | Base, 49 NFE | HyperFlow, 8 NFE | Speed-up |
|---|---|---|---|
| 4x H200, Ulysses degree 4 | about 175 s | about 60 s | 2.9x |
| 1x H200, auto CPU offload | about 395 s | about 130 s | 3.0x |

The speed-up is below the 49:8 NFE ratio because text encoding and VAE decoding, which HyperFlow leaves unchanged,
now take much of the run. Peak accelerator memory is about 80 GB per card either way (the LoRA adds 2.8 GB). The
single-GPU row uses `memory_reserve_margin="24GB"`, not the official recipe's 12 GB: on a 141 GB H200 a smaller margin
evicts the 10 GB VAE instead of the 62 GB text encoder when the DiT arrives and starves the denoiser. An 80 GB card
is untested.

With a fixed seed a run reproduces itself (audio bit-identical, video PSNR ≈ 43–50 dB, a residue of the VAE decode).
Across GPU counts or attention backends the clip is only visibly similar (PSNR ≈ 27 dB and ≈ 34 dB): sharding and
kernels change the bf16 reduction order. NVIDIA Sol-Attn sparse attention, optional and off by default, is a further
approximation (PSNR ≈ 23 dB against the dense run); check its output before adopting it.

## Quality

HyperFlow is a self-distillation: the base model is the only teacher. Against the base pipeline at 49 NFE, on the
same seeds, four things stand out:

- **More balanced capabilities**
- **Better camera control**
- **Better consistency**
- **Better materials and detail**

<!-- TODO(comparison): side-by-side clips, base 49 NFE vs HyperFlow 8 NFE, same seed, 124 frames at 1344x768.
| Prompt | Base, 49 NFE | HyperFlow, 8 NFE |
|---|---|---|
| ... | ... | ... |
-->

Judge on your own prompts: `--baseline` in the example scripts renders both pipelines on one seed.

## How it works

Three additions to the official pipeline, all reversible (`disable_hyperflow`):

- **Two-time conditioning.** The LoRA was trained with both the current time `t` and the step's endpoint `r` (a
  flow-map formulation). A `TwoTimeEmbedder` wraps the base `time_embedder`, adds a LoRA'd copy for `r`, and blends
  the two embeddings with a fixed gate stored in the file. Conditioning rows (`fl2va` keyframes, `ref2va`
  references) keep `r = t`, so they stay pinned exactly as in the official denoiser.
- **8-step schedule.** The official timestep block is replaced by the trained sigma grid (video and audio shifts
  included); the denoising loop hands each step's endpoints to the embedder. Nothing else in the workflow changes.
- **One file, three workflows.** `t2va` and `fl2va` share `transformer/`. `ref2va` runs the same file on
  `transformer_ref/`, which works because the adapter never touches `adaln_proj`, the carrier of the reference
  conditioning.

**File format.** A plain `safetensors` file: PEFT-style keys (`transformer.<module>.lora_A.weight`; bf16 for the
DiT blocks, fp32 for the two time embedders) plus a self-describing header (`hyperflow_sigmas`, `hyperflow_gate`,
`lora_rank`, `lora_alpha`, `base_model`, `base_model_revision`, …):

```python
from hyperflow_h3 import read_metadata

meta = read_metadata("minimax_h3_hyperflow_8step_v1.0.safetensors")  # header only, no tensors loaded
meta.base_model_revision, meta.sigmas, meta.gate
```

## Intended use and limitations

- A drop-in speed-up for MiniMax-H3 inference on diffusers: same inputs, same outputs (video + stereo audio), about 3x
  faster end to end. It is a distilled few-step sampler, so compare against the base Diffusers pipeline on your own
  prompts before adopting it (`--baseline` in the example scripts runs both on the same seed).
- Prompt following, languages, biases and failure modes are the base model's, which the distillation is designed to
  keep ([Quality](#quality)); see the [MiniMax-H3 model card](https://huggingface.co/MiniMaxAI/MiniMax-H3).
- Training code is not part of this release.
- Use is bound by the license below, including its territorial scope and its Acceptable Use Policy.

## License

The LoRA weights are a Model Derivative of MiniMax-H3 and are distributed under the
[MiniMax H3 Community License Agreement](LICENSE), the base model's license, with no additional terms. By
downloading or using them you accept that Agreement. In particular:

- **Territory.** The license is granted worldwide **excluding the European Union, the United Kingdom, the Republic of
  Korea and the United States of America**. Individuals and organizations there must obtain MiniMax's authorization
  before downloading ([application form](https://platform.minimax.io/h3-license), open to individuals as well;
  [Q&A](https://huggingface.co/MiniMaxAI/MiniMax-H3/blob/main/docs/QA-about-License.md)).
- **Redistribution.** Pass on a copy of the Agreement and the [`NOTICE`](NOTICE) file, mark modified files, and do not
  impose additional or different terms (Section III).
- **Disclosure.** Content generated with these weights and posted publicly must be clearly disclosed as AI-generated
  (Acceptable Use Policy, item 12). Naming "MiniMax H3" is encouraged, not required.
- **Commercial use.** Products or services with more than 20 million US dollars yearly revenue need MiniMax's prior
  written authorization (api@minimax.io). Products and services built with the weights must display "MiniMax H3" on
  their user interface (Section IV.2); this applies to what you build, not to finished videos published on
  third-party platforms.
- **Hosted services.** If you serve generations to third parties, you must implement the safeguards in Section V.5
  and bind your users to the same use restrictions (Section V.2).
- **Use restrictions.** Section V and the Acceptable Use Policy (Exhibit A) apply to the weights and to their outputs;
  outputs may not be used to improve other AI models.
- **Upstream text.** [`LICENSE`](LICENSE) is the August 2, 2026 text. MiniMax may update the Acceptable Use Policy;
  the version in the [upstream repository](https://huggingface.co/MiniMaxAI/MiniMax-H3/blob/main/LICENSE) governs.

The loader and example scripts on [GitHub](https://github.com/Video-Rebirth/hyperflow) are separate software under
the Apache License 2.0.

HyperFlow is developed by Video Rebirth. It is not an official MiniMax product and is not affiliated with or
endorsed by MiniMax. Powered by MiniMax H3.

## Acknowledgements

- **[MiniMax-H3](https://huggingface.co/MiniMaxAI/MiniMax-H3)** ([GitHub](https://github.com/MiniMax-AI/MiniMax-H3)): the base model, VAEs, conditioner and official workflows.
- **AnyFlow** ([GitHub](https://github.com/NVlabs/AnyFlow); Gu et al., 2026): the flow-map formulation behind the two-time `(t, r)` conditioning.
- **[diffusers](https://github.com/huggingface/diffusers)**: the Modular Pipeline and context parallel plan the loader builds on.
- **FlashAttention-3** and **Sol-Attn** ([GitHub](https://github.com/NVlabs/Sana/tree/main/techniques/sparse_backends); Li et al., 2026): optional attention kernels.

Thanks to their authors.