minimax-h3-30series

KO | EN

gitlite — search

#c #sql #kubernetes #video #reactjs #proxy #pytorch #vue #generative-ai #golang

minimax-h3-30series

(★ 9)

For RTX 3000 series cards.

File Explorer

ZIP Download

- - README.md
- - README.md
- build-workflows.py
- doctor.sh
- fetch-models.sh
- manifest.sh
- smoke-test.py
- tune.py
- 01-text-to-video-12gb.json
- 01-text-to-video-24gb.json
- 02-upscale-12gb.json
- 02-upscale-24gb.json
.gitignore
CREDITS.md
LICENSE
README.md

# Use via CDN

jsDelivr

jsDelivr serves any public GitHub repository as a CDN with zero setup. Pick a version and a file to get a ready-to-paste link and snippet.

Version

File

Link

Example

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

MiniMax H3 generates video **and synchronised audio in one pass**. Running it
normally means a multi-GPU box — the model is 19.5 GiB, its text encoder is
another 25.3 GiB, and that does not fit on one 24 GB card, let alone a 12 GB one.

It fits anyway, by keeping part of the model in VRAM and streaming the rest from
system RAM. This repo is a workflow built for that, plus the scripts to set it up
and work out the one number it depends on. `tune.py` probes your actual card and
computes that number for it — it does not assume 24 GB.

**Tested on two cards, in the same machine:**

- **RTX 3090 (24 GB)** — 5 s at 1344×768, video and audio, in **4:35**
- **RTX 3060 (12 GB)** — 10 s at 864×480 (480p), video and audio, in **6:47**

So this is not a 24 GB-only proposition. A 12 GB card renders full-length clips
with sound; it renders them at 480p instead of 1344×768. What card you have mostly
decides your *resolution*, not whether you can run the model — see
[RTX 30-series: what differs by card](#rtx-30-series-what-differs-by-card) for the
rest of the line, which is still formula-only.

---

## Start here

**Pick the workflow file for your card. It is already tuned — drag it into
ComfyUI and press Queue.** No scripts to run, nothing to configure.

| your GPU | drag in this file | you get |
|---|---|---|
| **24 GB** (3090) | `workflows/01-text-to-video-24gb.json` | 1344×768, 5 s, ~4:35 |
| **12 GB** (3060) | `workflows/01-text-to-video-12gb.json` | 864×480, 10 s, ~6:47 |

Both were measured on those exact cards. Three things have to be in place first.

### 1. Custom node packs

```bash
cd ComfyUI/custom_nodes
git clone https://github.com/pollockjj/ComfyUI-MultiGPU
git clone https://github.com/kijai/ComfyUI-KJNodes
git clone https://github.com/Larryvrh/ComfyUI-MiniMax-H3-Turbo
cd .. && for d in custom_nodes/*/requirements.txt; do pip install -r "$d"; done
pip install sageattention
```

Restart ComfyUI. Missing packs show up as red "missing node type" boxes with no
useful error, and **ComfyUI-MultiGPU is the one that matters most** — both
loaders in the workflow come from it.

Only if you also want the upscaler (workflow 02):

```bash
git clone https://github.com/numz/ComfyUI-SeedVR2_VideoUpscaler
git clone https://github.com/Kosinkadink/ComfyUI-VideoHelperSuite
```

### 2. Model files — ~51 GiB

Same files whatever card you have. Put each one in the folder shown:

| file | size | into `ComfyUI/models/` |
|---|---|---|
| `minimax_h3_fl2va_pruned_int8_convrot.safetensors` | 19.5 GiB | `diffusion_models/` |
| `qwen3vl_32b_minimax_h3_int8_convrot.safetensors` | 25.3 GiB | `text_encoders/` |
| `minimax_h3_video_vae_fp16.safetensors` | 4.9 GiB | `vae/` |
| `minimax_h3_audio_vae_fp32.safetensors` | 578 MiB | `vae/` |
| `minimax_h3_turbo_4step_ema_ckpt850.safetensors` | 744 MiB | `loras/` |

The first four are in [Comfy-Org/MiniMax-H3](https://huggingface.co/Comfy-Org/MiniMax-H3),
the LoRA is in [larryvrh/MiniMax-H3-Turbo-Lora](https://huggingface.co/larryvrh/MiniMax-H3-Turbo-Lora).
Download them however you like — or let the script do it, resumable and
byte-checked, which matters at this size:

```bash
./scripts/fetch-models.sh                  # ~51 GiB
./scripts/fetch-models.sh --with-upscale   # +8.7 GiB, adds workflow 02
```

### 3. Enough RAM

**64 GB.** This is the requirement people miss — the text encoder is 25.3 GiB and
lives in system RAM for the entire run, whatever GPU you have. A smaller card
needs *more* RAM, not less. 32 GB will page constantly; 16 GB will not work.

### Then

Drag your card's file onto the ComfyUI canvas, type a prompt into the
**Prompt + AV latent** node, press Queue. Every clip has sound, so
**describe the sound in your prompt** or you get silence.

---

## Optional scripts

None of these are required — the presets work without them.

```bash
./scripts/doctor.sh          # checks GPU, RAM, disk, node packs, model files
python scripts/tune.py       # re-tune if you change resolution, length, or GPU
python scripts/smoke-test.py # prove it runs, without opening the browser
```

`scripts/build-workflows.py` regenerates the workflow files from your running
ComfyUI's node definitions. You do not need it unless a node pack updated and
something loads wrong.

---

## Why one card works at all

ComfyUI-MultiGPU is **not** tensor parallelism. All compute happens on `cuda:0`;
any other device is a *weight shelf*, fetched over PCIe as each layer is needed.

That is what makes a single card viable. System RAM can be that shelf instead of
another GPU. You are not splitting the math — you were never splitting the math —
you are just choosing where the weights sit when they are not in use.

## RAM is the constraint, not VRAM

This is what decides whether you can run this at all.

The text encoder is **25.3 GiB**. It cannot fit on a 24 GB card alongside
anything else, so it lives in system RAM for the whole run. On top of that sits
whatever share of the 19.5 GiB diffusion model does not fit in VRAM.

| your RAM | verdict |
|---|---|
| **64 GB** | works — measured ~37 GB working set on a 3090, ~46 GB on a 3060, no swapping |
| 48 GB | should work with nothing else running (**untested**) |
| 32 GB | the encoder alone is 25.3 GiB; expect constant paging (**untested, likely painful**) |
| 16 GB | no |

Note the direction of that first row: the **smaller** card needed **more** RAM, because
whatever does not fit in VRAM has to live somewhere. Buying a cheaper GPU does not
reduce this requirement, it raises it.

`doctor.sh` computes this for your machine and says so plainly.

## RTX 30-series: what differs by card

`tune.py` reads your actual VRAM off `nvidia-smi` rather than assuming 24 GB, so
every card gets an allocation out of the same formula. Whether that allocation is
*good advice* is a different question, and the honest answer depends on how far
your card is from the one it was fitted on.

| card | VRAM | 608×352 draft | 864×480 (480p) | 1344×768 full res |
|---|---|---|---|---|
| 3090 / 3090 Ti | 24 GB | **measured** | — | **measured** — 4:35 @ 5 s |
| 3060 | 12 GB | should be fine | **measured** — 6:47 @ 10 s | outside the formula's fit |
| 3080 Ti | 12 GB | should be fine | should be fine | outside the formula's fit |
| 3080 | 10 GB | should be fine | likely, untested | outside the formula's fit |
| 3070 / 3070 Ti / 3060 Ti | 8 GB | should be fine | likely, untested | outside the formula's fit |

**480p is the shape that makes a 12 GB card work.** A 3060 renders a full
10-second clip with synchronised audio at 864×480 in 6:47, holding 5 GiB of DiT
resident and streaming the other 14.5 GiB from RAM. Both sides must stay multiples
of 32 — 864×480 is the closest you get to 16:9 at 480p.

**The formula survived a real extrapolation test.** It was fitted on a 3090 at
1344×768, then asked to predict a card of half the VRAM at a resolution it had
never seen. It returned 5 GiB resident, and that config ran on the first attempt
with no OOM — on a card too small for the allocator to hide slack in. That is
meaningfully better evidence than the two same-card data points it was built from.

**Why the full-res column still says "outside the fit."**

The activation reserve is fitted to two runs on a 3090 that *completed* — 13 GiB
resident at 124 frames, 8 GiB at 243. That tells us how much headroom was
**sufficient**. It does not tell us how much was **necessary**, and those are very
different things. We could not measure actual activation demand at all: ComfyUI's
allocator expands to fill free VRAM, so a 13 GiB-resident run and an 8 GiB-resident
run both peaked at ~22.7 GiB. Peak-used measures the allocator's appetite, not the
run's need.

So when the formula extrapolates down to a 12 GB card at full resolution and says
"2 GiB resident," that number inherits an upper-bound reserve as if it were a real
requirement. Publishing it as a prediction would be false precision in the
pessimistic direction, which is why that column says what it says.

**One genuine demand measurement exists**, and it came out of a crash. Running the
3090's 13 GiB allocation on a 12 GB card by mistake produced this:

```
video_patch_proj  →  Requested: 4.27 GiB   (1344×768, 124 frames)
```

That is a single activation tensor, measured, not inferred — a small card is too
tight for the allocator to mask real demand, so the failure reported a true number
where the 3090 never had to. It scales roughly with pixels × frames, which puts it
near 3.4 GiB at 864×480/243 — comfortably inside the 6.2 GiB the formula reserved
there, and consistent with that run completing. It is one tensor rather than the
whole activation footprint, so it bounds the answer from below rather than
settling it.

`tune.py` still refuses to write an allocation below 4 GiB without `--force`. Read
that as "nobody has timed this," not "this is known to fail."

**Draft size is where a small card is comfortable.** At 608×352/39 frames the
reserve drops to its 1.5 GiB floor, the formula stops extrapolating hard, and even
an 8 GB card holds ~7 GiB resident. 480p sits between that and full res, and is
the shape actually measured on a 3060.

**RAM does not get easier on a smaller card — it gets harder.** The 25.3 GiB text
encoder sits in system RAM whatever GPU you own, and less resident DiT means more
of *that* spills to RAM too. The measured 3060 run at 480p/10 s carried a ~46 GiB
working set against the 3090's ~37 GiB at full res, on the same machine. 64 GB RAM
is not a 3090 requirement; if anything it binds harder further down the line.

**All of which may be the wrong path for a small card entirely.** Everything above
assumes the INT8 19.5 GiB DiT and 25.3 GiB encoder, streamed whole. Quantized GGUF
builds shrink the files instead — a ~8.9 GiB DiT plausibly sits resident on a 12 GB
card with no streaming and no 64 GB RAM requirement, which would make this whole
section moot below 24 GB. That is untested here and is the single most useful thing
anyone could test next: see
[`experimental/gguf-quants/`](experimental/gguf-quants/README.md).

If you run a 3070, 3080, or 3080 Ti and it works — or doesn't — that is a genuinely
valuable data point; those rows are still formula-only.

## What you need

- One NVIDIA GPU, **12 GB or more** (tested: RTX 3090 at 1344×768, RTX 3060 at 480p)
- **64 GB RAM** (see above — this matters more than the GPU)
- **~55 GB free disk** (~64 GB with the optional upscaler)
- ComfyUI **0.30.0+**, Python 3.12, CUDA-capable PyTorch

## If you do not have ComfyUI yet

[Start here](#start-here) assumes ComfyUI is already installed and running. If
not:

```bash
git clone https://github.com/comfyanonymous/ComfyUI
cd ComfyUI
python3 -m venv venv && source venv/bin/activate
pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu128
pip install -r requirements.txt
python main.py 2>&1 | tee -a comfyui.log
```

That last line keeps a log. Without it ComfyUI's output only exists in the
terminal you launched it from, which is annoying the first time something fails.

### Downloading the weights

`fetch-models.sh` is resumable and safe to Ctrl-C: completed files are skipped by
exact byte count, partial files continue where they stopped, and network drops
retry with backoff. At 51 GiB that matters.

```bash
export COMFYUI=/path/to/ComfyUI
./scripts/fetch-models.sh --check            # status only, instant, no network
./scripts/fetch-models.sh                    # ~51 GiB
./scripts/fetch-models.sh --with-upscale     # +8.7 GiB, adds workflow 02
```

**Log in first** (`hf auth login`) — anonymous downloads are rate-limited. And
**do not set `HF_HOME`** to move the cache; it moves the token lookup too and
silently drops you to anonymous. Move `HF_XET_CACHE` instead, which is what the
script does.

## The one number that matters

The loader nodes carry a DisTorch2 allocation string:

```
cuda:0,13gb;cpu,*
```

That reads: *put 13 GiB of this model on cuda:0, spill the rest to system RAM.*
It is a **per-model quota consumed in order**, not a device capacity — worth
knowing, because the syntax suggests the opposite.

Too high and sampling dies with an OOM. Too low and the GPU waits on PCIe.
`tune.py` picks it from your VRAM, your desktop's share of it, and the shape you
are rendering. Longer clips need *less* resident weight, because activations grow
with frame count:

```bash
python scripts/tune.py --frames 243     # 10s -> cuda:0,8gb
python scripts/tune.py --vram-alloc 10  # override if you OOM
```

**How the number is derived.** It is fitted to two configurations measured here
that ran to completion, not to an estimate of demand. Peak VRAM is useless for
this: ComfyUI's allocator expands to fill whatever is free, so runs holding 13 GiB
and 8 GiB of weights both peaked at ~22.7 GiB. Peak-used tells you what the
allocator took, not what the run needed.

## Measured

Ryzen 9 9900X, 64 GB DDR5-6000, PCIe 4.0 x16, Ubuntu, ComfyUI 0.31.0, torch
2.13.0+cu130, driver 595.84. Times are ComfyUI's own `Prompt executed in`
figure, via `scripts/smoke-test.py`. Both cards were run in the same machine.

**RTX 3090, 24 GB** (250 W cap):

| shape | frames | resident | wall |
|---|---|---|---|
| 608×352 | 39 (1.6 s) | 13 GiB | 2:12 (cold model load) |
| 1344×768 | 124 (5 s) | 13 GiB | **4:35** |
| 1344×768 | 243 (10 s) | 8 GiB | **9:31** |

**RTX 3060, 12 GB** (11.6 GiB usable, ~0.5 GiB to the desktop):

| shape | frames | resident | wall |
|---|---|---|---|
| 864×480 | 243 (10 s) | 5 GiB | **6:47** |

Video and audio both landed at exactly 10.125 s. Note the 3060 is *not* simply
"slower" — 480p/10 s on the 12 GB card beat 1344×768/10 s on the 24 GB card,
because it is doing a third of the pixel-frames. Compare shapes, not cards.

Sampling holds ~35 s per step at 1344×768/124 frames after the first, with the
GPU at 100% and 249 W — compute-bound, not starved by PCIe. That was measured on
PCIe 4.0 x16 with 13 GiB resident; on a PCIe 3.0 board, or with less resident and
so more streamed per step, the transfer has half the bandwidth and may become the
limit instead. Untested here.

Cost grows faster than clip length, which is why the 10-second clip is more than
twice the 5-second one.

**Work at 608×352 first.** A draft is a ~1-minute loop where full resolution is
closer to five. Get the prompt and seed right cheaply, then render big.

### Untested

15-second clips (362 frames) at full resolution — the tuner estimates only ~2 GiB
could stay resident, meaning nearly the whole model would stream every step, and
it refuses without `--force`. Full resolution (1344×768) on a 12 GB card is also
untested and the tuner refuses it without `--force`; 480p is the shape that
works there. Also untested: image-to-video, the 20-step non-Turbo path, any GPU
other than the 3090 and 3060, any RAM size other than 64 GB, and any PCIe
generation other than 4.0 x16.

## Upscaling to 1080p

`workflows/02-upscale-24gb.json` (or `-12gb`) runs a finished clip through
SeedVR2 7B. It does not
generate anything — point it at a file already on disk, from workflow 01 or
elsewhere.

```bash
./scripts/fetch-models.sh --with-upscale   # +8.7 GiB, fp8 build
python scripts/build-workflows.py          # also builds the upscale presets
```

Open the workflow, set the `video` field on the **Video to upscale** node to an
absolute path, and queue it.

**Measured:** 608×352 at 39 frames (1.6 s) became 1864×1080 in **2:13**, audio
passed through unchanged, duration exact to the millisecond. Runs on a single
card — SeedVR2 does not spread across devices, which is why `batch_size` has to
stay small (see the note card on the workflow, or the gotcha below).

**`blocks_to_swap` must stay `0`.** It looks like an OOM fix; instead it hangs
the process hard enough that Ctrl-C will not stop it. Only a kill or restart
clears it.

This uses the **fp8** SeedVR2 build (8.2 GB) rather than the fp16 release
(16.5 GB), to keep the download down.

## Settings

**Length is in frames**, on the 17k+5 grid: 124 = 5 s, 243 = 10 s, 362 = 15 s.
362 is the model's ceiling; past it the scene drifts.

**Resolution:** short side 768, ceiling 1344×768, both sides multiples of 32.

**Describe the sound.** H3 generates audio in the same pass. Say nothing about it
and you get silence or noise.

**Expect to normalise the audio afterwards.** Output level tracks what the prompt
describes, and the spread is large — across five clips generated in one batch,
integrated loudness ranged from **−13.5 LUFS** (a loud cyberpunk street) to
**−44.4 LUFS** (a quiet anime seaside), a 31 dB span. The quiet end is inaudible at
normal playback volume. The signal is clean either way, so a gain pass fixes it
without regenerating:

```bash
# measure with loudnorm, then apply the correction as a fixed gain
ffmpeg -i in.mp4 -map 0:a -af loudnorm=I=-16:TP=-1.5:print_format=json -f null -
ffmpeg -i in.mp4 -c:v copy -c:a aac -ar 32000 -af volume=<gain>dB out.mp4
```

Apply it **per file**, not as one blanket gain. And do not use `-af loudnorm` to do
the correcting: it resamples 32 kHz to 96 kHz, which re-frames the AAC stream and
pushes audio ~75 ms out of sync with the video. Measure with it, correct with
`volume`, and keep `-ar 32000`.

**There is no negative prompt.** This runs through `BasicGuider` with no CFG. If
you do not want something in shot, do not mention it.

**One continuous motion per clip.** You cannot fit a cut into five seconds.

**Close-up faces are the Turbo LoRA's weak point** — these are preview weights and
skin can go plastic at close range. Bypass the LoRA node (Ctrl+B) and raise steps
to 20 if that matters for a shot.

## The workflows are generated, not hand-built

Every file in `workflows/` is
emitted by `scripts/build-workflows.py`,
which reads node signatures from your running ComfyUI's `/object_info`. Slot
order, widget order and defaults come from the nodes themselves, so a pack that
changes its signature produces a build error rather than a workflow that loads
looking fine and is quietly mis-wired.

```bash
python scripts/build-workflows.py --check   # validate against your install
python scripts/build-workflows.py           # regenerate
```

## Gotchas

**Changed GPU? Re-run `tune.py` before anything else.** The allocation is written
*into* the workflow JSON, so it is a property of the file, not of the machine. Move
the file to a different card — or swap the card under it — and it silently keeps
the old number. A 3090's `cuda:0,13gb` on a 12 GB card does not fail at load time;
DisTorch2 packs in what it can, sampling starts, and it dies on the first
activation with an OOM that looks like the model is simply too big for the card.
It isn't. Re-tune and it runs:

```bash
python scripts/tune.py --width 864 --height 480 --frames 243
```

**Don't download anything heavy while generating.** Page cache fills, the kernel
goes off compacting memory, and a model load stalls for minutes with the GPU at
zero. It looks exactly like a hung job, and it bites harder here because the
working set is already close to your RAM.

**A killed `hf` leaves a lock file**, and the next download blocks forever
printing "Still waiting to acquire lock" with no other output.
`fetch-models.sh` clears stale locks automatically.

**Don't set `HF_HOME` to move the cache.** It moves the token lookup too, and you
silently drop to anonymous rate-limited downloads. Move `HF_XET_CACHE` instead,
which is what `fetch-models.sh` does.

## Experimental: getting under the RAM floor

Everything in the tested path streams rather than shrinks. The 19.5 GiB DiT and
25.3 GiB encoder are always fully present somewhere, which is exactly why RAM
binds harder as cards get smaller. Two third-party leads attack that; neither is
integrated, tested here, or required for anything above.

**[`experimental/gguf-quants/`](experimental/gguf-quants/README.md) — the one worth
testing next.** Quantized weights, ~8.9 GiB DiT and ~12.2 GiB encoder. Multiple
independent community conversions exist, and quantizing DiT-style transformers is
an established technique from other models rather than a new idea being tried
here. If it holds up it doesn't improve the numbers in the 30-series table, it
*replaces* them — no streaming, no 64 GB RAM floor. It is also testable on a
3090 today, which is the property that makes it the obvious next move.

**[`experimental/clipproj-encoder/`](experimental/clipproj-encoder/README.md) — a
further-out lead.** A learned projection substituting a much smaller text encoder.
Interesting and well-documented, but single-author, single-machine, with quality
losses its own author names. Worth watching, not worth betting on yet.

The gap between those two is deliberate. Both are unverified *here*, but "several
people have done this to other models" and "one person has done this once" are not
the same kind of unverified, and collapsing them into a single "experimental"
bucket would lose the distinction that actually matters.

## Thanks

To [alesha-pro](https://github.com/alesha-pro/tools), whose ComfyUI work on
MiniMax H3 is worth reading if you run this model — particularly on multi-GPU
setups, which this repo does not cover.

Model weights, node packs and ComfyUI itself carry their own licences; see
[CREDITS.md](CREDITS.md).

## Licence

MIT.

minimax-h3-30series

Owner Repos

File Explorer

# Use via CDN

Was this content helpful?

Recent Feedback

minimax-h3-30series

Owner Repos

File Explorer

# Use via CDN

Was this content helpful?

Recent Feedback

Download README