minimax-h3-mi308x

Status: paused. This repository is temporarily paused and kept as a technical reference only. The active serving line is mi308x-llm-lab (Qwen3.8-Flash-Next preparation + frozen Qwen3.8-27B / DeepSeek-V4-Flash-0731 recipes on the same GPU class with vLLM).

This repository runs MiniMax H3 (a 33B audio-video joint diffusion transformer) on a single AMD Instinct accelerator via DiffSynth-Studio. It ships a reusable inference service with task-aware model switching, hybrid precision (BF16 generation core + NF4 encoders), and the 4-step Turbo distilled LoRA (~12x speedup, near-lossless quality).

Features

• Three tasks, one service: text-to-video (t2va), first/last-frame (fl2va), reference-driven (ref2va), with native stereo audio.
• Lazy loading: models load on first request; idle consumes no VRAM.
• Task-aware switching: FL2VA ↔ Ref2VA partitions swap explicitly (del + gc + empty_cache) when the task changes.
• Hybrid precision (default): BF16 DiT + BF16 VideoVAE (quality-critical) + NF4 Text/Audio encoders (near-lossless intermediate vectors). About 87 GB on disk, ~100 GB peak VRAM.
• Turbo 4-step distillation: 50 sampling steps → 4, ~12x faster, quality close to lossless (per-partition LoRA).
• Three offload modes: gpu (weights resident, fastest), cpu (memory-resident), disk (slowest, smallest footprint).
• Gradio UI + Python API in one app; a CLI runner (scripts/03_run.py) for headless use.

Requirements

Quick start

# 1. Probe the environment (ROCm / torch / disk)
bash scripts/00_check_env.sh

# 2. Download weights — hybrid is the recommended default (~87 GB)
bash scripts/01_download_model.sh            # MODE=hybrid (default)

# 3. Install DiffSynth-Studio (ROCm)
bash scripts/02_install_diffsynth.sh

# 4. Run a quick text-to-video generation
python scripts/03_run.py --task t2va --prompt "A cat running on grass, cinematic" --output out.mp4

# 5. Or launch the Gradio UI
python app.py

Precision and VRAM

Tasks

Reference-driven generation is the recommended way to preserve character identity across shots: fl2va treats the image as a keyframe (the model may drift), while ref2va locks the subject's identity (face/clothing/marks) without locking lighting.

Performance (measured, MI308X single GPU, hybrid)

Turbo sampling: 7s HD clip (175 frames @768p) ≈ 2.7 min vs ~33 min at 50 steps.

Service API

core.MiniMaxH3Service is the inference core shared by the CLI and the Gradio app:

from core import MiniMaxH3Service

service = MiniMaxH3Service(precision="hybrid", offload="gpu", turbo=True)
video, audio = service.generate(
    task="t2va",
    prompt="A cat running on grass, cinematic",
    num_frames=124,
    num_inference_steps=4,
    seed=0,
)
print(service.gpu_memory_report())

Repository layout

minimax-h3-mi308x/
├── app.py                      # Gradio UI + API endpoint
├── core.py                     # inference core: lazy load / task switch / VRAM management
├── requirements.txt            # runtime dependencies
└── scripts/
    ├── 00_check_env.sh         # environment probe
    ├── 01_download_model.sh    # weight download (hybrid / nf4 / bf16)
    ├── 02_install_diffsynth.sh # DiffSynth-Studio install (ROCm)
    ├── 03_run.py               # CLI inference
    ├── 04_serve_vllm_omni.sh   # optional: OpenAI-compatible /v1/videos via vLLM-Omni
    ├── 05_ref2va.py            # reference-driven generation CLI
    └── serve.sh                # background service launcher

Limitations

• Local generation is 768p. 2K capability relies on un-released H3-Context-IR / H3-Regenerate-2K and requires the official MiniMax API.
• Single GPU with CPU offload: ~5–20 min per clip.
• Model weights are under the MiniMax Community License — review its terms before commercial use. Weights are downloaded at runtime and not redistributed here.

Related projects

• DiffSynth-Studio — the inference framework this service wraps
• mi308x-llm-lab — companion repo: LLM serving lab on the same GPU class with vLLM (Qwen3.8 series + frozen DeepSeek-V4-Flash-0731 recipe)

License

Apache-2.0. See LICENSE. Model weights are subject to the MiniMax Community License and are downloaded at runtime.