MiniMax-H3 Third-Person View LoRA demo

.gitattributes

@@ -33,3 +33,7 @@ saved_model/**/* filter=lfs diff=lfs merge=lfs -text
 *.zip filter=lfs diff=lfs merge=lfs -text
 *.zst filter=lfs diff=lfs merge=lfs -text
 *tfevents* filter=lfs diff=lfs merge=lfs -text
+examples/doorway_character.jpg filter=lfs diff=lfs merge=lfs -text
+examples/katana_character.jpg filter=lfs diff=lfs merge=lfs -text
+examples/night_city.jpg filter=lfs diff=lfs merge=lfs -text
+examples/wyvern_boss.jpg filter=lfs diff=lfs merge=lfs -text

README.md

@@ -1,13 +1,110 @@
 ---
-title: Minimax H3 Third Person View Lora
-emoji: 👁
-colorFrom: purple
-colorTo: purple
+title: MiniMax-H3 Third-Person View LoRA
+emoji: 🎮
+colorFrom: yellow
+colorTo: pink
 sdk: gradio
 sdk_version: 6.28.0
-python_version: '3.13'
 app_file: app.py
+python_version: "3.12"
+startup_duration_timeout: 1h
 pinned: false
+short_description: Design sheets to game cutscenes with HUD and audio
+suggested_hardware: zero-a10g
+models:
+  - MiniMaxAI/MiniMax-H3
+  - multimodalart/MiniMax-H3-Pruned
+  - WarmBloodAban/Minimax_H3_LoRAs
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# MiniMax-H3 · Third-Person View LoRA
+
+A demo of [`WarmBloodAban/Minimax_H3_LoRAs`](https://huggingface.co/WarmBloodAban/Minimax_H3_LoRAs)
+(`Minimax-h3_Third_person_view.safetensors`) on [MiniMax-H3](https://huggingface.co/MiniMaxAI/MiniMax-H3),
+MiniMax's 33B omni-modal model that generates video with natively synchronized audio.
+
+The LoRA turns H3 into a **game-cutscene renderer**: over-the-shoulder and FPV camera language,
+Unreal-Engine-looking lighting, and — the part it is actually distinctive for — **legible HUD furniture
+drawn in-frame**: target-lock reticles, floating damage numbers, QTE prompts, translucent status bars.
+The soundtrack (impacts, foley, score) is base H3's, generated in the same denoising pass.
+
+## It is a *reference* LoRA, not a text-to-video one
+
+The adapter's own metadata says `ss_base_model_version: minimax_h3_ref2va`, so it was trained on H3's
+**ref2va** partition — the one that conditions on an ordered list of reference media, not the plain
+text-to-video partition. So this Space is built around reference sheets: you upload a character sheet,
+an environment plate, a boss design, and H3 keeps those identities consistent through the shot.
+Running this adapter on the t2v partition would attach cleanly and quietly produce worse output; it
+isn't offered.
+
+## What the demo owes the model card
+
+| The card says | Here |
+|---|---|
+| LoRA weight **0.6 – 0.85**, 0.7 recommended | A slider clamped to exactly that window, defaulting to 0.7. The adapter is attached with PEFT and re-scaled per request, so the window is live |
+| A long structured prompt format — `subject_definitions:` / `summary:` / `retention_analysis:` / `detailed_description:` with `[Shot N]` beats / `overall_soundscape:` / `non_diegetic_music:`, cross-referencing `<Subject N>`, `<Environment N>`, `<Picture N>` | The UI **is** that format. Each reference slot you fill becomes a `<Subject N>`/`<Environment N>` bound to its `<Picture N>`; your one action line plus the camera preset become the `detailed_description:` beats; the `summary:` is prefixed `[reference generation]` as the card shows. The assembled document is shown after every run, and an override box takes a hand-written one |
+| Trigger vocabulary in three groups — camera views (*third-person perspective*, *over-the-shoulder camera*, *first-person POV*, *FPV HUD*), game rendering (*rendered in Unreal Engine*, *gameplay sequence*, *combat stance*, *macro close-up*), UI elements (*transparent HUD elements*, *target-lock UI reticle*, *QTE UI prompt*, *floating damage text UI*) | The four camera presets each spend the camera-view + game-rendering tags their shot actually wants; the HUD checkbox spends the UI group. Nothing is sprinkled in decoratively |
+| Base is the **INT8 Reference** architecture | The ref2va DiT, in bf16 on ZeroGPU's 96 GB tier — no quantization needed at this size |
+
+## Architecture
+
+MiniMax-H3 is 195.9 GiB in bf16 and a ZeroGPU Space is evicted at 150 GB of storage, so the pipeline is
+cut at its `text_encoder` step — the split every MiniMax-H3 Space uses. The 62 GiB Qwen3-VL conditioner
+runs in [`multimodalart/qwen3vl-conditioner`](https://huggingface.co/spaces/multimodalart/qwen3vl-conditioner)
+and is called over the gradio API with each caller's own ZeroGPU token forwarded, so the booking is
+billed to whoever asked for the video; `prompt_embeds` + `text_token_tags` is the whole wire format.
+This Space holds the DiT and the two autoencoders. `h3_split_blocks.py` holds the denoising-half block
+stack.
+
+The DiT is [`multimodalart/MiniMax-H3-Pruned`](https://huggingface.co/multimodalart/MiniMax-H3-Pruned),
+which folds the AdaLN input projections onto a rank-8 subspace: `transformer_ref` drops from 61.7 GiB
+to 37.5 GiB with identical output. This LoRA touches no AdaLN module, so nothing needs projecting.
+
+## How the LoRA is applied
+
+Attached as a live **PEFT adapter** (`load_lora_adapter(..., adapter_name="third_person_view")`) and
+re-scaled per request via `set_adapters`, rather than folded into the base weights — folding would be
+faster to serve but would freeze the strength, and 0.6–0.85 is the knob this LoRA is actually steered
+with. For the same reason the pipeline is **not** AoTI-compiled: a captured graph would route around
+the PEFT-injected layers and silently drop the adapter.
+
+The export is keyed on the *original* H3 partition (`diffusion_model.blocks.N.…`, 416 tensors, rank 64,
+ai-toolkit), so applying it to the diffusers port means replaying the layout transforms
+[`convert_minimax_h3_to_diffusers.py`](https://github.com/huggingface/diffusers/blob/main/scripts/convert_minimax_h3_to_diffusers.py)
+applied to the base weights — a delta is only valid in the layout of the weight it is added to:
+
+| Original LoRA target | diffusers parameter | Transform |
+|---|---|---|
+| `blocks.N.…` / `token_refiner.blocks.N.…` | `transformer_blocks.N.…` / `token_refiner.refiner_blocks.N.…` | rename |
+| `attn.out_proj` | `attn.to_out.0` | rename |
+| `attn.qkv_proj` | `attn.to_q` / `to_k` / `to_v` | split `lora_B`'s rows into contiguous thirds |
+| `mlp.fc2` | `ff.net.2` | rename |
+| `mlp.fc1` | `ff.net.0.proj` | **swap the two fused SwiGLU halves** (`[gate; value]` → `[value; gate]`) |
+
+Both of the last two rows are easy to get wrong. The gate/value swap is a real difference between H3's
+native SwiGLU packing and diffusers' `GEGLU`-style ordering — skip it and every MLP delta lands on the
+wrong half of the activation. Conversely the contiguous QKV split is *only* correct for ai-toolkit
+exports like this one; fal-trained H3 LoRAs store per-head-interleaved QKV rows and need de-interleaving
+first. The two are distinguished by key naming, and this repo is unambiguously the former. Any target
+that resolves to no transformer weight is a fatal error rather than a silent skip.
+
+## Examples
+
+Three ready-to-run briefs. The wyvern-boss and ruined-village reference sheets are frames lifted from
+the LoRA author's own showcase clip in
+[`WarmBloodAban/Minimax_H3_LoRAs`](https://huggingface.co/WarmBloodAban/Minimax_H3_LoRAs) (Apache-2.0) —
+the closest thing to the inputs the adapter was demonstrated on. The character and city plates come from
+[`linoyts/repo-to-space-example-inputs`](https://huggingface.co/datasets/linoyts/repo-to-space-example-inputs)
+(CC0-1.0).
+
+## Known limits
+
+Five seconds of 24 fps video per run, at 960×544 or 1280×720. HUD text is *shaped* like HUD text and
+usually isn't real words — that's a base-H3 limit the LoRA doesn't fix. Faces drift on fast whip-pans.
+The first request after a cold start pays for weight download plus placement.
+
+## License
+
+MiniMax-H3 is covered by the **MiniMax H3 Community License Agreement** — note its attribution,
+territorial-scope and revenue clauses. The LoRA is Apache-2.0. Read both before using any output of
+this Space.

app.py

@@ -0,0 +1,894 @@
+"""MiniMax-H3 · Third-Person View LoRA — game cutscenes from design reference sheets.
+
+[`WarmBloodAban/Minimax_H3_LoRAs`](https://huggingface.co/WarmBloodAban/Minimax_H3_LoRAs) ships
+`Minimax-h3_Third_person_view.safetensors`, a rank-64 ai-toolkit LoRA whose own metadata names its base as
+`minimax_h3_ref2va` — the **reference** partition of MiniMax-H3, the one that conditions on an ordered list of
+reference images rather than on a first frame. That is why this Space is a `ref2va` deployment: the adapter goes
+onto `transformer_ref`, and the user's uploads arrive as `<Picture 1..3>` in the order they are given.
+
+What the LoRA does, from its card: cinematic game cutscenes — third-person over-the-shoulder / spring-arm camera
+tracking, first-person POV, whip-pan view transitions, and native game HUD overlays (target-lock reticles, Boss
+health bars, QTE prompts, floating damage text). Its card is explicit that it wants MiniMax-H3's **structured**
+prompt format (`subject_definitions` / `summary` / `retention_analysis` / `detailed_description` /
+`overall_soundscape` / `non_diegetic_music`) with `<Subject N>` / `<Environment N>` / `<Picture N>` cross-references,
+so this demo is a composer for exactly that document rather than a prompt box: you label each reference sheet, write
+one line of action, pick a camera and whether the HUD is on, and the Space assembles the card's format around the
+LoRA's own trigger vocabulary. The assembled document is shown next to the result, and an override box takes a
+hand-written one.
+
+Recipe, all from the card: LoRA weight **0.6–0.85, 0.7 recommended** (a live slider here, which is why the adapter
+is attached with PEFT rather than folded into the weights).
+
+Deployment follows the other MiniMax-H3 Spaces. H3 is 195.9 GiB in bfloat16 and a ZeroGPU Space is evicted at 150 GB
+of storage, so `MiniMaxH3Ref2VAGeneratorBlocks` is cut at its `text_encoder` step: the 62 GiB Qwen3-VL conditioner
+runs in [`multimodalart/qwen3vl-conditioner`](https://huggingface.co/spaces/multimodalart/qwen3vl-conditioner) and is
+called over the gradio API, while this Space holds the DiT and the two autoencoders. The DiT is
+[`multimodalart/MiniMax-H3-Pruned`](https://huggingface.co/multimodalart/MiniMax-H3-Pruned)'s `transformer_ref`
+(37.5 GiB — the AdaLN input projections folded onto their reachable rank-8 subspace, 1.5e-5 relative, ~250x below one
+bfloat16 step), which this LoRA does not touch: it adapts `attn.qkv_proj`, `attn.out_proj` and `mlp.fc1`/`fc2` only.
+"""
+
+from __future__ import annotations
+
+import os
+import tempfile
+import time
+import traceback
+from functools import cache
+
+# Before anything that could initialize CUDA: `import spaces` patches `torch.cuda` so the weights can be loaded at
+# startup rather than on GPU time.
+import spaces  # noqa: F401
+import gradio as gr
+import torch
+
+VERSION = "tpv-lora"
+MODEL_REPO = os.environ.get("H3_MODEL_REPO", "multimodalart/MiniMax-H3-Pruned")
+LORA_REPO = os.environ.get("H3_LORA_REPO", "WarmBloodAban/Minimax_H3_LoRAs")
+LORA_FILE = os.environ.get("H3_LORA_FILE", "Minimax-h3_Third_person_view.safetensors")
+ADAPTER = "third_person_view"
+CONDITIONER_SPACE = os.environ.get("H3_CONDITIONER", "multimodalart/qwen3vl-conditioner")
+# `lazy` moves the weights onto the card inside the first GPU call and leaves them there. Startup placement is not an
+# option: `spaces`' startup `torch.pack()` writes a second on-disk copy of every startup-resident CUDA tensor, and
+# 48 GB of weights plus its pack runs at the 150 GB Space storage quota.
+PLACEMENT = os.environ.get("H3_PLACEMENT", "lazy").lower()
+# cuDNN's fused attention is 10-20% faster than the SDPA default on this pool and needs nothing installed.
+# flash-attention 3 is sm90-only and this card is sm120 (the `zero-a10g` flavour name is legacy).
+ATTENTION = os.environ.get("H3_ATTENTION", "_native_cudnn").lower()
+GPU_SIZE = os.environ.get("H3_GPU_SIZE", "xlarge")
+MIN_GPU_DURATION = int(os.environ.get("H3_GPU_DURATION_MIN", "120"))
+MAX_GPU_DURATION = int(os.environ.get("H3_GPU_DURATION_MAX", "1500"))
+
+# The card's recommended weight window, verbatim: "LoRA Weight: 0.6 - 0.85 (0.7 is recommended as a starting point)".
+WEIGHT_MIN, WEIGHT_MAX, DEFAULT_WEIGHT = 0.6, 0.85, 0.7
+DEFAULT_STEPS = 20
+DEFAULT_SEED = 42
+
+# Must stay identical to the conditioner's table: the *label* goes over the wire, so a canvas that half does not know
+# is rejected there and surfaces as a failure here.
+CANVASES = {
+    # 16:9
+    "960x544 · 16:9 fast": (544, 960),
+    "1024x576 · 16:9 fast": (576, 1024),
+    "1152x640 · 16:9": (640, 1152),
+    "1280x704 · 16:9": (704, 1280),
+    "1344x768 · 16:9 full": (768, 1344),
+    # 21:9
+    "1152x512 · 21:9 fast": (512, 1152),
+    "1536x672 · 21:9 full": (672, 1536),
+    # 9:16
+    "544x960 · 9:16 fast": (960, 544),
+    "640x1152 · 9:16": (1152, 640),
+    # 4:3
+    "768x576 · 4:3 fast": (576, 768),
+    "1024x768 · 4:3 full": (768, 1024),
+}
+# Game cutscenes are widescreen; the cheapest 16:9 bucket keeps a default request inside a few minutes of GPU.
+DEFAULT_CANVAS = "960x544 · 16:9 fast"
+FPS, FRAMES_PER_CHUNK, LATENTS_PER_CHUNK = 24, 17, 5
+MIN_DURATION, MAX_UI_DURATION = 2, 14
+MAX_IMAGE_SLOTS, OPEN_IMAGE_SLOTS = 3, 2
+
+# Seconds of GPU one request needs, from the packed sequence it is about to denoise: linear in the rows for the
+# matmuls, quadratic for the attention. Fit shared with the other MiniMax-H3 Spaces on this pool.
+STEP_LINEAR, STEP_QUADRATIC, SAFETY = 1.1745e-4, 3.8396e-9, 1.3
+PLACEMENT_ALLOWANCE = int(os.environ.get("H3_PLACEMENT_ALLOWANCE", "90"))
+AUDIO_LATENTS_PER_SECOND, AUDIO_CHANNELS = 40, 2
+REFERENCE_IMAGE_SHORT_EDGE, CANVAS_MULTIPLE = 2048, 32
+DECODE_BASE, DECODE_PER_DEFAULT_CANVAS, DEFAULT_CANVAS_PIXELS = 15, 25, 960 * 544 * 124
+# A 2048-short-edge reference also becomes Qwen3-VL vision tokens in the text stream. Only the *estimate* label needs
+# a number for them; the booking itself reads the tags the conditioner actually returned.
+ESTIMATED_TEXT_ROWS, ESTIMATED_VISION_ROWS_PER_IMAGE = 900, 1800
+
+# ── The LoRA's prompt contract ────────────────────────────────────────────────
+# Roles, camera phrasings and the HUD clause are built out of the card's own "Key Trigger Words & Recommended Tags"
+# (camera views: third-person perspective, over-the-shoulder camera, first-person POV, FPV HUD; game rendering:
+# rendered in Unreal Engine, gameplay sequence, combat stance; UI elements: transparent HUD elements, target-lock UI
+# reticle, QTE UI prompt, floating damage text UI) and out of the structured example prompt it publishes.
+
+ROLES = {
+    "Character": ("subject", "character design reference sheet"),
+    "Creature / Boss": ("subject", "monster design reference sheet"),
+    "Prop / Weapon": ("subject", "prop design reference sheet"),
+    "Environment": ("environment", "environment design reference sheet"),
+}
+
+CAMERAS = {
+    "Third-person · over-the-shoulder": {
+        "genre": "third-person",
+        "summary": "tracked continuously by an over-the-shoulder spring-arm camera",
+        "aesthetic": "third-person over-the-shoulder spring-arm camera tracking",
+        "opening": "an over-the-shoulder camera locked 3.0 meters directly behind",
+        "continues": (
+            "The camera holds its over-the-back angle and adjusts its spring-arm distance with every movement, "
+            "with hit-impulse micro-shakes on each impact."
+        ),
+    },
+    "Third-person · orbiting combat camera": {
+        "genre": "third-person",
+        "summary": "tracked by an orbiting third-person combat camera",
+        "aesthetic": "orbiting third-person combat camera with a dynamic spring-arm distance",
+        "opening": "a third-person combat camera orbiting 4.0 meters around",
+        "continues": (
+            "The camera orbits around the action and tightens its distance on every impact, keeping the combat "
+            "stance centred in frame."
+        ),
+    },
+    "First-person POV (FPV)": {
+        "genre": "first-person",
+        "summary": "shown entirely in first-person POV with FPV framing",
+        "aesthetic": "first-person POV (FPV) camera with weapon-in-hand framing",
+        "opening": "a first-person POV camera looking out through the eyes of",
+        "continues": (
+            "The camera stays in first-person POV throughout, with FPV head-bob, fast view whip-pans and "
+            "weapon-in-hand framing at the bottom of frame."
+        ),
+    },
+    "Whip-pan: third-person → first-person": {
+        "genre": "third-person",
+        "summary": "starting over-the-shoulder and whip-panning into first-person POV",
+        "aesthetic": "third-person to first-person perspective transition driven by a fast camera whip-pan",
+        "opening": "an over-the-shoulder camera locked 3.0 meters behind",
+        "continues": (
+            "Mid-sequence the camera whip-pans forward into a first-person POV view and holds it to the end of "
+            "the shot."
+        ),
+    },
+}
+DEFAULT_CAMERA = "Third-person · over-the-shoulder"
+
+HUD_CLAUSE = (
+    ", and transparent combat HUD elements in the top-right corner: a target-lock UI reticle, a Boss health bar, "
+    "floating damage text UI and QTE UI prompts"
+)
+NO_HUD_CLAUSE = ", and a clean cinematic frame with no UI overlays"
+DEFAULT_SOUNDSCAPE = (
+    "Footsteps on wet stone, weapon impacts and metallic blade clashes, monstrous roars, thruster and dash bursts, "
+    "and crisp action RPG combat UI audio effects."
+)
+DEFAULT_MUSIC = (
+    "An intense, high-tempo epic battle track, orchestral-electronic, with heavy industrial percussion and a low "
+    "pulsing synth bass that swells through the sequence."
+)
+
+
+def snap_frames(seconds: float) -> int:
+    """The frame count MiniMax-H3's video VAE can decode: the next `17 * n + 5` at 24 fps."""
+    frames = max(1, round(float(seconds) * FPS))
+    while frames % FRAMES_PER_CHUNK != LATENTS_PER_CHUNK:
+        frames += 1
+    return frames
+
+
+def lower_duration_floor(seconds: float = MIN_DURATION) -> None:
+    """Let the pipeline generate below its 5 s floor. 56 frames (2.33 s) is fine on this checkpoint."""
+    from diffusers.modular_pipelines.minimax_h3.modular_pipeline import MiniMaxH3ModularPipeline
+
+    MiniMaxH3ModularPipeline.min_duration = property(lambda self: float(seconds))
+
+
+def video_latent_frames(num_frames: int) -> int:
+    """`17 * n + 5` frames become `5 * n + 2` video latents."""
+    return 5 * ((num_frames - LATENTS_PER_CHUNK) // FRAMES_PER_CHUNK) + 2
+
+
+def target_rows(height: int, width: int, num_frames: int) -> int:
+    """The generated rows of the packed sequence: video patched `(1, 2, 2)`, plus two audio rows per latent."""
+    video = video_latent_frames(num_frames) * (height // CANVAS_MULTIPLE) * (width // CANVAS_MULTIPLE)
+    return video + round(num_frames / FPS * AUDIO_LATENTS_PER_SECOND) * AUDIO_CHANNELS
+
+
+def reference_rows(image_paths: list[str]) -> int:
+    """The rows the image reference blocks add, from metadata alone — no decode.
+
+    A reference image is resized to a 2048-pixel short edge and encoded as a single frame, so a squarer reference is
+    a cheaper one.
+    """
+    from PIL import Image
+
+    rows = 0
+    for path in image_paths:
+        if not path:
+            continue
+        try:
+            width, height = Image.open(path).size
+        except Exception:
+            width, height = 1024, 1024
+        scale = REFERENCE_IMAGE_SHORT_EDGE / min(width, height)
+        resolved = [
+            max(CANVAS_MULTIPLE, round(edge * scale / CANVAS_MULTIPLE) * CANVAS_MULTIPLE) for edge in (height, width)
+        ]
+        rows += (resolved[0] // CANVAS_MULTIPLE) * (resolved[1] // CANVAS_MULTIPLE)
+    return rows
+
+
+def denoise_seconds(sequence: int, steps: int) -> float:
+    return int(steps) * (STEP_LINEAR * sequence + STEP_QUADRATIC * sequence**2) * SAFETY
+
+
+def get_duration(prompt_embeds, text_token_tags, image_paths, height, width, num_frames, steps, weight, seed, **_):
+    """Seconds of GPU to reserve for one request, from the packed sequence it is about to denoise."""
+    sequence = int(text_token_tags.shape[0]) + reference_rows(image_paths) + target_rows(height, width, num_frames)
+    denoise = denoise_seconds(sequence, steps)
+    encode = 5 + reference_rows(image_paths) * 1e-3
+    decode = DECODE_BASE + DECODE_PER_DEFAULT_CANVAS * (height * width * num_frames) / DEFAULT_CANVAS_PIXELS
+    total = PLACEMENT_ALLOWANCE + encode + denoise + decode + 10
+    duration = max(MIN_GPU_DURATION, min(MAX_GPU_DURATION, int(total)))
+    print(f"[{VERSION}] S={sequence} -> reserving {duration}s ({denoise:.0f}s of denoise at {steps} steps)", flush=True)
+    return duration
+
+
+def estimate_label(canvas, duration, steps, *image_paths) -> str:
+    """The same estimate, phrased for the UI, so the cost of a canvas / duration / steps choice is visible up front."""
+    height, width = CANVASES.get(canvas, CANVASES[DEFAULT_CANVAS])
+    num_frames = snap_frames(duration)
+    paths = [path for path in image_paths if path]
+    refs = reference_rows(paths)
+    sequence = ESTIMATED_TEXT_ROWS + ESTIMATED_VISION_ROWS_PER_IMAGE * len(paths) + refs
+    sequence += target_rows(height, width, num_frames)
+    seconds = int(PLACEMENT_ALLOWANCE + 5 + denoise_seconds(sequence, steps) + DECODE_BASE)
+    return (
+        f"{width}x{height} · {num_frames} frames ({num_frames / FPS:.2f} s) · {int(steps)} steps · "
+        f"{len(paths)} reference{'' if len(paths) == 1 else 's'} → roughly "
+        f"**{seconds // 60}m {seconds % 60:02d}s** of GPU time"
+    )
+
+
+# ── The LoRA, onto the diffusers port ────────────────────────────────────────
+#
+# `Minimax-h3_Third_person_view.safetensors` is an ai-toolkit export: 416 tensors, rank 64, no `.alpha`, keys
+# `diffusion_model.blocks.N.{attn.qkv_proj,attn.out_proj,mlp.fc1,mlp.fc2}.lora_{A,B}.weight` plus the same four under
+# `token_refiner.blocks.N`, and `ss_base_model_version: minimax_h3_ref2va` in its metadata. diffusers serves the
+# *converted* port, so every name — and, for two of them, the row layout of `lora_B` — has to be pushed through the
+# same transforms `scripts/convert_minimax_h3_to_diffusers.py` applied to the base weights. This reproduces
+# `_convert_non_diffusers_minimax_h3_lora_to_diffusers`:
+#
+#   * `blocks.` -> `transformer_blocks.`, `token_refiner.blocks.` -> `token_refiner.refiner_blocks.`,
+#     `attn.out_proj` -> `attn.to_out.0`, `mlp.fc2` -> `ff.net.2` (pure renames),
+#   * `mlp.fc1` -> `ff.net.0.proj` with its two fused halves swapped: the reference computes `fc2(silu(gate) * value)`
+#     from a fused `[gate; value]` while diffusers' `SwiGLU` computes `value * silu(gate)` from a fused
+#     `[value; gate]`, so the halves trade places,
+#   * `attn.qkv_proj` -> `to_q` / `to_k` / `to_v`: split `lora_B`'s 21504 rows into **contiguous** thirds of 7168
+#     (`num_attention_heads * attention_head_dim`).
+#
+# That last split is where MiniMax-H3 LoRAs diverge. DiffSynth-Studio exports run the raw checkpoint's *per-head
+# interleaved* fused QKV and have to be de-interleaved before the split; they are identified by peft's `.default.`
+# infix over these names. ai-toolkit exports under `diffusion_model.` are already `[q_all; k_all; v_all]` and must
+# **not** be reordered — de-interleaving this file anyway would scatter each head's q/k/v across all three
+# projections and turn the adapter into structured noise on all 50 blocks.
+#
+# Row transforms only ever touch `lora_B`, so the three attention projections share one `lora_A`: the rows of `B @ A`
+# are the rows of `B`, which makes the split exact rather than an approximation.
+
+
+def _lora_target_name(source_name: str) -> str:
+    """Map an original-checkpoint module path to the diffusers one (no `.lora_A/B.*` suffix)."""
+    if source_name.startswith("token_refiner.blocks."):
+        return source_name.replace("token_refiner.blocks.", "token_refiner.refiner_blocks.", 1)
+    if source_name.startswith("blocks."):
+        return source_name.replace("blocks.", "transformer_blocks.", 1)
+    return source_name
+
+
+def _lora_modules(name: str, a_weight, b_weight, inner_dim: int):
+    """Yield `(diffusers_module_path, lora_A, lora_B)` for one original module path."""
+    target = _lora_target_name(name)
+
+    if target.endswith(".attn.qkv_proj"):
+        prefix = target.removesuffix("qkv_proj")
+        for kind, part in zip(("q", "k", "v"), b_weight.split(inner_dim, dim=0)):
+            yield f"{prefix}to_{kind}", a_weight, part.contiguous()
+    elif target.endswith(".mlp.fc1"):
+        gate, value = b_weight.chunk(2, dim=0)
+        yield target.replace(".mlp.fc1", ".ff.net.0.proj"), a_weight, torch.cat([value, gate]).contiguous()
+    elif target.endswith(".mlp.fc2"):
+        yield target.replace(".mlp.fc2", ".ff.net.2"), a_weight, b_weight
+    elif target.endswith(".attn.out_proj"):
+        yield target.replace(".attn.out_proj", ".attn.to_out.0"), a_weight, b_weight
+    else:
+        raise ValueError(
+            f"unexpected LoRA target `{name}`: this adapter is documented as attention + feed-forward only, so a "
+            "new module type means the checkpoint changed"
+        )
+
+
+def build_lora_state_dict(transformer) -> tuple[dict, int, int]:
+    """Download the LoRA and remap it into a PEFT-format state dict for the diffusers transformer.
+
+    Every target is validated against the transformer's own parameter shapes, and an unresolved one is fatal: a
+    silently dropped target means the name mapping is wrong and the Space would serve a half-applied adapter that
+    still *looks* like it worked.
+    """
+    from huggingface_hub import hf_hub_download
+    from safetensors.torch import load_file
+
+    raw = load_file(hf_hub_download(LORA_REPO, LORA_FILE))
+
+    prefix, suffix_a, suffix_b = "diffusion_model.", ".lora_A.weight", ".lora_B.weight"
+    unexpected = [key for key in raw if not (key.startswith(prefix) and key.endswith((suffix_a, suffix_b)))]
+    if unexpected:
+        raise ValueError(f"{LORA_FILE} holds {len(unexpected)} unexpected tensors, e.g. {unexpected[:5]}")
+    bases = sorted({key[len(prefix) : -len(suffix_a)] for key in raw if key.endswith(suffix_a)})
+    if not bases:
+        raise ValueError(f"No `{prefix}*{suffix_a}` / `{suffix_b}` pairs found in {LORA_FILE}")
+
+    ranks = set()
+    for name in bases:
+        if f"{prefix}{name}{suffix_b}" not in raw:
+            raise ValueError(f"LoRA is missing the lora_B twin of {prefix}{name}{suffix_a}")
+        ranks.add(raw[f"{prefix}{name}{suffix_a}"].shape[0])
+    if len(ranks) != 1:
+        raise ValueError(f"LoRA mixes ranks {sorted(ranks)}; this loader assumes a single rank")
+    rank = ranks.pop()
+
+    inner_dim = transformer.config.num_attention_heads * transformer.config.attention_head_dim
+    base_shapes = {key: tuple(value.shape) for key, value in transformer.state_dict().items()}
+
+    state_dict: dict[str, torch.Tensor] = {}
+    missed: list[str] = []
+    for name in bases:
+        a_weight = raw[f"{prefix}{name}{suffix_a}"]
+        b_weight = raw[f"{prefix}{name}{suffix_b}"]
+        for module, a_part, b_part in _lora_modules(name, a_weight, b_weight, inner_dim):
+            base = base_shapes.get(f"{module}.weight")
+            if base is None:
+                missed.append(module)
+                continue
+            # `W` is [out, in]; the adapter must be `lora_B` [out, r] @ `lora_A` [r, in].
+            if (b_part.shape[0], a_part.shape[1]) != base:
+                raise ValueError(
+                    f"LoRA delta for `{module}` would be {(b_part.shape[0], a_part.shape[1])}, "
+                    f"base weight is {base}"
+                )
+            state_dict[f"{module}.lora_A.weight"] = a_part
+            state_dict[f"{module}.lora_B.weight"] = b_part
+    if missed:
+        raise ValueError(
+            f"{len(missed)} LoRA targets matched no transformer weight, e.g. {missed[:5]}. "
+            "The LoRA and the diffusers transformer disagree on module naming."
+        )
+    return state_dict, rank, len(bases)
+
+
+def load_and_apply_lora(transformer) -> str:
+    """Attach the LoRA as a PEFT adapter so its strength stays a per-request knob."""
+    state_dict, rank, targets = build_lora_state_dict(transformer)
+    # `prefix=None` because the keys are already the transformer's own module paths, and no `network_alphas` because
+    # the file carries no `.alpha` tensors — PEFT then sets alpha == rank, i.e. the adapter's intrinsic scale is 1.0
+    # and the `set_adapters` weight *is* the strength the card talks about.
+    transformer.load_lora_adapter(state_dict, prefix=None, adapter_name=ADAPTER)
+    transformer.set_adapters([ADAPTER], [DEFAULT_WEIGHT])
+    return (
+        f"LoRA attached · {targets} checkpoint targets -> {len(state_dict) // 2} diffusers modules, rank {rank}, "
+        f"alpha == rank · default weight {DEFAULT_WEIGHT:g} · {LORA_FILE}"
+    )
+
+
+# ── Model loading ────────────────────────────────────────────────────────────
+
+PIPE = None
+LOAD_ERROR: str | None = None
+LORA_STATUS: str | None = None
+
+
+def load_models() -> str | None:
+    """Load the denoising half at startup, but *not* onto the card — see `PLACEMENT`.
+
+    `MiniMaxH3Ref2VAGeneratorBlocks` declares `transformer_ref`, `vae`, `audio_vae`, the two schedulers and
+    `video_processor`, so `load_components` fetches exactly those subfolders — `text_encoder/` and the `transformer/`
+    partition are never touched. Both autoencoders carry `_keep_in_fp32_modules` over every module and stay float32:
+    a bfloat16 audio VAE decodes the soundtrack roughly 20 dB too quiet.
+    """
+    global PIPE, LOAD_ERROR, LORA_STATUS
+
+    if PIPE is not None or LOAD_ERROR is not None:
+        return LOAD_ERROR
+
+    started = time.time()
+    try:
+        from diffusers import ComponentsManager
+
+        from h3_split_blocks import MiniMaxH3Ref2VAGeneratorBlocks
+
+        lower_duration_floor()
+        blocks = MiniMaxH3Ref2VAGeneratorBlocks()
+        print(f"[{VERSION}] loading {[c.name for c in blocks.expected_components]} from {MODEL_REPO} ...", flush=True)
+        pipe = blocks.init_pipeline(MODEL_REPO, components_manager=ComponentsManager(), collection="h3")
+        # The pruned DiT is served as remote code (`transformer_ref/modeling_minimax_h3_pruned.py`, reached through
+        # the `AutoModel` type hint in `modular_model_index.json`). `load_components` forwards `trust_remote_code`
+        # only to components that live in the pipeline's own repo, so the two VAEs and the schedulers — which
+        # `modular_model_index.json` still points at `MiniMaxAI/MiniMax-H3` — never see it.
+        pipe.load_components(dtype=torch.bfloat16, trust_remote_code=True)
+
+        # Both VAEs explicitly, and before the transformer: `set_attention_backend` also sets the registry's *global*
+        # backend, and the float32 audio VAE has no cuDNN kernel.
+        pipe.vae.set_attention_backend("native")
+        pipe.audio_vae.set_attention_backend("native")
+        pipe.transformer_ref.set_attention_backend(ATTENTION)
+
+        # Before any GPU placement, so the adapter's parameters travel with the transformer. No AoTI package on this
+        # Space on purpose: a compiled block graph is captured around the base linears and would silently bypass the
+        # LoRA layers PEFT injects.
+        LORA_STATUS = load_and_apply_lora(pipe.transformer_ref)
+        print(f"[{VERSION}] {LORA_STATUS}", flush=True)
+
+        import h3_fbc
+
+        print(f"[h3-fbc] {h3_fbc.status()}", flush=True)
+
+        PIPE = pipe
+        print(f"[{VERSION}] ready in {time.time() - started:.0f}s", flush=True)
+    except Exception as error:
+        traceback.print_exc()
+        LOAD_ERROR = (
+            f"**Loading `{MODEL_REPO}` failed** after {time.time() - started:.0f}s: "
+            f"`{type(error).__name__}: {error}`"
+        )
+    return LOAD_ERROR
+
+
+# ── Prompt composition ───────────────────────────────────────────────────────
+
+
+def collect_slots(slots) -> list[tuple[str, str, str]]:
+    """The `(path, role, description)` references of a request, in the order the model reads them.
+
+    That order numbers `<Picture N>` and advances the shared audio/video rotary clock, so the same references in a
+    different order are a different request.
+    """
+    return [(path, role, (detail or "").strip()) for path, role, detail in slots if path]
+
+
+def compose_prompt(references, action, camera, hud, soundscape, music, seconds) -> str:
+    """Assemble MiniMax-H3's structured document in the layout the LoRA's card publishes."""
+    action = (action or "").strip().rstrip(".")
+    spec = CAMERAS.get(camera, CAMERAS[DEFAULT_CAMERA])
+
+    entries, subjects, environments = [], 0, 0
+    for index, (_, role, detail) in enumerate(references, start=1):
+        kind, sheet = ROLES.get(role, ROLES["Character"])
+        if kind == "subject":
+            subjects += 1
+            label = f"<Subject {subjects}>"
+        else:
+            environments += 1
+            label = f"<Environment {environments}>"
+        entries.append((label, index, detail, sheet))
+
+    subject = next((label for label, _, _, sheet in entries if "environment" not in sheet), "the player character")
+    environment = next((label for label, _, _, sheet in entries if "environment" in sheet), None)
+    place = f" in {environment}" if environment else ""
+
+    definitions = [
+        f"{label} is {detail} from <Picture {index}>."
+        if detail
+        else f"{label} is the subject shown in <Picture {index}>."
+        for label, index, detail, _ in entries
+    ]
+    definitions += [f"<Picture {index}> is the {sheet} for {label}." for label, index, _, sheet in entries]
+
+    retention = [
+        f"{label} (appears in [Shot 1]): fully_preserved - the design, colours and silhouette from "
+        f"<Picture {index}> are fully preserved."
+        for label, index, _, _ in entries
+    ]
+
+    sections = [
+        "subject_definitions:\n" + "\n".join(definitions),
+        (
+            "summary:\n"
+            f"[reference generation] A {float(seconds):g}-second photorealistic {spec['genre']} action RPG "
+            f"gameplay sequence{place}, where {subject} {action}, {spec['summary']}."
+        ),
+        "retention_analysis:\n" + "\n".join(retention),
+        (
+            "detailed_description:\n"
+            f"The target video features a photorealistic 3D {spec['genre']} action RPG gameplay aesthetic rendered "
+            f"in Unreal Engine with real-time game mechanics, {spec['aesthetic']}, deep depth of field"
+            f"{HUD_CLAUSE if hud else NO_HUD_CLAUSE}.\n"
+            f"[Shot 1] The video opens with {spec['opening']} {subject}{place}. {action.capitalize()}. "
+            f"{spec['continues']}"
+        ),
+    ]
+    if (soundscape or "").strip():
+        sections.append("overall_soundscape:\n" + soundscape.strip())
+    if (music or "").strip():
+        sections.append("non_diegetic_music:\n" + music.strip())
+    return "\n\n".join(sections)
+
+
+# ── Guard, conditioner ───────────────────────────────────────────────────────
+
+
+def check_prompt(prompt: str) -> None:
+    """The NCII guard. Every request here carries an uploaded image, so every request is checked; it runs before the
+    conditioner call and the denoise booking, so a refused prompt costs no GPU time on either half."""
+    import ncii_guard
+
+    try:
+        flag = ncii_guard.classify(prompt)
+    except Exception as error:
+        traceback.print_exc()
+        raise gr.Error(f"The content filter is unavailable (`{type(error).__name__}`), so nothing was run.")
+    if flag["label"] == "ncii":
+        print(f"[guard] prompt refused (ncii {flag['score']:.2f})", flush=True)
+        raise gr.Error("This prompt was flagged by a content filter and wasn't run.")
+
+
+@cache
+def conditioner():
+    """The other half, over the gradio API. `gradio_client` attaches the caller's own ZeroGPU token per call, so the
+    conditioner's booking is billed to whoever asked for the video."""
+    from gradio_client import Client
+
+    return Client(CONDITIONER_SPACE)
+
+
+def encode_remote(prompt, image_paths, canvas, num_frames):
+    """`/encode_ref2va` on the conditioner Space: a safetensors file holding `prompt_embeds` + `text_token_tags`, with
+    the resolved `height` / `width` / `num_frames` in its metadata, plus the plan.
+
+    `canvas` is the label. `media` and `kinds` are parallel and ordered; the references go over because `ref2va`'s
+    presentation puts a vision block in front of the prompt for every image.
+    """
+    from gradio_client import handle_file
+    from safetensors import safe_open
+
+    path, plan = conditioner().predict(
+        prompt=prompt,
+        media=[handle_file(image) for image in image_paths],
+        kinds=",".join("image" for _ in image_paths),
+        canvas=canvas,
+        num_frames=num_frames,
+        rewrite_prompt=False,
+        api_name="/encode_ref2va",
+    )
+    with safe_open(path, framework="pt") as handle:
+        return handle.get_tensor("prompt_embeds"), handle.get_tensor("text_token_tags"), handle.metadata(), plan
+
+
+# ── Inference ────────────────────────────────────────────────────────────────
+
+
+@spaces.GPU(duration=get_duration, size=GPU_SIZE)
+def _generate(prompt_embeds, text_token_tags, image_paths, height, width, num_frames, steps, weight, seed):
+    """The only thing on GPU time: the reference encoder, the packed-sequence denoise loop and the decoders.
+
+    References cross as paths and are decoded here; only the generated outputs come back. A `@spaces.GPU` argument
+    crosses a process boundary by pickling, and expanded reference frames are large.
+    """
+    from diffusers.modular_pipelines.minimax_h3 import MiniMaxH3ImageReference
+
+    import h3_fbc
+
+    if PLACEMENT == "lazy":
+        PIPE.to("cuda")
+
+    # The whole reason the adapter is not folded into the weights: strength is a per-request scale on the LoRA layers.
+    PIPE.transformer_ref.set_adapters([ADAPTER], [float(weight)])
+
+    with h3_fbc.enabled(PIPE.transformer_ref, steps=int(steps)):
+        state = PIPE(
+            prompt_embeds=prompt_embeds.to("cuda"),
+            text_token_tags=text_token_tags,
+            references=[MiniMaxH3ImageReference.from_file(path) for path in image_paths],
+            height=height,
+            width=width,
+            num_frames=num_frames,
+            num_inference_steps=int(steps),
+            generator=torch.Generator("cpu").manual_seed(int(seed)),
+        )
+    return state.get("videos")[0], state.get("audio")[0].cpu(), state.get("sampling_rate")
+
+
+def generate(
+    # The first nine are the columns `gr.Examples` varies, and they lead the signature for that reason: an example row
+    # is applied to `inputs` positionally. Every parameter has a default, which is what lets a nine-column row call
+    # this at all.
+    action="",
+    picture_1=None,
+    role_1="Character",
+    detail_1="",
+    picture_2=None,
+    role_2="Environment",
+    detail_2="",
+    camera=DEFAULT_CAMERA,
+    hud=True,
+    picture_3=None,
+    role_3="Creature / Boss",
+    detail_3="",
+    canvas=DEFAULT_CANVAS,
+    duration=5,
+    steps=DEFAULT_STEPS,
+    weight=DEFAULT_WEIGHT,
+    seed=DEFAULT_SEED,
+    soundscape=DEFAULT_SOUNDSCAPE,
+    music=DEFAULT_MUSIC,
+    override="",
+    progress=gr.Progress(track_tqdm=True),
+):
+    """One request: compose the structured prompt, condition it remotely, denoise here."""
+    if LOAD_ERROR:
+        raise gr.Error(LOAD_ERROR)
+    if PIPE is None:
+        raise gr.Error("The denoiser is still loading.")
+
+    from diffusers.utils import encode_video
+
+    references = collect_slots(
+        [(picture_1, role_1, detail_1), (picture_2, role_2, detail_2), (picture_3, role_3, detail_3)]
+    )
+    if not references:
+        raise gr.Error("Add at least one reference sheet — a character, an environment or a creature.")
+    if not (override or "").strip() and not (action or "").strip():
+        raise gr.Error("Write one line of action, or paste a full structured prompt in the advanced options.")
+
+    num_frames = snap_frames(duration)
+    prompt = (override or "").strip() or compose_prompt(
+        references, action, camera, hud, soundscape, music, num_frames / FPS
+    )
+    check_prompt(prompt)
+
+    image_paths = [path for path, _, _ in references]
+    progress(0.0, desc="Reading the prompt and the reference sheets ...")
+    conditioned = time.time()
+    try:
+        prompt_embeds, text_token_tags, metadata, plan = encode_remote(prompt, image_paths, canvas, num_frames)
+    except gr.Error:
+        raise
+    except Exception as error:
+        # gradio only puts the exception *type* on the wire, so the useful half of a conditioner-side failure is in
+        # that Space's logs.
+        traceback.print_exc()
+        raise gr.Error(
+            f"The conditioner ({CONDITIONER_SPACE}) failed with `{type(error).__name__}: {error}`. "
+            "Its logs carry the full traceback."
+        ) from error
+    condition_seconds = time.time() - conditioned
+    height, width, num_frames = (int(metadata[key]) for key in ("height", "width", "num_frames"))
+
+    progress(0.1, desc=f"Rendering {num_frames / FPS:.1f} s at {width}x{height} ...")
+    started = time.time()
+    frames, audio, sampling_rate = _generate(
+        prompt_embeds, text_token_tags, image_paths, height, width, num_frames, steps, weight, seed
+    )
+    generate_seconds = time.time() - started
+
+    directory = os.path.join(tempfile.gettempdir(), "h3-outputs")
+    os.makedirs(directory, exist_ok=True)
+    path = os.path.join(directory, f"h3-tpv-{int(time.time() * 1000)}.mp4")
+    encode_video(frames, fps=FPS, output_path=path, audio=audio, audio_sample_rate=sampling_rate)
+
+    print(
+        f"[{VERSION}] {len(image_paths)} references · {width}x{height}, {num_frames} frames "
+        f"({num_frames / FPS:.3f} s), {int(steps)} steps, weight {float(weight):g} · conditioner "
+        f"{condition_seconds:.0f}s ({plan['num_text_tokens']} tokens) · denoise + decode {generate_seconds:.0f}s "
+        f"({generate_seconds / int(steps):.1f} s/step) · seed {int(seed)}",
+        flush=True,
+    )
+    return path, prompt
+
+
+# ── UI ───────────────────────────────────────────────────────────────────────
+
+try:
+    import ncii_guard
+
+    ncii_guard.start()
+except Exception as guard_error:  # the guard revives itself per request; a cold cache should not fail the boot
+    print(f"[guard] start failed ({type(guard_error).__name__}: {guard_error}); it will be retried per request")
+load_models()
+
+INTRO = """# MiniMax-H3 · Third-Person View LoRA
+
+<div align="center">
+  <a href="https://huggingface.co/WarmBloodAban/Minimax_H3_LoRAs" target="_blank" rel="noopener"><strong>[ LoRA ]</strong></a> &nbsp;
+  <a href="https://huggingface.co/MiniMaxAI/MiniMax-H3" target="_blank" rel="noopener"><strong>[ base model ]</strong></a> &nbsp;
+  <a href="https://huggingface.co/spaces/multimodalart/minimax-h3-reference" target="_blank" rel="noopener"><strong>[ base demo ]</strong></a>
+</div>
+
+**Game cutscenes out of design reference sheets.** Label each sheet you upload, write one line of action, pick a
+camera, and this composes MiniMax-H3's structured prompt around the LoRA's own vocabulary — third-person
+over-the-shoulder / spring-arm tracking, first-person POV, whip-pan transitions, target-lock reticles and Boss health
+bars — then renders the clip **with its synchronized soundtrack** in a single denoising pass.
+"""
+
+CSS = """
+.main.fillable { max-width: 1250px !important; }
+.dark .gradio-container { color: var(--body-text-color); }
+"""
+
+with gr.Blocks(title="MiniMax-H3 · Third-Person View LoRA", theme=gr.themes.Citrus(), css=CSS) as demo:
+    gr.Markdown(INTRO)
+    if LOAD_ERROR:
+        gr.Markdown(LOAD_ERROR)
+
+    with gr.Row():
+        with gr.Column():
+            gr.Markdown("### 1 · Reference sheets — they become `<Picture 1..3>`, in this order")
+            pictures, roles, details, slot_columns = [], [], [], []
+            with gr.Row():
+                for index in range(MAX_IMAGE_SLOTS):
+                    with gr.Column(min_width=180, visible=index < OPEN_IMAGE_SLOTS) as column:
+                        pictures.append(
+                            gr.Image(label=f"Picture {index + 1}", type="filepath", height=190, show_label=True)
+                        )
+                        roles.append(
+                            gr.Dropdown(
+                                label="Role",
+                                choices=list(ROLES),
+                                value="Character" if index == 0 else ("Environment" if index == 1 else "Creature / Boss"),
+                                container=True,
+                            )
+                        )
+                        details.append(
+                            gr.Textbox(
+                                label="What's in it",
+                                lines=2,
+                                placeholder="the mint-green cat mecha with a tattered beige cape",
+                            )
+                        )
+                    slot_columns.append(column)
+            add_slot = gr.Button("+ Add a third reference sheet", size="sm", variant="secondary")
+
+            action = gr.Textbox(
+                label="2 · What happens in the shot",
+                lines=2,
+                placeholder="dodges a leaping wyvern attack, counterattacks with an energy-blade combo, then parries "
+                "a wing-claw swipe",
+            )
+            with gr.Row():
+                camera = gr.Dropdown(label="3 · Camera", choices=list(CAMERAS), value=DEFAULT_CAMERA, scale=3)
+                hud = gr.Checkbox(label="Combat HUD overlay", value=True, scale=1)
+            run = gr.Button("Render the cutscene", variant="primary")
+            estimate = gr.Markdown(estimate_label(DEFAULT_CANVAS, 5, DEFAULT_STEPS, None))
+
+            with gr.Accordion("Advanced options", open=False):
+                weight = gr.Slider(
+                    label="LoRA weight (the card recommends 0.6–0.85)",
+                    minimum=WEIGHT_MIN,
+                    maximum=WEIGHT_MAX,
+                    step=0.05,
+                    value=DEFAULT_WEIGHT,
+                )
+                canvas = gr.Dropdown(label="Canvas", choices=list(CANVASES), value=DEFAULT_CANVAS)
+                duration = gr.Slider(
+                    label="Duration (s)", minimum=MIN_DURATION, maximum=MAX_UI_DURATION, step=1, value=5
+                )
+                steps = gr.Slider(label="Steps", minimum=10, maximum=40, step=1, value=DEFAULT_STEPS)
+                seed = gr.Number(label="Seed", value=DEFAULT_SEED, precision=0)
+                soundscape = gr.Textbox(label="Diegetic soundscape", lines=2, value=DEFAULT_SOUNDSCAPE)
+                music = gr.Textbox(label="Non-diegetic music", lines=2, value=DEFAULT_MUSIC)
+                override = gr.Textbox(
+                    label="Write the structured prompt myself (overrides everything above)",
+                    lines=6,
+                    placeholder="subject_definitions:\n<Subject 1> is ... from <Picture 1>.\n\nsummary:\n"
+                    "[reference generation] A 10-second photorealistic third-person ...",
+                )
+
+        with gr.Column():
+            result = gr.Video(label="Cutscene + soundtrack")
+            with gr.Accordion("Structured prompt sent to MiniMax-H3", open=False):
+                prompt_view = gr.Textbox(show_label=False, lines=18, interactive=False)
+
+    open_slots = gr.State(OPEN_IMAGE_SLOTS)
+
+    def reveal_slot(open_count):
+        open_count = min(open_count + 1, MAX_IMAGE_SLOTS)
+        return [
+            open_count,
+            *[gr.update(visible=index < open_count) for index in range(MAX_IMAGE_SLOTS)],
+            gr.update(visible=open_count < MAX_IMAGE_SLOTS),
+        ]
+
+    add_slot.click(reveal_slot, open_slots, [open_slots, *slot_columns, add_slot], api_name=False)
+
+    for control in (canvas, duration, steps, *pictures):
+        control.change(
+            estimate_label,
+            [canvas, duration, steps, *pictures],
+            estimate,
+            show_progress="hidden",
+            api_name=False,
+        )
+
+    request = [
+        action,
+        pictures[0],
+        roles[0],
+        details[0],
+        pictures[1],
+        roles[1],
+        details[1],
+        camera,
+        hud,
+        pictures[2],
+        roles[2],
+        details[2],
+        canvas,
+        duration,
+        steps,
+        weight,
+        seed,
+        soundscape,
+        music,
+        override,
+    ]
+    exampled = request[:9]
+
+    gr.Examples(
+        examples=[
+            [
+                "dodges a leaping wyvern attack, counterattacks with a glowing energy-blade combo, then parries a "
+                "wing-claw swipe in a shower of sparks",
+                "examples/katana_character.jpg",
+                "Character",
+                "the young woman with long black hair in two buns, blue eyes, a black mouth mask, an orange utility "
+                "jacket and two white-corded katana hilts rising behind her shoulders",
+                "examples/ruined_village.jpg",
+                "Environment",
+                "the foggy ruined village street with wooden houses, a glowing paper lantern, blood-red spider "
+                "lilies and wet stone paving",
+                "Third-person · over-the-shoulder",
+                True,
+            ],
+            [
+                "plants her feet into a combat stance and charges an ultimate finisher as the pale wyvern staggers "
+                "and opens its ring-like tooth-lined maw",
+                "examples/katana_character.jpg",
+                "Character",
+                "the young woman with long black hair in two buns, an orange utility jacket and two katana hilts "
+                "rising behind her shoulders",
+                "examples/wyvern_boss.jpg",
+                "Creature / Boss",
+                "the pale eyeless wyvern with a circular ring-like maw lined with rows of sharp teeth, a long "
+                "muscular neck, clawed wings and heavy bipedal limbs",
+                "Whip-pan: third-person → first-person",
+                True,
+            ],
+            [
+                "sprints across a rain-slick rooftop, vaults a neon billboard gap and lands into a slide while "
+                "tracer fire streaks past",
+                "examples/doorway_character.jpg",
+                "Character",
+                "the young girl with brown hair, a white shirt and skirt and a guitar case slung across her back",
+                "examples/night_city.jpg",
+                "Environment",
+                "the night city of lit high-rise towers and a faceted glass skyscraper reflected in the dark river "
+                "below",
+                "First-person POV (FPV)",
+                True,
+            ],
+        ],
+        inputs=exampled,
+        outputs=[result, prompt_view],
+        fn=generate,
+        cache_examples=True,
+        cache_mode="lazy",
+    )
+
+    run.click(generate, request, [result, prompt_view], api_name="generate")
+
+
+if __name__ == "__main__":
+    demo.launch(show_error=True, max_threads=1000)

h3_fbc.py

@@ -0,0 +1,357 @@
+"""First-block cache for MiniMax-H3: skip the trunk on steps whose block-0 residual barely moved.
+
+Block 0 and the final AdaLN head run at the true timestep on **every** step; only blocks 1..49 are skipped, and only
+while the residual they would have been handed looks like the one from the last step that actually ran. The decision
+signal is the relative L1 between this step's block-0 residual (`block0_out - block0_in`) and the residual of the last
+*computed* step, over the whole packed sequence. On a skip the trunk's contribution is replayed as a cached residual,
+`(final_trunk_out - block0_out)` of that computed step.
+
+Ported from `duckyshell/ComfyUI-MiniMaxH3-FirstBlockCache` (`nodes.py` @ 725973c) — same signal, same protected window
+(10%-95% of the schedule, converted through the video shift of 12.0) and the same cap of two consecutive skips, which
+is their "H3 Safe" preset at threshold 0.08.
+
+**The audio exemption is not theirs.** duckyshell has no audio term anywhere: the decision is ~98% video by row count
+and every audio row rides the stale trunk residual, which is what costs the soundtrack its energy. Audio runs its own
+schedule (shift 3 against video's 12, diverging by up to 11x in rate across 20 steps), so on a skip the audio rows of
+the trunk output are instead a 2-point **linear** extrapolation of the last two actually-computed audio features, in
+the audio sigma coordinate — `xmarre/ComfyUI-Spectrum-MiniMax-H3`'s `audio_blend_weight=0.0` path, applied where
+Spectrum applies it (the post-trunk hidden feature, ahead of the head that still runs at the true timestep) and fixed
+to the right coordinate. Following ComfyUI PR #15390, no carried audio tensor is ever mutated: every write is a fresh
+tensor out of `index_copy`.
+
+It earns its place. Running this Space's own request at threshold 0.08 with `H3_FBC_AUDIO_EXEMPT=0` — the duckyshell
+mechanism verbatim, same 13 skipped forwards, same video to within 0.2 dB — costs the soundtrack **16.7% of its RMS**
+(0.0483 against an uncached 0.0580), while the exemption holds it at 1.04x. That is the same direction the offline
+study measured on a near-silent clip, three times the size on one with real audio energy.
+
+**A threshold does not travel across step counts.** The signature shrinks as the schedule is subdivided, so the same
+number gates far more loosely at more steps. Measured on this Space — 960x544, 124 frames, one image reference,
+seed 42, AoTI blocks, at its **default 28 steps** (27 forwards) — against the same request with `H3_FBC=0`:
+
+| threshold | skipped | denoise loop | end to end | audio RMS vs uncached |
+|---|---|---|---|---|
+| 0.03 | 0 / 27 | 1.02x | 1.06x | 1.000 (bitwise-identical audio) |
+| 0.05 | 9 / 27 | 1.46x | 1.36x | 0.956 |
+| 0.08 | 13 / 27 | 2.19x | 1.82x | 1.040 |
+
+The offline study calibrated 0.08 over a 20-step schedule, where it skipped 7 of 19 forwards. At 28 steps that same
+0.08 skips 13 of 27 — nearly half — and the sampled video visibly re-rolls its background detail. **0.05 is the
+default** because it reproduces the skip fraction that study validated (33% here against 37% there); 0.08 is the
+aggressive setting. Below the signature floor — 0.03 skipped nothing at all here — a threshold buys nothing and still
+pays for the signature, so lower is not safer, it is just slower.
+
+A cached request is not the uncached one: the trajectory moves, so the video is a different sample of the same prompt
+(same shot, same subject, same quality — different signage and background detail). `H3_FBC=0` restores today's output
+exactly, and is worth reaching for when a request has to reproduce a specific earlier result.
+
+This composes with `h3_aoti`: that module patches each of the 50 blocks' own `forward` and they stay a real
+`ModuleList`, so skipping the trunk simply does not call blocks 1..49 that step. `LazyAOTIModel` rebinds its constants
+whenever the weights dict it is handed changes identity, and the first forward of a request never skips, so every
+block has bound its own weights before any step is cached.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import os
+import types
+
+ENABLED = os.environ.get("H3_FBC", "1") == "1"
+# Relative-L1 gate on the block-0 residual, calibrated at this Space's default 28 steps — see the table above.
+THRESHOLD = float(os.environ.get("H3_FBC_THRESHOLD", "0.05"))
+# duckyshell's cap. Without it the gate compares against an ever-older computed step and drifts away unbounded.
+MAX_CONSECUTIVE_HITS = int(os.environ.get("H3_FBC_MAX_CONSECUTIVE", "2"))
+# The protected head and tail of the schedule, as fractions, converted to sigma through the video shift below.
+START_PERCENT = float(os.environ.get("H3_FBC_START_PERCENT", "0.10"))
+END_PERCENT = float(os.environ.get("H3_FBC_END_PERCENT", "0.95"))
+# `MiniMaxH3SetTimestepsStep` builds the video schedule at shift 12.0 and the audio one at 3.0.
+VIDEO_SHIFT = float(os.environ.get("H3_FBC_VIDEO_SHIFT", "12.0"))
+AUDIO_EXEMPT = os.environ.get("H3_FBC_AUDIO_EXEMPT", "1") == "1"
+
+# Every keyword `MiniMaxH3LoopDenoiser` passes. It filters the packed-sequence layout through
+# `inspect.signature(transformer.forward).parameters`, so a replacement forward that drops a name silently stops
+# receiving it; `install` refuses rather than let that happen quietly.
+FORWARD_PARAMETERS = (
+    "hidden_states",
+    "audio_hidden_states",
+    "encoder_hidden_states",
+    "timestep",
+    "timestep_indices",
+    "token_tags",
+    "position_ids",
+    "video_indices",
+    "audio_indices",
+    "text_indices",
+    "attention_kwargs",
+    "return_dict",
+)
+
+
+def status() -> str:
+    return (
+        f"first-block cache **on** · threshold `{THRESHOLD}` · audio exemption "
+        f"{'on' if AUDIO_EXEMPT else 'off'}"
+        if ENABLED
+        else "first-block cache **off** (`H3_FBC=1` to skip the trunk on steady steps)"
+    )
+
+
+def _shifted_sigma(u: float, shift: float) -> float:
+    return shift * u / (1.0 + (shift - 1.0) * u)
+
+
+def _rel_l1(current, previous) -> float:
+    numerator = (current.float() - previous.float()).abs().mean()
+    denominator = previous.float().abs().mean().clamp(min=1e-8)
+    return float((numerator / denominator).item())
+
+
+class _State:
+    def __init__(self, threshold: float, steps: int, audio_exempt: bool):
+        self.threshold = threshold
+        self.steps = steps
+        self.audio_exempt = audio_exempt
+        # duckyshell reads the window as sigma bounds: a flow model's sigma at `u = 1 - percent`, shifted.
+        self.start_sigma = _shifted_sigma(1.0 - START_PERCENT, VIDEO_SHIFT)
+        self.end_sigma = _shifted_sigma(1.0 - END_PERCENT, VIDEO_SHIFT)
+        self.original = None
+        self.failed = False
+        self.consecutive_hits = 0
+        self.prev_first_residual = None
+        self.tail_residual = None
+        self.audio_history = []  # [(sigma_audio, audio rows of the trunk output)], newest last, at most two
+        self.computed = 0
+        self.skipped = 0
+
+
+def _cached_forward(
+    self,
+    state,
+    hidden_states,
+    audio_hidden_states,
+    encoder_hidden_states,
+    timestep,
+    timestep_indices,
+    token_tags,
+    position_ids,
+    video_indices,
+    audio_indices,
+    text_indices,
+    return_dict,
+):
+    """`MiniMaxH3Transformer3DModel.forward` with the block loop split at block 0.
+
+    Everything outside the loop is that method verbatim, at the `diffusers` commit `requirements.txt` pins; keep the
+    two in step when the pin moves.
+    """
+    import torch
+
+    from diffusers.models.transformers.transformer_minimax_h3 import (
+        MINIMAX_H3_MODALITY_NUM,
+        MiniMaxH3TransformerOutput,
+    )
+
+    sequence_length = position_ids.shape[0]
+    rotary_emb = self.rope(position_ids)
+
+    video_embeds = self.proj_in(hidden_states.to(self.proj_in.weight.dtype))
+    audio_embeds = self.audio_proj_in(audio_hidden_states.to(self.audio_proj_in.weight.dtype))
+    text_embeds = self.context_embedder(encoder_hidden_states.to(self.context_embedder.weight.dtype))
+    text_embeds = self.token_refiner(text_embeds)
+
+    packed = text_embeds.new_zeros((text_embeds.shape[0], sequence_length, text_embeds.shape[-1]))
+    packed = packed.index_copy(1, text_indices, text_embeds)
+    packed = packed.index_copy(1, video_indices, video_embeds.to(text_embeds.dtype))
+    packed = packed.index_copy(1, audio_indices, audio_embeds.to(text_embeds.dtype))
+
+    temb = self.time_proj(timestep)
+    temb = self.time_embedder(temb.to(self.time_embedder.linear_1.weight.dtype))
+    adaln_indices = timestep_indices * MINIMAX_H3_MODALITY_NUM + token_tags.clamp(min=0)
+
+    attention_mask = None
+    is_pad = token_tags < 0
+    if bool(is_pad.any()):
+        attention_mask = is_pad[None, :] == is_pad[:, None]
+
+    blocks = self.transformer_blocks
+    block0_out = blocks[0](packed, temb, adaln_indices, rotary_emb, attention_mask)
+    first_residual = block0_out - packed
+
+    # The generated rows trail their modality's index list, so the last row of each carries that stream's live noise
+    # level. The scheduler exposes `timesteps = 1 - sigmas[:-1]`.
+    sigma_video = 1.0 - float(timestep[timestep_indices[video_indices[-1]]].item())
+    sigma_audio = 1.0 - float(timestep[timestep_indices[audio_indices[-1]]].item())
+
+    use_cache = False
+    if (
+        state.prev_first_residual is not None
+        and state.tail_residual is not None
+        and state.prev_first_residual.shape == first_residual.shape
+        and state.consecutive_hits < MAX_CONSECUTIVE_HITS
+        and state.end_sigma <= sigma_video <= state.start_sigma
+    ):
+        use_cache = _rel_l1(first_residual, state.prev_first_residual) <= state.threshold
+
+    if use_cache:
+        state.consecutive_hits += 1
+        state.skipped += 1
+        trunk_out = block0_out + state.tail_residual
+        if state.audio_exempt and state.audio_history:
+            sigma_prev, feature_prev = state.audio_history[-1]
+            if len(state.audio_history) == 2 and abs(sigma_prev - state.audio_history[-2][0]) > 1e-8:
+                sigma_prev2, feature_prev2 = state.audio_history[-2]
+                ratio = (sigma_audio - sigma_prev) / (sigma_prev - sigma_prev2)
+                audio_feature = feature_prev + (feature_prev - feature_prev2) * ratio
+            else:
+                audio_feature = feature_prev
+            trunk_out = trunk_out.index_copy(1, audio_indices, audio_feature.to(trunk_out.dtype))
+    else:
+        state.consecutive_hits = 0
+        state.computed += 1
+        trunk_out = block0_out
+        for block in blocks[1:]:
+            trunk_out = block(trunk_out, temb, adaln_indices, rotary_emb, attention_mask)
+        state.tail_residual = (trunk_out - block0_out).detach()
+        state.prev_first_residual = first_residual.detach()
+        if state.audio_exempt:
+            state.audio_history.append((sigma_audio, trunk_out.index_select(1, audio_indices).detach().float()))
+            state.audio_history = state.audio_history[-2:]
+
+    out = self.norm_out(trunk_out, temb, timestep_indices).to(self.proj_out.weight.dtype)
+    video_output = self.proj_out(out).index_select(1, video_indices)
+    audio_output = self.audio_proj_out(out).index_select(1, audio_indices)
+
+    if not return_dict:
+        return (video_output, audio_output)
+    return MiniMaxH3TransformerOutput(sample=video_output, audio_sample=audio_output)
+
+
+def _forward(
+    self,
+    hidden_states,
+    audio_hidden_states,
+    encoder_hidden_states,
+    timestep,
+    timestep_indices,
+    token_tags,
+    position_ids,
+    video_indices,
+    audio_indices,
+    text_indices,
+    attention_kwargs=None,
+    return_dict: bool = True,
+):
+    """The installed forward. Anything it cannot serve — a LoRA scale, an unexpected layout, a bug — is handed to the
+    original forward instead, for this call and every later one, so a cached request can degrade to an uncached one but
+    never to a failed one."""
+    state = self._h3_fbc
+    original = dict(
+        hidden_states=hidden_states,
+        audio_hidden_states=audio_hidden_states,
+        encoder_hidden_states=encoder_hidden_states,
+        timestep=timestep,
+        timestep_indices=timestep_indices,
+        token_tags=token_tags,
+        position_ids=position_ids,
+        video_indices=video_indices,
+        audio_indices=audio_indices,
+        text_indices=text_indices,
+        attention_kwargs=attention_kwargs,
+        return_dict=return_dict,
+    )
+    # `apply_lora_scale` decorates the real forward and this one is not it, so a request that actually scales a LoRA
+    # goes down the original path rather than silently losing its scale.
+    if state.failed or (attention_kwargs or {}).get("scale") is not None:
+        return state.original(**original)
+    try:
+        return _cached_forward(
+            self,
+            state,
+            hidden_states,
+            audio_hidden_states,
+            encoder_hidden_states,
+            timestep,
+            timestep_indices,
+            token_tags,
+            position_ids,
+            video_indices,
+            audio_indices,
+            text_indices,
+            return_dict,
+        )
+    except Exception as error:
+        state.failed = True
+        print(f"[h3-fbc] disabled for this request ({type(error).__name__}: {error}); running uncached", flush=True)
+        return state.original(**original)
+
+
+def install(transformer, steps: int = 0, threshold: float = THRESHOLD, audio_exempt: bool = AUDIO_EXEMPT) -> bool:
+    """Bind the caching forward onto `transformer`. Returns whether it went on.
+
+    `accelerate`'s `add_hook_to_module` — what `ComponentsManager.enable_auto_cpu_offload` installs — moves the real
+    forward to `_old_forward` and puts its own onload wrapper in `forward`. Replacing `forward` there would step over
+    the wrapper and run the block stack against weights still on the host, so the replacement goes into `_old_forward`
+    whenever the hook is present.
+    """
+    import inspect
+
+    if getattr(transformer, "_h3_fbc", None) is not None:
+        return True
+
+    hooked = hasattr(transformer, "_hf_hook") and hasattr(transformer, "_old_forward")
+    current = transformer._old_forward if hooked else transformer.forward
+    missing = [name for name in FORWARD_PARAMETERS if name not in inspect.signature(current).parameters]
+    if missing:
+        print(f"[h3-fbc] this transformer's forward has no {missing}; running uncached", flush=True)
+        return False
+    if not hasattr(transformer, "transformer_blocks") or len(transformer.transformer_blocks) < 2:
+        print("[h3-fbc] no block stack to skip; running uncached", flush=True)
+        return False
+
+    state = _State(threshold, steps, audio_exempt)
+    state.original = current
+    transformer._h3_fbc = state
+    bound = types.MethodType(_forward, transformer)
+    if hooked:
+        transformer._old_forward = bound
+    else:
+        transformer.forward = bound
+    return True
+
+
+def uninstall(transformer) -> None:
+    state = getattr(transformer, "_h3_fbc", None)
+    if state is None:
+        return
+    if hasattr(transformer, "_hf_hook") and hasattr(transformer, "_old_forward"):
+        transformer._old_forward = state.original
+    else:
+        transformer.__dict__.pop("forward", None)
+    del transformer._h3_fbc
+    total = state.computed + state.skipped
+    if total:
+        print(
+            f"[h3-fbc] {state.skipped}/{total} forwards served from cache "
+            f"(threshold {state.threshold}, audio exemption {'on' if state.audio_exempt else 'off'})",
+            flush=True,
+        )
+
+
+@contextlib.contextmanager
+def enabled(transformer, steps: int = 0):
+    """Cache the trunk for the duration of one request. The state is per-request by construction — a residual only ever
+    means something within the schedule it was measured on — and nothing in here can raise into the request."""
+    installed = False
+    if ENABLED:
+        try:
+            installed = install(transformer, steps=steps)
+        except Exception as error:
+            print(f"[h3-fbc] install failed ({type(error).__name__}: {error}); running uncached", flush=True)
+    try:
+        yield installed
+    finally:
+        if installed:
+            try:
+                uninstall(transformer)
+            except Exception as error:
+                print(f"[h3-fbc] uninstall failed ({type(error).__name__}: {error})", flush=True)

h3_split_blocks.py

@@ -0,0 +1,147 @@
+"""The halves of a **split** MiniMax-H3 deployment, for both of its checkpoint partitions.
+
+MiniMax-H3 is 195.9 GiB in bfloat16 and a ZeroGPU Space is evicted at 150 GB of storage, so `MiniMaxH3Blocks` is cut
+at its `text_encoder` step: the 62.14 GiB Qwen3-VL runs in the conditioner Space, everything else in a generator
+Space, and `prompt_embeds` + `text_token_tags` is the whole wire format between them.
+
+`resize` / `setup` run on **both** sides: they own no pretrained component, and each half needs the canvas and the
+prepared keyframes or normalized references. Both conditioner halves also return the resolved `height` / `width` /
+`num_frames`, which the generating half pins rather than re-deriving.
+
+Two things the blocks leave to the caller: a keyframe reaches them EXIF-transposed and in RGB, and the `t2va` / `fl2va`
+frame count is aligned to `17 * n + 5` before the call, since that arithmetic lives on the denoising side of the cut.
+"""
+
+from diffusers.modular_pipelines.minimax_h3.before_encoder import MiniMaxH3Ref2VASetupStep
+from diffusers.modular_pipelines.minimax_h3.decoders import MiniMaxH3AfterDenoiseStep
+from diffusers.modular_pipelines.minimax_h3.encoders import (
+    MiniMaxH3Ref2VAReferenceEncoderStep,
+    MiniMaxH3Ref2VATextEncoderStep,
+    MiniMaxH3TextEncoderStep,
+)
+from diffusers.modular_pipelines.minimax_h3.modular_blocks_minimax_h3 import (
+    MiniMaxH3AutoKeyframeVaeEncoderStep,
+    MiniMaxH3AutoResizeStep,
+    MiniMaxH3CoreDenoiseStep,
+    MiniMaxH3DecodeStep,
+    MiniMaxH3Ref2VACoreDenoiseStep,
+    _generation_outputs,
+)
+from diffusers.modular_pipelines.modular_pipeline import SequentialPipelineBlocks
+from diffusers.modular_pipelines.modular_pipeline_utils import OutputParam
+
+
+def _wire_outputs(num_frames: bool = True) -> list[OutputParam]:
+    """The wire format of the split. `num_frames` is declared by the `ref2va` half alone, whose setup resolves one."""
+    return [
+        OutputParam.template("prompt_embeds"),
+        OutputParam("text_token_tags", description="The per-row modality tag of every row of `prompt_embeds`."),
+        OutputParam("height", type_hint=int, description="Resolved height of the generated video in pixels."),
+        OutputParam("width", type_hint=int, description="Resolved width of the generated video in pixels."),
+        *(
+            [OutputParam("num_frames", type_hint=int, description="Resolved number of frames, of the form 17 * n + 5.")]
+            if num_frames
+            else []
+        ),
+    ]
+
+
+class MiniMaxH3ConditionerBlocks(SequentialPipelineBlocks):
+    """The conditioner half of a split MiniMax-H3: the keyframes on the canvas plus the Qwen3-VL read at layer 50."""
+
+    model_name = "minimax-h3"
+    block_classes = [MiniMaxH3AutoResizeStep, MiniMaxH3TextEncoderStep]
+    block_names = ["resize", "text_encoder"]
+
+    @property
+    def description(self):
+        return (
+            "The conditioner half of a split MiniMax-H3 deployment: puts the keyframes onto the target canvas and "
+            "encodes MiniMax-H3's presentation of the request into the `prompt_embeds` / `text_token_tags` pair the "
+            "denoising half consumes. The frame count is the caller's to align."
+        )
+
+    @property
+    def outputs(self):
+        return _wire_outputs(num_frames=False)
+
+
+class MiniMaxH3GeneratorBlocks(SequentialPipelineBlocks):
+    """The denoising half of a split MiniMax-H3: `MiniMaxH3Blocks` with its `text_encoder` step removed."""
+
+    model_name = "minimax-h3"
+    block_classes = [
+        MiniMaxH3AutoResizeStep,
+        MiniMaxH3AutoKeyframeVaeEncoderStep,
+        MiniMaxH3CoreDenoiseStep,
+        MiniMaxH3AfterDenoiseStep,
+        MiniMaxH3DecodeStep,
+    ]
+    block_names = ["resize", "vae_encoder", "denoise", "after_denoise", "decode"]
+
+    @property
+    def description(self):
+        return (
+            "The denoising half of a split MiniMax-H3 deployment: the `t2va` / `fl2va` branch of `MiniMaxH3Blocks` "
+            "without its text-encoder step, so `prompt_embeds` and `text_token_tags` come in as inputs and the "
+            "62.14 GiB Qwen3-VL conditioner is never loaded here."
+        )
+
+    @property
+    def outputs(self):
+        return _generation_outputs()
+
+
+class MiniMaxH3Ref2VAConditionerBlocks(SequentialPipelineBlocks):
+    """The conditioner half of a split `ref2va`: the resolved plan plus the Qwen3-VL read at its 50th layer.
+
+    Component for component this is `MiniMaxH3ConditionerBlocks`, so one conditioner Space serves both partitions.
+    What differs is the presentation: `ref2va` prepends a label per reference and a vision block per image and per
+    merged video frame pair, so the references themselves have to reach this half.
+    """
+
+    model_name = "minimax-h3"
+    block_classes = [MiniMaxH3Ref2VASetupStep, MiniMaxH3Ref2VATextEncoderStep]
+    block_names = ["setup", "text_encoder"]
+
+    @property
+    def description(self):
+        return (
+            "The conditioner half of a split MiniMax-H3 `ref2va` deployment: resolves the request plan (canvas, frame "
+            "count, references normalized onto MiniMax-H3's own rates and resolutions) and encodes MiniMax-H3's "
+            "presentation of it into the `prompt_embeds` / `text_token_tags` pair the denoising half consumes."
+        )
+
+    @property
+    def outputs(self):
+        return _wire_outputs()
+
+
+class MiniMaxH3Ref2VAGeneratorBlocks(SequentialPipelineBlocks):
+    """The denoising half of a split `ref2va`: the `ref2va` branch with its `text_encoder` step removed.
+
+    `reference_encoder` stays here, next to the two autoencoders it runs: its output shapes are where every reference
+    block's geometry in the packed layout comes from.
+    """
+
+    model_name = "minimax-h3"
+    block_classes = [
+        MiniMaxH3Ref2VASetupStep,
+        MiniMaxH3Ref2VAReferenceEncoderStep,
+        MiniMaxH3Ref2VACoreDenoiseStep,
+        MiniMaxH3AfterDenoiseStep,
+        MiniMaxH3DecodeStep,
+    ]
+    block_names = ["setup", "reference_encoder", "denoise", "after_denoise", "decode"]
+
+    @property
+    def description(self):
+        return (
+            "The denoising half of a split MiniMax-H3 `ref2va` deployment: the `ref2va` branch of `MiniMaxH3Blocks` "
+            "without its text-encoder step, so `prompt_embeds` and `text_token_tags` come in as inputs and the "
+            "62.14 GiB Qwen3-VL conditioner is never loaded here. The transformer is the `transformer_ref` partition."
+        )
+
+    @property
+    def outputs(self):
+        return _generation_outputs()

ncii_guard.py

@@ -0,0 +1,90 @@
+"""The NCII prompt guard, in its own process.
+
+[`hfmlsoc/ncii-light-guard-v01`](https://huggingface.co/hfmlsoc/ncii-light-guard-v01) is a 270M CPU text
+classifier scoring the NCII risk of an edit prompt. It cannot live in the main process: with it loaded there,
+every subsequent `@spaces.GPU` worker dies at `worker_init` with `RuntimeError: No CUDA GPUs are available` —
+the fork inherits whatever CUDA driver state the classifier's torch activity left behind, and a factory reboot
+does not clear it. It cannot be a `multiprocessing.spawn` child either: spawn re-imports the parent's main
+module, and on a Space that main module is `app.py` — the child would re-run the whole startup, `start()`
+included. So the classifier runs this file as a plain subprocess — a fresh interpreter that never sees `spaces`
+— and answers over stdin/stdout, one JSON object per line.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import select
+import subprocess
+import sys
+import threading
+
+GUARD_REPO = "hfmlsoc/ncii-light-guard-v01"
+
+_lock = threading.Lock()
+_process: subprocess.Popen | None = None
+
+
+def _read(timeout: float) -> dict:
+    readable, _, _ = select.select([_process.stdout], [], [], timeout)
+    if not readable:
+        raise TimeoutError(f"the guard did not answer within {timeout}s")
+    line = _process.stdout.readline()
+    if not line:
+        raise EOFError("the guard process died")
+    return json.loads(line)
+
+
+def _spawn() -> None:
+    global _process
+    _process = subprocess.Popen(
+        [sys.executable, os.path.abspath(__file__)],
+        stdin=subprocess.PIPE,
+        stdout=subprocess.PIPE,
+        text=True,
+        bufsize=1,
+    )
+    # Generous: a cold cache downloads the checkpoint first.
+    assert _read(300.0) == {"status": "ready"}
+
+
+def start() -> None:
+    """Launch the worker and block until its model is up. Called once at startup; `classify` revives it if it dies."""
+    with _lock:
+        _spawn()
+
+
+def classify(prompt: str, timeout: float = 60.0) -> dict:
+    """`{'label': 'safe' | 'ncii', 'score': ...}` for one prompt, replacing a dead or wedged worker once."""
+    with _lock:
+        for attempt in (0, 1):
+            try:
+                if _process is None or _process.poll() is not None:
+                    _spawn()
+                _process.stdin.write(json.dumps({"prompt": prompt}) + "\n")
+                _process.stdin.flush()
+                return _read(timeout)
+            except Exception:
+                if attempt:
+                    raise
+                if _process is not None and _process.poll() is None:
+                    _process.kill()
+
+
+def _serve() -> None:
+    """The child: plain torch on CPU. The protocol keeps the real stdout to itself — everything else
+    (download progress, warnings) is pushed over to stderr so it cannot corrupt a reply."""
+    protocol = os.fdopen(os.dup(1), "w", buffering=1)
+    os.dup2(2, 1)
+
+    from transformers import pipeline
+
+    classifier = pipeline("text-classification", model=GUARD_REPO, device="cpu")
+    protocol.write(json.dumps({"status": "ready"}) + "\n")
+    for line in sys.stdin:
+        result = classifier(json.loads(line)["prompt"], truncation=True)[0]
+        protocol.write(json.dumps({"label": result["label"], "score": float(result["score"])}) + "\n")
+
+
+if __name__ == "__main__":
+    _serve()

packages.txt

@@ -0,0 +1 @@
+ffmpeg

requirements.txt

@@ -0,0 +1,18 @@
+# diffusers from the MiniMax-H3 PR (https://github.com/huggingface/diffusers/pull/14371), pinned to a
+# commit on its minimax-h3-refactor branch — the modular MiniMax-H3 blocks are in no release yet, and
+# h3_split_blocks.py subclasses them. main has since renamed those block classes, so the pin is load-bearing.
+#   665f578278365ea4a3318cb8c9b66ce6c01204b9 = refs/pull/14371/head at the time of this deploy
+--extra-index-url https://download.pytorch.org/whl/cu130
+diffusers @ git+https://github.com/huggingface/diffusers.git@665f578278365ea4a3318cb8c9b66ce6c01204b9
+torch==2.11.0
+torchvision==0.26.0
+torchaudio==2.11.0
+transformers==5.8.0
+accelerate==1.14.0
+huggingface-hub==1.24.0
+peft
+av
+pillow
+numpy
+requests
+safetensors>=0.8.0