redkits/flux-h3-chain

FLUX.2 / Z-Image -> MiniMax-H3 Chain

Two-stage production image-to-video pipeline:

Stage 1 (keyframe)                    Stage 2 (video + native stereo audio)
Z-Image-Turbo (6B, fast)      or      MiniMax-H3 `fl2va` workflow
FLUX.2-klein-9B + abliterated  ----->  keyframe -> 5-15s @ 24fps,
text encoder (uncensored path)         32kHz synchronized stereo audio,
                                       up to 2K, muxed mp4

Hardware requirements

Stage	Minimum	Recommended
Z-Image-Turbo keyframe	1x 16GB GPU	1x 24GB GPU
FLUX.2-klein-9B keyframe	1x 24GB GPU	1x 40GB+ GPU
MiniMax-H3 fl2va	1x A100-80GB + >=240GB host RAM (auto CPU offload)	2x A100-80GB (conditioning split, see diffusers docs)

MiniMax-H3 ships a 61.7GB transformer + 62.1GB conditioner; the app uses ComponentsManager.enable_auto_cpu_offload to stream components onto the GPU. For lighter deployments, set H3_REPO=lightx2v/Minimax-h3-Turbo (distilled).

Quickstart

pip install -r requirements.txt
export HF_TOKEN=hf_xxx            # needed for MiniMaxAI/MiniMax-H3 (gated) + ponpoke encoder (gated)
export IMG_BACKEND=zimage         # or flux2klein for the uncensored path
python app.py                     # -> http://localhost:7860

Headless single-shot test:

python - <<'PY'
from app import gen_keyframe, gen_video
kf = gen_keyframe("cinematic lighthouse keeper at dawn, storm, volumetric light",
                  "zimage", 1280, 720, seed=42, steps=8)
kf.save("keyframe.png")
gen_video(kf, "storm intensifies, waves crash, beam sweeps", 5, 30, 42, 1280, 720)
PY

Environment knobs

Var	Default	Purpose
IMG_BACKEND	zimage	zimage or flux2klein
UNCENSORED_ENCODER	ponpoke/flux2-klein-9b-uncensored-text-encoder	abliterated Qwen3 encoder for FLUX.2-klein
H3_REPO	MiniMaxAI/MiniMax-H3	swap for lightx2v/Minimax-h3-Turbo etc.
H3_VARIANT	fl2va	fl2va (keyframe), t2va (text-only), ref2va (omni-reference)
H3_RESERVE	12GB	GPU memory reserve margin for offloading

Notes

• MiniMax-H3 integration is Modular Diffusers only (no DiffusionPipeline half) — requires diffusers main (pinned in requirements).
• Frame counts snap to 17*n + 5; duration is clamped to 5-15s at 24fps.
• Canvas dimensions must be multiples of 32.
• Guidance is distilled into the H3 weights: no CFG / negative prompt.
• Uncensored path: image-side refusals are removed at the text-encoder level (abliterated encoder); H3 weights run locally and have no hosted-API filter.