From 85ecb827ab9cf76ac4ea3aa793d7db047ed19a57 Mon Sep 17 00:00:00 2001
From: yiyixuxu <yixu310@gmail.com>
Date: Sun, 2 Aug 2026 17:17:31 +0000
Subject: [PATCH 01/16] Let the MiniMax-H3 video VAE encode a single frame

`encode` padded a lone frame up to `clip_length` by repeating it, ran the
temporal path over 17 copies and dropped `token_drop` latent frames, returning
two latent frames rather than one. That is why the blocks reached past it into
`_encode_clip` / `_encode`, which in turn needed `@apply_forward_hook` of their
own to onload the VAE under offloading.

Encode a still through the spatial encoder alone, so `encode` is correct for it
and only `encode` / `decode` carry the hook, as in every other autoencoder.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
---
 .../autoencoders/autoencoder_kl_minimax_h3.py  | 18 +++++++-----------
 1 file changed, 7 insertions(+), 11 deletions(-)

diff --git a/src/diffusers/models/autoencoders/autoencoder_kl_minimax_h3.py b/src/diffusers/models/autoencoders/autoencoder_kl_minimax_h3.py
index 586138fc884e..56d4707092b3 100644
--- a/src/diffusers/models/autoencoders/autoencoder_kl_minimax_h3.py
+++ b/src/diffusers/models/autoencoders/autoencoder_kl_minimax_h3.py
@@ -707,14 +707,8 @@ def _stitch_tiles(
             result_rows.append(torch.cat(result_row, dim=-1))
         return torch.cat(result_rows, dim=-2)
 
-    @apply_forward_hook
     def _encode_clip(self, x: torch.Tensor) -> torch.Tensor:
-        r"""
-        Encode one temporal clip, spatially tiled when tiling is enabled.
-
-        MiniMax-H3 encodes a keyframe or an image reference through this method rather than through [`~encode`],
-        because a single frame must not go through the temporal chunking, so it carries the offload hook too.
-        """
+        r"""Encode one temporal clip, spatially tiled when tiling is enabled."""
         if not self.use_tiling:
             return self.quant_conv(self.encoder(x))
 
@@ -768,17 +762,19 @@ def _decode_clip(self, z: torch.Tensor) -> torch.Tensor:
 
         return self._stitch_tiles(rows, y_overlaps, x_overlaps)
 
-    @apply_forward_hook
     def _encode(self, x: torch.Tensor) -> torch.Tensor:
         r"""
         Encode a video in `clip_length`-frame chunks and drop the `token_drop` trailing latent frames.
 
-        MiniMax-H3 encodes a video reference through this method rather than through [`~encode`], because the
-        posterior is sampled under a fixed generator rather than through the distribution object, so it carries the
-        offload hook too.
+        A single frame has no temporal extent to chunk, so it goes through the spatial encoder alone. Padding it up to
+        `clip_length` by repetition instead would run the temporal path over `clip_length` copies of the same image and
+        return `clip_length // temporal_compression_ratio - token_drop` latent frames rather than one — which is not
+        the conditioning MiniMax-H3 was trained with.
         """
         clip_length = self.config.clip_length
         num_frames = x.shape[2]
+        if num_frames == 1:
+            return self._encode_clip(x)
         if num_frames % clip_length != 0:
             pad_frames = x[:, :, -1:].repeat(1, 1, (-num_frames) % clip_length, 1, 1)
             x = torch.cat([x, pad_frames], dim=2)

From ed785ded37fc5c510a983ec5b7cc045cae6a1457 Mon Sep 17 00:00:00 2001
From: yiyixuxu <yixu310@gmail.com>
Date: Sun, 2 Aug 2026 17:17:40 +0000
Subject: [PATCH 02/16] Leave the MiniMax-H3 encoders encoding only

The keyframe and reference encoders drew the conditioning noise, mixed it in at
the noise-augmentation level and packed the result into rows, so they owned a
slice of latent preparation and had to be handed the target latent geometry and
the request generator to do it.

They now return the encoded latents and nothing else, one tensor per condition.
Both also go through the public `vae.encode` rather than `_encode_clip` /
`_encode`, and `encode_keyframes` takes the VAE directly instead of the whole
component bag.

The draw order is unchanged, which is what keeps a seeded request reproducible:
one draw per condition, in packed order, ahead of the video and audio noise.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
---
 .../modular_pipelines/minimax_h3/encoders.py  | 143 +++++-------------
 1 file changed, 40 insertions(+), 103 deletions(-)

diff --git a/src/diffusers/modular_pipelines/minimax_h3/encoders.py b/src/diffusers/modular_pipelines/minimax_h3/encoders.py
index da2d611eaba0..26e3e2b55e5c 100644
--- a/src/diffusers/modular_pipelines/minimax_h3/encoders.py
+++ b/src/diffusers/modular_pipelines/minimax_h3/encoders.py
@@ -17,22 +17,17 @@
 from transformers import Qwen2TokenizerFast, Qwen3VLForConditionalGeneration, Qwen3VLProcessor
 
 from ...models import AutoencoderKLMiniMaxH3, AutoencoderKLMiniMaxH3Audio
-from ...models.autoencoders.vae import DiagonalGaussianDistribution
-from ...schedulers import MiniMaxH3Scheduler
 from ...utils import logging
 from ..modular_pipeline import ModularPipelineBlocks, PipelineState
 from ..modular_pipeline_utils import ComponentSpec, InputParam, OutputParam
 from .modular_pipeline import MiniMaxH3ModularPipeline, MiniMaxH3Ref2VAModularPipeline
 from .packing import (
     MINIMAX_H3_KEYFRAME_ENCODE_SEED,
-    MINIMAX_H3_KEYFRAME_NOISE_AUG,
     MINIMAX_H3_PIXEL_MEAN,
     MINIMAX_H3_PIXEL_STD,
     MINIMAX_H3_TEXT_ENCODER_LAYER,
     MINIMAX_H3_TEXT_TAG,
     MINIMAX_H3_VIDEO_TAG,
-    keyframe_condition_noise,
-    patchify_video_latents,
 )
 from .packing_ref2va import (
     MiniMaxH3PreparedReference,
@@ -219,17 +214,14 @@ class MiniMaxH3KeyframeVaeEncoderStep(ModularPipelineBlocks):
     @property
     def description(self) -> str:
         return (
-            "Encodes the `fl2va` keyframes into packed conditioning rows and noises them to MiniMax-H3's "
-            "conditioning level. The rows are the anchors of the whole denoising loop: the loop only ever writes the "
-            "generated rows, so they are never updated again."
+            "Encodes the `fl2va` keyframes into conditioning latents. They become the anchors of the whole denoising "
+            "loop, which only ever writes the generated rows, so they are never updated again — the prepare-latents "
+            "step noises them to MiniMax-H3's conditioning level and packs them."
         )
 
     @property
     def expected_components(self) -> list[ComponentSpec]:
-        return [
-            ComponentSpec("vae", AutoencoderKLMiniMaxH3),
-            ComponentSpec("scheduler", MiniMaxH3Scheduler),
-        ]
+        return [ComponentSpec("vae", AutoencoderKLMiniMaxH3)]
 
     @property
     def inputs(self) -> list[InputParam]:
@@ -240,15 +232,6 @@ def inputs(self) -> list[InputParam]:
                 required=True,
                 description="The keyframes put onto the target canvas, in packed order.",
             ),
-            InputParam(name="latent_height", type_hint=int, required=True, description="Height of the video latents."),
-            InputParam(name="latent_width", type_hint=int, required=True, description="Width of the video latents."),
-            InputParam.template(
-                "generator",
-                description=(
-                    "The generator of the request. The conditioning noise is drawn from it before the target noise "
-                    "of the prepare-latents step."
-                ),
-            ),
         ]
 
     @property
@@ -256,67 +239,58 @@ def intermediate_outputs(self) -> list[OutputParam]:
         return [
             OutputParam(
                 "condition_latents",
-                type_hint=torch.Tensor,
-                description="The noise-augmented video conditioning rows, in packed order.",
+                type_hint=list[torch.Tensor],
+                description=(
+                    "The normalized video conditioning latents, one `(1, latent_channels, 1, latent_height, "
+                    "latent_width)` tensor per keyframe, in packed order."
+                ),
             )
         ]
 
     @staticmethod
-    def encode_keyframes(components, images: list, device: torch.device | None = None) -> torch.Tensor:
+    def encode_keyframes(vae, images: list, device: torch.device) -> list[torch.Tensor]:
         r"""
-        Encode the `fl2va` keyframes into packed conditioning rows.
+        Encode the `fl2va` keyframes into normalized conditioning latents.
 
-        The keyframes go through the video VAE's spatial encoder only — they are single frames, so none of its
-        17-frame temporal chunking applies — and the posterior is *sampled*, under a generator seeded with 42
-        independently of the request seed. The sampled latent is rounded to float16 before being normalized, as in the
-        reference implementation; both are part of reproducing the released model's conditioning.
+        A keyframe is a single frame, so `vae.encode` runs its spatial encoder alone with none of the 17-frame
+        temporal chunking. The posterior is *sampled*, under a generator seeded with 42 independently of the request
+        seed, and the sampled latent is rounded to float16 before being normalized, as in the reference
+        implementation; both are part of reproducing the released model's conditioning.
 
         Args:
+            vae (`AutoencoderKLMiniMaxH3`): The video VAE.
             images (`list[PIL.Image.Image]`):
                 The keyframes, already prepared onto the target canvas, in packed order.
-            device (`torch.device`, *optional*): The device to run the VAE on.
+            device (`torch.device`): The device to run the VAE on.
 
         Returns:
-            `torch.Tensor` of shape `(num_condition_rows, latent_channels * prod(patch_size))`: the float32
-            conditioning rows.
+            `list[torch.Tensor]`: one `(1, latent_channels, 1, latent_height, latent_width)` float32 CPU tensor per
+            keyframe, in packed order. One entry per condition is what the prepare-latents step draws its noise
+            against, so the list is the unit the request's generator is consumed in.
         """
-        device = device or components._execution_device
-        latents_mean = torch.tensor(components.vae.config.latents_mean).view(1, -1, 1, 1, 1)
-        latents_std = torch.tensor(components.vae.config.latents_std).view(1, -1, 1, 1, 1)
+        latents_mean = torch.tensor(vae.config.latents_mean).view(1, -1, 1, 1, 1)
+        latents_std = torch.tensor(vae.config.latents_std).view(1, -1, 1, 1, 1)
         pixel_mean = torch.tensor(MINIMAX_H3_PIXEL_MEAN, device=device).view(1, -1, 1, 1, 1)
         pixel_std = torch.tensor(MINIMAX_H3_PIXEL_STD, device=device).view(1, -1, 1, 1, 1)
 
-        rows = []
+        keyframe_latents = []
         for image in images:
             pixels = torch.from_numpy(np.array(image)).to(device).permute(2, 0, 1)[None, :, None]
             pixels = (pixels.to(torch.float32).div(255.0) - pixel_mean) / pixel_std
-            # `vae.encode` chunks along time for videos; a keyframe is one frame and is encoded by the (tiled)
-            # spatial encoder alone, which is what the released model conditions on.
-            moments = components.vae._encode_clip(pixels)
-            posterior = DiagonalGaussianDistribution(moments)
+            posterior = vae.encode(pixels, return_dict=False)[0]
             latents = posterior.sample(generator=torch.Generator().manual_seed(MINIMAX_H3_KEYFRAME_ENCODE_SEED))
             # The sampled latent is rounded to float16 before it is normalized: ~11 bits of every conditioning
             # latent, so the released model's conditioning cannot be reproduced without it.
             latents = latents.to(torch.float16).float().cpu()
-            rows.append(patchify_video_latents((latents - latents_mean) / latents_std, components.patch_size))
-        return torch.cat(rows)
+            keyframe_latents.append((latents - latents_mean) / latents_std)
+        return keyframe_latents
 
     @torch.no_grad()
     def __call__(self, components: MiniMaxH3ModularPipeline, state: PipelineState) -> PipelineState:
         block_state = self.get_block_state(state)
         device = components._execution_device
 
-        condition_latents = self.encode_keyframes(components, block_state.keyframes, device=device)
-        noise = keyframe_condition_noise(
-            ((1, block_state.latent_height, block_state.latent_width),) * len(block_state.keyframes),
-            components.patch_size,
-            components.vae_latent_channels,
-            generator=block_state.generator,
-            device=device,
-        )
-        block_state.condition_latents = components.scheduler.scale_noise(
-            condition_latents.to(device), MINIMAX_H3_KEYFRAME_NOISE_AUG, noise
-        )
+        block_state.condition_latents = self.encode_keyframes(components.vae, block_state.keyframes, device)
 
         self.set_block_state(state, block_state)
         return components, state
@@ -480,11 +454,11 @@ class MiniMaxH3Ref2VAReferenceEncoderStep(ModularPipelineBlocks):
     @property
     def description(self) -> str:
         return (
-            "Encodes the `ref2va` references into packed conditioning rows — image and video references through the "
-            "video VAE, soundtracks through the audio VAE — and noises the visual ones to MiniMax-H3's conditioning "
-            "level. Audio references ride along clean, at `t = 1.0`. Both are anchors of the whole denoising loop, "
-            "which only ever writes the generated rows. The latent geometry of every reference is resolved here, so "
-            "this runs before the packed layout is built."
+            "Encodes the `ref2va` references — image and video references through the video VAE, soundtracks through "
+            "the audio VAE. They are the anchors of the whole denoising loop, which only ever writes the generated "
+            "rows; the prepare-latents step noises the visual ones to MiniMax-H3's conditioning level and packs them, "
+            "while soundtracks ride along clean at `t = 1.0`. The latent geometry of every reference is resolved "
+            "here, so this runs before the packed layout is built."
         )
 
     @property
@@ -492,7 +466,6 @@ def expected_components(self) -> list[ComponentSpec]:
         return [
             ComponentSpec("vae", AutoencoderKLMiniMaxH3),
             ComponentSpec("audio_vae", AutoencoderKLMiniMaxH3Audio),
-            ComponentSpec("scheduler", MiniMaxH3Scheduler),
         ]
 
     @property
@@ -504,13 +477,6 @@ def inputs(self) -> list[InputParam]:
                 required=True,
                 description="The prepared references, in packed order. Their latent geometry is filled in here.",
             ),
-            InputParam.template(
-                "generator",
-                description=(
-                    "The generator of the request. The conditioning noise is drawn from it before the target noise "
-                    "of the prepare-latents step."
-                ),
-            ),
         ]
 
     @property
@@ -518,9 +484,10 @@ def intermediate_outputs(self) -> list[OutputParam]:
         return [
             OutputParam(
                 "condition_latents",
-                type_hint=torch.Tensor,
+                type_hint=list[torch.Tensor],
                 description=(
-                    "The noise-augmented video conditioning rows of the image and video references, in packed order, "
+                    "The encoded video conditioning latents of the image and video references, one `(1, "
+                    "latent_channels, num_latent_frames, latent_height, latent_width)` tensor each in packed order, "
                     "or None when the references carry none."
                 ),
             ),
@@ -565,7 +532,7 @@ def encode_references(
         audio_latents_mean = torch.tensor(components.audio_vae.config.latents_mean).view(1, 1, -1)
         audio_latents_std = torch.tensor(components.audio_vae.config.latents_std).view(1, 1, -1)
 
-        video_rows, audio_rows = [], []
+        video_latents, audio_rows = [], []
         for reference in references:
             if reference.kind != "audio":
                 if reference.kind == "image":
@@ -576,21 +543,14 @@ def encode_references(
                 pixels = (pixels.to(torch.float32).div(255.0) - pixel_mean) / pixel_std
                 # A single frame is encoded by the (tiled) spatial encoder alone; a video goes through the temporal
                 # chunking, which is what turns `17 * n + 5` frames into `5 * n + 2` latent frames.
-                moments = (
-                    components.vae._encode_clip(pixels)
-                    if reference.kind == "image"
-                    else components.vae._encode(pixels)
-                )
-                posterior = DiagonalGaussianDistribution(moments)
+                posterior = components.vae.encode(pixels, return_dict=False)[0]
                 latents = posterior.sample(generator=torch.Generator().manual_seed(MINIMAX_H3_KEYFRAME_ENCODE_SEED))
                 # The sampled latent is rounded to float16 before it is normalized: ~11 bits of every conditioning
                 # latent, so the released model's conditioning cannot be reproduced without it.
                 latents = latents.to(torch.float16).float().cpu()
                 reference.num_latent_frames = latents.shape[2]
                 reference.latent_height, reference.latent_width = latents.shape[3], latents.shape[4]
-                video_rows.append(
-                    patchify_video_latents((latents - latents_mean) / latents_std, components.patch_size)
-                )
+                video_latents.append((latents - latents_mean) / latents_std)
 
             if reference.has_audio:
                 posterior = components.audio_vae.encode(reference.waveform.to(device)[:, None], return_dict=False)[0]
@@ -600,39 +560,16 @@ def encode_references(
                 normalized = (latents - audio_latents_mean) / audio_latents_std
                 audio_rows.append(normalized.reshape(-1, components.audio_latent_channels))
 
-        return (
-            torch.cat(video_rows) if video_rows else None,
-            torch.cat(audio_rows) if audio_rows else None,
-        )
+        return video_latents or None, torch.cat(audio_rows) if audio_rows else None
 
     @torch.no_grad()
     def __call__(self, components: MiniMaxH3Ref2VAModularPipeline, state: PipelineState) -> PipelineState:
         block_state = self.get_block_state(state)
         device = components._execution_device
 
-        condition_latents, audio_condition_latents = self.encode_references(
+        block_state.condition_latents, block_state.audio_condition_latents = self.encode_references(
             components, block_state.prepared_references, device=device
         )
-        if condition_latents is not None:
-            noise = keyframe_condition_noise(
-                tuple(
-                    (reference.num_latent_frames, reference.latent_height, reference.latent_width)
-                    for reference in block_state.prepared_references
-                    if reference.kind != "audio"
-                ),
-                components.patch_size,
-                components.vae_latent_channels,
-                generator=block_state.generator,
-                device=device,
-            )
-            condition_latents = components.scheduler.scale_noise(
-                condition_latents.to(device), MINIMAX_H3_KEYFRAME_NOISE_AUG, noise
-            )
-        if audio_condition_latents is not None:
-            audio_condition_latents = audio_condition_latents.to(device)
-
-        block_state.condition_latents = condition_latents
-        block_state.audio_condition_latents = audio_condition_latents
 
         self.set_block_state(state, block_state)
         return components, state

From b97a4999bfc72fa5ec5121be883ce03acadeae8e Mon Sep 17 00:00:00 2001
From: yiyixuxu <yixu310@gmail.com>
Date: Sun, 2 Aug 2026 17:17:52 +0000
Subject: [PATCH 03/16] Turn the MiniMax-H3 setup step into a resize step

`MiniMaxH3SetupStep` ran ahead of both encoders and handed them derived values,
so neither could be popped out and run on raw inputs. It also resolved the frame
count and the latent geometry, which no encoder reads.

What is left is a resize step, in the shape `QwenImageEditResizeStep` uses: raw
`image` / `last_image` in, a `VaeImageProcessor` of its own, canvas-sized
keyframes out. It is wrapped in a conditional block so a text-only request skips
it rather than running it empty. `exif_transpose` and `convert("RGB")` are gone
because `load_image` already applies both.

The follower keyframe keeps MiniMax-H3's own cover-crop rather than moving to
`resize_mode="crop"`: the processor sizes with floor division and centres with
`w // 2 - src_w // 2` where MiniMax-H3 rounds and centres with `(src_w - w) // 2`,
which differs by a pixel on 106 of 218 sampled aspect ratios and would move the
conditioning latents off the reference implementation. The stretched anchor is
pixel-identical either way and does go through the processor.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
---
 .../minimax_h3/before_encoder.py              | 146 ++++++------------
 .../minimax_h3/modular_blocks_minimax_h3.py   |  72 +++++++--
 .../test_modular_pipeline_minimax_h3.py       |   2 +-
 3 files changed, 110 insertions(+), 110 deletions(-)

diff --git a/src/diffusers/modular_pipelines/minimax_h3/before_encoder.py b/src/diffusers/modular_pipelines/minimax_h3/before_encoder.py
index 88978bb6ff77..f32e521002cd 100644
--- a/src/diffusers/modular_pipelines/minimax_h3/before_encoder.py
+++ b/src/diffusers/modular_pipelines/minimax_h3/before_encoder.py
@@ -16,9 +16,11 @@
 import torch
 from PIL import Image, ImageOps
 
+from ...configuration_utils import FrozenDict
+from ...image_processor import VaeImageProcessor
 from ...utils import logging
 from ..modular_pipeline import ModularPipelineBlocks, PipelineState
-from ..modular_pipeline_utils import InputParam, OutputParam
+from ..modular_pipeline_utils import ComponentSpec, InputParam, OutputParam
 from .modular_pipeline import MiniMaxH3ModularPipeline, MiniMaxH3Ref2VAModularPipeline
 from .packing import (
     MINIMAX_H3_CANVAS_MULTIPLE,
@@ -26,10 +28,7 @@
     MINIMAX_H3_MAX_DURATION,
     MINIMAX_H3_MIN_DURATION,
     align_num_frames,
-    audio_latent_num_frames,
-    prepare_keyframe_image,
     resolve_canvas_size,
-    video_latent_num_frames,
 )
 from .packing_ref2va import (
     MINIMAX_H3_MAX_REFERENCE_AUDIOS,
@@ -51,57 +50,27 @@
 logger = logging.get_logger(__name__)  # pylint: disable=invalid-name
 
 
-def _latent_geometry(components, height: int, width: int, num_frames: int) -> tuple[int, int, int, int]:
-    r"""The latent geometry the packed layout, the noise draws and the decoders all key off."""
-    ratio = components.vae_spatial_compression_ratio
-    return video_latent_num_frames(num_frames), height // ratio, width // ratio, audio_latent_num_frames(num_frames)
-
-
-def _latent_geometry_outputs() -> list[OutputParam]:
-    r"""The declaration of what [`_latent_geometry`] resolves, shared by the two setup blocks."""
-    return [
-        OutputParam("num_latent_frames", type_hint=int, description="Number of generated video latent frames."),
-        OutputParam("latent_height", type_hint=int, description="Height of the generated video latents."),
-        OutputParam("latent_width", type_hint=int, description="Width of the generated video latents."),
-        OutputParam("num_audio_latents", type_hint=int, description="Number of generated audio latents per channel."),
-    ]
-
-
-class MiniMaxH3SetupStep(ModularPipelineBlocks):
+class MiniMaxH3ResizeStep(ModularPipelineBlocks):
     model_name = "minimax-h3"
 
     @property
     def description(self) -> str:
         return (
-            "Resolves the plan shared by the `t2va` and `fl2va` tasks: the canvas (MiniMax-H3's own 768-short-edge "
-            "geometry for the aspect ratio of the first keyframe, or 16:9 without keyframes), the `17 * n + 5` frame "
-            "count the video VAE can decode, the latent geometry every later block keys off, and the keyframes put "
-            "onto that canvas."
+            "Puts the `fl2va` keyframes onto the target canvas — MiniMax-H3's own 768-short-edge geometry for the "
+            "aspect ratio of the first keyframe unless `height` and `width` say otherwise. The canvas resolved here "
+            "is the one the whole request generates at."
         )
 
-    @staticmethod
-    def _check_inputs(block_state) -> None:
-        if (block_state.height is None) != (block_state.width is None):
-            raise ValueError("`height` and `width` have to be passed together, or neither of them.")
-        if block_state.height is not None and (
-            block_state.height % MINIMAX_H3_CANVAS_MULTIPLE or block_state.width % MINIMAX_H3_CANVAS_MULTIPLE
-        ):
-            raise ValueError(
-                f"`height` and `width` must be multiples of {MINIMAX_H3_CANVAS_MULTIPLE}, got "
-                f"{block_state.height}x{block_state.width}."
-            )
-        # The duration the request generates is the one of the *aligned* frame count, so that is what the ceiling has
-        # to hold for: 346 frames would otherwise pass the check and then be rounded up to 362, i.e. 15.083 seconds.
-        aligned_num_frames = align_num_frames(block_state.num_frames)
-        duration = aligned_num_frames / MINIMAX_H3_FPS
-        if not MINIMAX_H3_MIN_DURATION <= duration <= MINIMAX_H3_MAX_DURATION:
-            raise ValueError(
-                f"MiniMax-H3 generates between {MINIMAX_H3_MIN_DURATION} and {MINIMAX_H3_MAX_DURATION} seconds at "
-                f"{MINIMAX_H3_FPS} fps, so `num_frames`, rounded up to the next `17 * n + 5` the video VAE can "
-                f"encode, must be between {int(MINIMAX_H3_MIN_DURATION * MINIMAX_H3_FPS)} and "
-                f"{int(MINIMAX_H3_MAX_DURATION * MINIMAX_H3_FPS)}, got {block_state.num_frames} (rounded up to "
-                f"{aligned_num_frames})."
-            )
+    @property
+    def expected_components(self) -> list[ComponentSpec]:
+        return [
+            ComponentSpec(
+                "image_processor",
+                VaeImageProcessor,
+                config=FrozenDict({"vae_scale_factor": 16}),
+                default_creation_method="from_config",
+            ),
+        ]
 
     @property
     def inputs(self) -> list[InputParam]:
@@ -124,15 +93,6 @@ def inputs(self) -> list[InputParam]:
             ),
             InputParam.template("height", description="Height of the generated video in pixels, a multiple of 32."),
             InputParam.template("width", description="Width of the generated video in pixels, a multiple of 32."),
-            InputParam(
-                name="num_frames",
-                type_hint=int,
-                default=124,
-                description=(
-                    "Number of frames to generate, at the fixed 24 fps. Snapped up to the next `17 * n + 5` the video "
-                    "VAE can decode; the resulting duration must stay between 5 and 15 seconds."
-                ),
-            ),
         ]
 
     @property
@@ -140,57 +100,61 @@ def intermediate_outputs(self) -> list[OutputParam]:
         return [
             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."),
-            *_latent_geometry_outputs(),
             OutputParam(
                 "keyframes",
                 type_hint=list,
-                description="The keyframes put onto the target canvas, in packed order (empty for `t2va`).",
+                description="The keyframes put onto the target canvas, in packed order.",
             ),
             OutputParam(
                 "keyframe_anchors",
                 type_hint=tuple,
-                description="Which end of the video every keyframe is anchored to, in packed order.",
+                description=(
+                    "Which end of the video every keyframe is anchored to, in packed order. Positional with "
+                    "`keyframes`, so both are resolved here."
+                ),
             ),
         ]
 
     @torch.no_grad()
     def __call__(self, components: MiniMaxH3ModularPipeline, state: PipelineState) -> PipelineState:
         block_state = self.get_block_state(state)
-        self._check_inputs(block_state)
 
-        keyframes = [
-            ImageOps.exif_transpose(keyframe).convert("RGB")
-            for keyframe in (block_state.image, block_state.last_image)
-            if keyframe is not None
-        ]
+        keyframes = [keyframe for keyframe in (block_state.image, block_state.last_image) if keyframe is not None]
         block_state.keyframe_anchors = tuple(
             anchor
             for anchor, keyframe in (("first", block_state.image), ("last", block_state.last_image))
             if keyframe is not None
         )
         if block_state.height is None:
-            block_state.height, block_state.width = resolve_canvas_size(*(keyframes[0].size if keyframes else (16, 9)))
+            block_state.height, block_state.width = resolve_canvas_size(*keyframes[0].size)
+
+        prepared = []
+        for index, keyframe in enumerate(keyframes):
+            if keyframe.size == (block_state.width, block_state.height):
+                prepared.append(keyframe)
+            elif index == 0:
+                # The geometry anchor is stretched onto the canvas. `resize_mode="default"` is exactly PIL's
+                # `resize((width, height), LANCZOS)`, verified pixel-identical across aspect ratios.
+                prepared.append(
+                    components.image_processor.resize(keyframe, height=block_state.height, width=block_state.width)
+                )
+            else:
+                # The follower is cover-cropped. `VaeImageProcessor`'s `resize_mode="crop"` is *not* a drop-in here:
+                # it sizes with floor division and centres with `w // 2 - src_w // 2`, where MiniMax-H3 rounds and
+                # centres with `(src_w - w) // 2`. The two agree on some aspect ratios and differ by a pixel on
+                # others (106 of 218 sampled), which would move the conditioning latents off the reference
+                # implementation, so the released model's arithmetic is kept.
+                scale = max(block_state.width / keyframe.size[0], block_state.height / keyframe.size[1])
+                resized_size = (
+                    max(block_state.width, round(keyframe.size[0] * scale)),
+                    max(block_state.height, round(keyframe.size[1] * scale)),
+                )
+                left = max(0, (resized_size[0] - block_state.width) // 2)
+                top = max(0, (resized_size[1] - block_state.height) // 2)
+                resized = keyframe.resize(resized_size, Image.Resampling.LANCZOS)
+                prepared.append(resized.crop((left, top, left + block_state.width, top + block_state.height)))
+        block_state.keyframes = prepared
 
-        aligned_num_frames = align_num_frames(block_state.num_frames)
-        if aligned_num_frames != block_state.num_frames:
-            logger.warning(
-                f"`num_frames` has to be of the form 17 * n + 5 for the video VAE; rounding {block_state.num_frames} "
-                f"up to {aligned_num_frames}."
-            )
-            block_state.num_frames = aligned_num_frames
-
-        (
-            block_state.num_latent_frames,
-            block_state.latent_height,
-            block_state.latent_width,
-            block_state.num_audio_latents,
-        ) = _latent_geometry(components, block_state.height, block_state.width, block_state.num_frames)
-
-        block_state.keyframes = [
-            prepare_keyframe_image(keyframe, block_state.height, block_state.width, stretch=index == 0)
-            for index, keyframe in enumerate(keyframes)
-        ]
         self.set_block_state(state, block_state)
         return components, state
 
@@ -288,7 +252,6 @@ def intermediate_outputs(self) -> list[OutputParam]:
             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."),
-            *_latent_geometry_outputs(),
             OutputParam(
                 "prepared_references",
                 type_hint=list[MiniMaxH3PreparedReference],
@@ -397,12 +360,5 @@ def __call__(self, components: MiniMaxH3Ref2VAModularPipeline, state: PipelineSt
                 f"to {block_state.num_frames}."
             )
 
-        (
-            block_state.num_latent_frames,
-            block_state.latent_height,
-            block_state.latent_width,
-            block_state.num_audio_latents,
-        ) = _latent_geometry(components, block_state.height, block_state.width, block_state.num_frames)
-
         self.set_block_state(state, block_state)
         return components, state
diff --git a/src/diffusers/modular_pipelines/minimax_h3/modular_blocks_minimax_h3.py b/src/diffusers/modular_pipelines/minimax_h3/modular_blocks_minimax_h3.py
index b1a7b4f69724..90c2c8621fec 100644
--- a/src/diffusers/modular_pipelines/minimax_h3/modular_blocks_minimax_h3.py
+++ b/src/diffusers/modular_pipelines/minimax_h3/modular_blocks_minimax_h3.py
@@ -22,7 +22,7 @@
     MiniMaxH3Ref2VAPrepareLayoutStep,
     MiniMaxH3SetTimestepsStep,
 )
-from .before_encoder import MiniMaxH3Ref2VASetupStep, MiniMaxH3SetupStep
+from .before_encoder import MiniMaxH3Ref2VASetupStep, MiniMaxH3ResizeStep
 from .decoders import MiniMaxH3AudioDecodeStep, MiniMaxH3VideoDecodeStep
 from .denoise import MiniMaxH3DenoiseStep, MiniMaxH3Ref2VADenoiseStep
 from .encoders import (
@@ -46,6 +46,57 @@ def _generation_outputs() -> list[OutputParam]:
     ]
 
 
+# auto_docstring
+class MiniMaxH3AutoResizeStep(ConditionalPipelineBlocks):
+    """
+    Keyframe canvas block.
+       - MiniMaxH3ResizeStep runs for the `fl2va` task, whichever of the two keyframes is given.
+       - when neither `image` nor `last_image` is provided (`t2va`), this block is skipped and the layout step falls
+         back to MiniMax-H3's own 16:9 canvas.
+
+      Components:
+          image_processor (`VaeImageProcessor`)
+
+      Inputs:
+          image (`Image`, *optional*):
+              Keyframe the video starts from.
+          last_image (`Image`, *optional*):
+              Keyframe the video ends on.
+          height (`int`, *optional*):
+              Height of the generated video in pixels, a multiple of 32.
+          width (`int`, *optional*):
+              Width of the generated video in pixels, a multiple of 32.
+
+      Outputs:
+          height (`int`), width (`int`):
+              The resolved canvas.
+          keyframes (`list`):
+              The keyframes put onto that canvas, in packed order.
+          keyframe_anchors (`tuple`):
+              Which end of the video every keyframe is anchored to, in packed order.
+    """
+
+    model_name = "minimax-h3"
+    block_classes = [MiniMaxH3ResizeStep]
+    block_names = ["keyframes"]
+    block_trigger_inputs = ["image", "last_image"]
+    default_block_name = None
+
+    def select_block(self, **kwargs) -> str | None:
+        if kwargs.get("image") is not None or kwargs.get("last_image") is not None:
+            return "keyframes"
+        return None
+
+    @property
+    def description(self):
+        return (
+            "Keyframe canvas block.\n"
+            + " - MiniMaxH3ResizeStep runs for the `fl2va` task, whichever of the two keyframes is given.\n"
+            + " - when neither `image` nor `last_image` is provided (`t2va`), this block is skipped and the layout "
+            "step falls back to MiniMax-H3's own 16:9 canvas."
+        )
+
+
 # auto_docstring
 class MiniMaxH3AutoKeyframeVaeEncoderStep(ConditionalPipelineBlocks):
     """
@@ -54,22 +105,15 @@ class MiniMaxH3AutoKeyframeVaeEncoderStep(ConditionalPipelineBlocks):
        - when neither `image` nor `last_image` is provided (`t2va`), this block is skipped.
 
       Components:
-          vae (`AutoencoderKLMiniMaxH3`) scheduler (`MiniMaxH3Scheduler`)
+          vae (`AutoencoderKLMiniMaxH3`)
 
       Inputs:
-          keyframes (`list`, *optional*):
+          keyframes (`list`):
               The keyframes put onto the target canvas, in packed order.
-          latent_height (`int`, *optional*):
-              Height of the video latents.
-          latent_width (`int`, *optional*):
-              Width of the video latents.
-          generator (`Generator`, *optional*):
-              The generator of the request. The conditioning noise is drawn from it before the target noise of the
-              prepare-latents step.
 
       Outputs:
-          condition_latents (`Tensor`):
-              The noise-augmented video conditioning rows, in packed order.
+          condition_latents (`list`):
+              The normalized video conditioning latents, one tensor per keyframe, in packed order.
     """
 
     model_name = "minimax-h3"
@@ -205,7 +249,7 @@ class MiniMaxH3Blocks(SequentialPipelineBlocks):
 
     model_name = "minimax-h3"
     block_classes = [
-        MiniMaxH3SetupStep,
+        MiniMaxH3AutoResizeStep,
         MiniMaxH3TextEncoderStep,
         MiniMaxH3AutoKeyframeVaeEncoderStep,
         MiniMaxH3PrepareLayoutStep,
@@ -215,7 +259,7 @@ class MiniMaxH3Blocks(SequentialPipelineBlocks):
         MiniMaxH3DecodeStep,
     ]
     block_names = [
-        "setup",
+        "resize",
         "text_encoder",
         "vae_encoder",
         "prepare_layout",
diff --git a/tests/modular_pipelines/minimax_h3/test_modular_pipeline_minimax_h3.py b/tests/modular_pipelines/minimax_h3/test_modular_pipeline_minimax_h3.py
index 6e1bf9f4236a..9a785ff125ca 100644
--- a/tests/modular_pipelines/minimax_h3/test_modular_pipeline_minimax_h3.py
+++ b/tests/modular_pipelines/minimax_h3/test_modular_pipeline_minimax_h3.py
@@ -52,7 +52,7 @@
 
 
 T2VA_WORKFLOW = [
-    ("setup", "MiniMaxH3SetupStep"),
+    ("resize", "MiniMaxH3AutoResizeStep"),
     ("text_encoder", "MiniMaxH3TextEncoderStep"),
     ("prepare_layout", "MiniMaxH3PrepareLayoutStep"),
     ("prepare_latents", "MiniMaxH3PrepareLatentsStep"),

From 2b89de7657355f8e6a420a253e5f6f10ee8ecff4 Mon Sep 17 00:00:00 2001
From: yiyixuxu <yixu310@gmail.com>
Date: Sun, 2 Aug 2026 17:18:03 +0000
Subject: [PATCH 04/16] Resolve the MiniMax-H3 geometry where the layout is
 built
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The frame alignment and the latent shapes were resolved in the setup step, ahead
of the encoders, though the layout step is their first reader. They move to
`prepare_layout` for both blocksets, along with the canvas fallback and the
checks that guard them — the multiple-of-32 canvas and the 5-to-15 second
ceiling now sit in the block that computes what they protect.

`prepare_latents` picks up the other half: it draws the conditioning noise the
encoders used to draw, mixes it in and packs every condition, so all three noise
streams of a request are drawn in one place, in the order a seed reproduces.
Each condition is packed on its own because `ref2va` references are encoded at
their own resolutions and do not share a shape.

`_layout_inputs`, `_layout_outputs`, `_set_layout_state`, `_latent_geometry` and
`_latent_geometry_outputs` are inlined into the two blocks that used them, and
`keyframe_condition_noise` and `prepare_keyframe_image` are gone with their last
callers.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
---
 .../minimax_h3/before_denoise.py              | 405 +++++++++++-------
 .../modular_pipelines/minimax_h3/packing.py   |  73 ----
 2 files changed, 252 insertions(+), 226 deletions(-)

diff --git a/src/diffusers/modular_pipelines/minimax_h3/before_denoise.py b/src/diffusers/modular_pipelines/minimax_h3/before_denoise.py
index ef874b1e0100..c0a1a0811dea 100644
--- a/src/diffusers/modular_pipelines/minimax_h3/before_denoise.py
+++ b/src/diffusers/modular_pipelines/minimax_h3/before_denoise.py
@@ -22,11 +22,19 @@
 from .modular_pipeline import MiniMaxH3ModularPipeline, MiniMaxH3Ref2VAModularPipeline
 from .packing import (
     MINIMAX_H3_AUDIO_CHANNELS,
+    MINIMAX_H3_CANVAS_MULTIPLE,
+    MINIMAX_H3_FPS,
     MINIMAX_H3_KEYFRAME_NOISE_AUG,
+    MINIMAX_H3_MAX_DURATION,
+    MINIMAX_H3_MIN_DURATION,
     MiniMaxH3PackedSequence,
+    align_num_frames,
+    audio_latent_num_frames,
     build_packed_sequence,
     build_row_timesteps,
     patchify_video_latents,
+    resolve_canvas_size,
+    video_latent_num_frames,
 )
 from .packing_ref2va import MiniMaxH3PreparedReference, build_ref2va_packed_sequence
 
@@ -34,93 +42,39 @@
 logger = logging.get_logger(__name__)  # pylint: disable=invalid-name
 
 
-def _layout_inputs() -> list[InputParam]:
-    r"""What both packed layouts are built from, beyond the conditioning of the task itself."""
-    return [
-        InputParam(
-            name="text_token_tags",
-            type_hint=torch.Tensor,
-            required=True,
-            description="The per-row modality tag of every row of `prompt_embeds`.",
-        ),
-        InputParam(
-            name="num_latent_frames", type_hint=int, required=True, description="Number of video latent frames."
-        ),
-        InputParam(name="latent_height", type_hint=int, required=True, description="Height of the video latents."),
-        InputParam(name="latent_width", type_hint=int, required=True, description="Width of the video latents."),
-        InputParam(
-            name="num_audio_latents",
-            type_hint=int,
-            required=True,
-            description="Number of audio latents per channel.",
-        ),
-    ]
-
-
-def _layout_outputs() -> list[OutputParam]:
-    r"""The row layout of the packed sequence, shared by the two tasks."""
-    return [
-        OutputParam(
-            "layout",
-            type_hint=MiniMaxH3PackedSequence,
-            description="The structural description of the packed sequence.",
-        ),
-        OutputParam(
-            "position_ids",
-            type_hint=torch.Tensor,
-            description="The `(t, h, w)` rotary coordinate of every row, in float64.",
-        ),
-        OutputParam("token_tags", type_hint=torch.Tensor, description="The modality tag of every row."),
-        OutputParam(
-            "video_indices",
-            type_hint=torch.Tensor,
-            description="Sequence positions of the video rows, conditioning rows first.",
-        ),
-        OutputParam(
-            "audio_indices",
-            type_hint=torch.Tensor,
-            description="Sequence positions of the audio rows, reference rows first.",
-        ),
-        OutputParam("text_indices", type_hint=torch.Tensor, description="Sequence positions of the text rows."),
-        OutputParam(
-            "num_condition_video_rows",
-            type_hint=int,
-            description="How many leading video rows are conditioning rows rather than generated rows.",
-        ),
-        OutputParam(
-            "num_condition_audio_rows",
-            type_hint=int,
-            description="How many leading audio rows are reference rows rather than generated rows.",
-        ),
-    ]
-
-
-def _set_layout_state(block_state, layout: MiniMaxH3PackedSequence, device: torch.device) -> None:
-    block_state.layout = layout
-    block_state.position_ids = layout.position_ids.to(device)
-    block_state.token_tags = layout.token_tags.to(device)
-    block_state.video_indices = layout.video_indices.to(device)
-    block_state.audio_indices = layout.audio_indices.to(device)
-    block_state.text_indices = layout.text_indices.to(device)
-    block_state.num_condition_video_rows = layout.num_condition_video_rows
-    block_state.num_condition_audio_rows = layout.num_condition_audio_rows
-
-
 class MiniMaxH3PrepareLayoutStep(ModularPipelineBlocks):
     model_name = "minimax-h3"
 
     @property
     def description(self) -> str:
         return (
-            "Builds the packed layout of a `t2va` / `fl2va` request — `[text | keyframe conditions | target audio | "
-            "target video]` — and its fp64 rotary grid. MiniMax-H3 runs full self-attention over this one sequence, "
-            "so the layout is what every later block addresses rows through."
+            "Resolves the geometry of a `t2va` / `fl2va` request — the canvas, the `17 * n + 5` frame count the video "
+            "VAE can decode and the latent shapes every later block keys off — and builds the packed layout from it: "
+            "`[text | keyframe conditions | target audio | target video]` plus its fp64 rotary grid. MiniMax-H3 runs "
+            "full self-attention over this one sequence, so the layout is what every later block addresses rows "
+            "through."
         )
 
     @property
     def inputs(self) -> list[InputParam]:
         return [
-            *_layout_inputs(),
+            InputParam(
+                name="text_token_tags",
+                type_hint=torch.Tensor,
+                required=True,
+                description="The per-row modality tag of every row of `prompt_embeds`.",
+            ),
+            InputParam.template("height", description="Height of the generated video in pixels, a multiple of 32."),
+            InputParam.template("width", description="Width of the generated video in pixels, a multiple of 32."),
+            InputParam(
+                name="num_frames",
+                type_hint=int,
+                default=124,
+                description=(
+                    "Number of frames to generate, at the fixed 24 fps. Snapped up to the next `17 * n + 5` the video "
+                    "VAE can decode; the resulting duration must stay between 5 and 15 seconds."
+                ),
+            ),
             InputParam(
                 name="keyframe_anchors",
                 type_hint=tuple,
@@ -131,11 +85,87 @@ def inputs(self) -> list[InputParam]:
 
     @property
     def intermediate_outputs(self) -> list[OutputParam]:
-        return _layout_outputs()
+        return [
+            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."),
+            OutputParam("num_latent_frames", type_hint=int, description="Number of generated video latent frames."),
+            OutputParam("latent_height", type_hint=int, description="Height of the generated video latents."),
+            OutputParam("latent_width", type_hint=int, description="Width of the generated video latents."),
+            OutputParam(
+                "num_audio_latents", type_hint=int, description="Number of generated audio latents per channel."
+            ),
+            OutputParam(
+                "layout",
+                type_hint=MiniMaxH3PackedSequence,
+                description="The structural description of the packed sequence.",
+            ),
+            OutputParam(
+                "position_ids",
+                type_hint=torch.Tensor,
+                description="The `(t, h, w)` rotary coordinate of every row, in float64.",
+            ),
+            OutputParam("token_tags", type_hint=torch.Tensor, description="The modality tag of every row."),
+            OutputParam(
+                "video_indices",
+                type_hint=torch.Tensor,
+                description="Sequence positions of the video rows, conditioning rows first.",
+            ),
+            OutputParam(
+                "audio_indices",
+                type_hint=torch.Tensor,
+                description="Sequence positions of the audio rows, reference rows first.",
+            ),
+            OutputParam("text_indices", type_hint=torch.Tensor, description="Sequence positions of the text rows."),
+            OutputParam(
+                "num_condition_video_rows",
+                type_hint=int,
+                description="How many leading video rows are conditioning rows rather than generated rows.",
+            ),
+            OutputParam(
+                "num_condition_audio_rows",
+                type_hint=int,
+                description="How many leading audio rows are reference rows rather than generated rows.",
+            ),
+        ]
 
     @torch.no_grad()
     def __call__(self, components: MiniMaxH3ModularPipeline, state: PipelineState) -> PipelineState:
         block_state = self.get_block_state(state)
+        device = components._execution_device
+
+        # Without a keyframe to take the aspect ratio from, MiniMax-H3 generates on its own 16:9 canvas.
+        if block_state.height is None:
+            block_state.height, block_state.width = resolve_canvas_size(16, 9)
+        if block_state.height % MINIMAX_H3_CANVAS_MULTIPLE or block_state.width % MINIMAX_H3_CANVAS_MULTIPLE:
+            raise ValueError(
+                f"`height` and `width` must be multiples of {MINIMAX_H3_CANVAS_MULTIPLE}, got "
+                f"{block_state.height}x{block_state.width}."
+            )
+
+        aligned_num_frames = align_num_frames(block_state.num_frames)
+        if aligned_num_frames != block_state.num_frames:
+            logger.warning(
+                f"`num_frames` has to be of the form 17 * n + 5 for the video VAE; rounding {block_state.num_frames} "
+                f"up to {aligned_num_frames}."
+            )
+            block_state.num_frames = aligned_num_frames
+        # The duration the request generates is the one of the *aligned* frame count, so that is what the ceiling has
+        # to hold for: 346 frames would otherwise pass the check and then be rounded up to 362, i.e. 15.083 seconds.
+        duration = block_state.num_frames / MINIMAX_H3_FPS
+        if not MINIMAX_H3_MIN_DURATION <= duration <= MINIMAX_H3_MAX_DURATION:
+            raise ValueError(
+                f"MiniMax-H3 generates between {MINIMAX_H3_MIN_DURATION} and {MINIMAX_H3_MAX_DURATION} seconds at "
+                f"{MINIMAX_H3_FPS} fps, so `num_frames`, rounded up to the next `17 * n + 5` the video VAE can "
+                f"encode, must be between {int(MINIMAX_H3_MIN_DURATION * MINIMAX_H3_FPS)} and "
+                f"{int(MINIMAX_H3_MAX_DURATION * MINIMAX_H3_FPS)}, got {block_state.num_frames}."
+            )
+
+        ratio = components.vae_spatial_compression_ratio
+        block_state.num_latent_frames = video_latent_num_frames(block_state.num_frames)
+        block_state.latent_height = block_state.height // ratio
+        block_state.latent_width = block_state.width // ratio
+        block_state.num_audio_latents = audio_latent_num_frames(block_state.num_frames)
 
         layout = build_packed_sequence(
             block_state.text_token_tags,
@@ -146,7 +176,14 @@ def __call__(self, components: MiniMaxH3ModularPipeline, state: PipelineState) -
             components.patch_size,
             block_state.keyframe_anchors,
         )
-        _set_layout_state(block_state, layout, components._execution_device)
+        block_state.layout = layout
+        block_state.position_ids = layout.position_ids.to(device)
+        block_state.token_tags = layout.token_tags.to(device)
+        block_state.video_indices = layout.video_indices.to(device)
+        block_state.audio_indices = layout.audio_indices.to(device)
+        block_state.text_indices = layout.text_indices.to(device)
+        block_state.num_condition_video_rows = layout.num_condition_video_rows
+        block_state.num_condition_audio_rows = layout.num_condition_audio_rows
 
         self.set_block_state(state, block_state)
         return components, state
@@ -158,30 +195,94 @@ class MiniMaxH3Ref2VAPrepareLayoutStep(ModularPipelineBlocks):
     @property
     def description(self) -> str:
         return (
-            "Builds the packed layout of a `ref2va` request — `[text | reference blocks | target audio | target "
-            "video]` — and its fp64 rotary grid. The reference order advances the shared audio/video rotary clock, so "
-            "it is part of the layout rather than a detail of the presentation."
+            "Resolves the latent shapes of a `ref2va` request and builds its packed layout — `[text | reference "
+            "blocks | target audio | target video]` — plus its fp64 rotary grid. The reference order advances the "
+            "shared audio/video rotary clock, so it is part of the layout rather than a detail of the presentation."
         )
 
     @property
     def inputs(self) -> list[InputParam]:
         return [
-            *_layout_inputs(),
+            InputParam(
+                name="text_token_tags",
+                type_hint=torch.Tensor,
+                required=True,
+                description="The per-row modality tag of every row of `prompt_embeds`.",
+            ),
             InputParam(
                 name="prepared_references",
                 type_hint=list[MiniMaxH3PreparedReference],
                 required=True,
                 description="The prepared references, in packed order, with their latent geometry filled in.",
             ),
+            InputParam.template("height", required=True, description="Height of the generated video in pixels."),
+            InputParam.template("width", required=True, description="Width of the generated video in pixels."),
+            InputParam(
+                name="num_frames",
+                type_hint=int,
+                required=True,
+                description="Resolved number of frames, of the form 17 * n + 5.",
+            ),
         ]
 
     @property
     def intermediate_outputs(self) -> list[OutputParam]:
-        return _layout_outputs()
+        return [
+            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."),
+            OutputParam("num_latent_frames", type_hint=int, description="Number of generated video latent frames."),
+            OutputParam("latent_height", type_hint=int, description="Height of the generated video latents."),
+            OutputParam("latent_width", type_hint=int, description="Width of the generated video latents."),
+            OutputParam(
+                "num_audio_latents", type_hint=int, description="Number of generated audio latents per channel."
+            ),
+            OutputParam(
+                "layout",
+                type_hint=MiniMaxH3PackedSequence,
+                description="The structural description of the packed sequence.",
+            ),
+            OutputParam(
+                "position_ids",
+                type_hint=torch.Tensor,
+                description="The `(t, h, w)` rotary coordinate of every row, in float64.",
+            ),
+            OutputParam("token_tags", type_hint=torch.Tensor, description="The modality tag of every row."),
+            OutputParam(
+                "video_indices",
+                type_hint=torch.Tensor,
+                description="Sequence positions of the video rows, conditioning rows first.",
+            ),
+            OutputParam(
+                "audio_indices",
+                type_hint=torch.Tensor,
+                description="Sequence positions of the audio rows, reference rows first.",
+            ),
+            OutputParam("text_indices", type_hint=torch.Tensor, description="Sequence positions of the text rows."),
+            OutputParam(
+                "num_condition_video_rows",
+                type_hint=int,
+                description="How many leading video rows are conditioning rows rather than generated rows.",
+            ),
+            OutputParam(
+                "num_condition_audio_rows",
+                type_hint=int,
+                description="How many leading audio rows are reference rows rather than generated rows.",
+            ),
+        ]
 
     @torch.no_grad()
     def __call__(self, components: MiniMaxH3Ref2VAModularPipeline, state: PipelineState) -> PipelineState:
         block_state = self.get_block_state(state)
+        device = components._execution_device
+
+        # The canvas and the frame count are settled by the setup step: a `ref2va` soundtrack is truncated to the
+        # generated duration as the references are prepared, so `num_frames` has to be final before that runs.
+        ratio = components.vae_spatial_compression_ratio
+        block_state.num_latent_frames = video_latent_num_frames(block_state.num_frames)
+        block_state.latent_height = block_state.height // ratio
+        block_state.latent_width = block_state.width // ratio
+        block_state.num_audio_latents = audio_latent_num_frames(block_state.num_frames)
 
         layout = build_ref2va_packed_sequence(
             block_state.text_token_tags,
@@ -192,7 +293,14 @@ def __call__(self, components: MiniMaxH3Ref2VAModularPipeline, state: PipelineSt
             block_state.num_audio_latents,
             components.patch_size,
         )
-        _set_layout_state(block_state, layout, components._execution_device)
+        block_state.layout = layout
+        block_state.position_ids = layout.position_ids.to(device)
+        block_state.token_tags = layout.token_tags.to(device)
+        block_state.video_indices = layout.video_indices.to(device)
+        block_state.audio_indices = layout.audio_indices.to(device)
+        block_state.text_indices = layout.text_indices.to(device)
+        block_state.num_condition_video_rows = layout.num_condition_video_rows
+        block_state.num_condition_audio_rows = layout.num_condition_audio_rows
 
         self.set_block_state(state, block_state)
         return components, state
@@ -204,11 +312,15 @@ class MiniMaxH3PrepareLatentsStep(ModularPipelineBlocks):
     @property
     def description(self) -> str:
         return (
-            "Draws the initial noise of the generated rows and prepends the conditioning rows. MiniMax-H3 draws the "
-            "video noise as a latent tensor and patchifies it afterwards, then the audio noise directly in row "
-            "layout — both off the request's generator, after the conditioning noise of the encoder step."
+            "Draws every noise stream of the request and packs the video rows. MiniMax-H3 draws one condition at a "
+            "time first — noising the encoded anchors to its conditioning level — then the video noise as a latent "
+            "tensor, then the audio noise directly in row layout, all off the request's generator, in that order."
         )
 
+    @property
+    def expected_components(self) -> list[ComponentSpec]:
+        return [ComponentSpec("scheduler", MiniMaxH3Scheduler)]
+
     @property
     def inputs(self) -> list[InputParam]:
         return [
@@ -244,8 +356,12 @@ def inputs(self) -> list[InputParam]:
             ),
             InputParam(
                 name="condition_latents",
-                type_hint=torch.Tensor,
-                description="The video conditioning rows to prepend, or None for a request that has none.",
+                type_hint=list[torch.Tensor],
+                description=(
+                    "The encoded video conditioning latents, one `(1, latent_channels, num_latent_frames, "
+                    "latent_height, latent_width)` tensor per condition in packed order, or None for a request that "
+                    "has none. Noised and packed here."
+                ),
             ),
             InputParam(
                 name="audio_condition_latents",
@@ -269,83 +385,66 @@ def intermediate_outputs(self) -> list[OutputParam]:
             ),
         ]
 
-    @staticmethod
-    def prepare_latents(
-        components,
-        num_latent_frames: int,
-        latent_height: int,
-        latent_width: int,
-        num_audio_latents: int,
-        device: torch.device,
-        generator: torch.Generator | list[torch.Generator] | None = None,
-        latents: torch.Tensor | None = None,
-        audio_latents: torch.Tensor | None = None,
-    ) -> tuple[torch.Tensor, torch.Tensor]:
-        r"""
-        Draw the initial noise of both modalities and pack it into transformer rows.
-
-        A request draws every stream from the one generator it is given, and the order is part of what that generator
-        reproduces: the conditioning noise of the keyframes or references first (one draw per condition, in
-        [`~modular_pipelines.minimax_h3.packing.keyframe_condition_noise`]), then the video noise here, as a latent tensor
-        that is patchified afterwards, then the audio noise, directly in row layout. Passing `latents` or
-        `audio_latents` skips its draw and shifts the ones after it.
-
-        Args:
-            num_latent_frames (`int`): Number of video latent frames.
-            latent_height (`int`): Latent height.
-            latent_width (`int`): Latent width.
-            num_audio_latents (`int`): Number of audio latents per channel.
-            device (`torch.device`): The device the rows are drawn on.
-            generator (`torch.Generator`, *optional*): The generator of the request.
-            latents (`torch.Tensor`, *optional*):
-                Pre-generated video noise of shape `(1, latent_channels, num_latent_frames, latent_height,
-                latent_width)`, used instead of the draw.
-            audio_latents (`torch.Tensor`, *optional*):
-                Pre-generated audio noise of shape `(2, audio_latent_channels, num_audio_latents)`.
-
-        Returns:
-            `tuple[torch.Tensor, torch.Tensor]`: the video rows and the channel-major audio rows.
-        """
+    @torch.no_grad()
+    def __call__(self, components: MiniMaxH3ModularPipeline, state: PipelineState) -> PipelineState:
+        block_state = self.get_block_state(state)
+        device = components._execution_device
+        patch_size = components.patch_size
+
+        # A request draws every stream from the one generator it is given, and the order is part of what that
+        # generator reproduces: one draw per condition first, then the video noise as a latent tensor, then the audio
+        # noise directly in row layout. Passing `latents` or `audio_latents` skips its draw and shifts the ones after
+        # it.
+        condition_rows = None
+        if block_state.condition_latents is not None:
+            # One draw per condition, in packed order. Each is packed on its own because `ref2va` references are
+            # encoded at their own resolutions, so their latents do not share a shape.
+            packed = []
+            for condition in block_state.condition_latents:
+                noise = randn_tensor(
+                    condition.shape, generator=block_state.generator, device=device, dtype=torch.float32
+                )
+                # The anchors are not fully clean: the released model noises them to `t = 0.999` and holds them there
+                # for every step. Mixing before the patchify is the same arithmetic, since patchify only permutes.
+                noised = components.scheduler.scale_noise(condition.to(device), MINIMAX_H3_KEYFRAME_NOISE_AUG, noise)
+                packed.append(patchify_video_latents(noised, patch_size))
+            condition_rows = torch.cat(packed)
+
+        latents = block_state.latents
         if latents is None:
             latents = randn_tensor(
-                (1, components.vae_latent_channels, num_latent_frames, latent_height, latent_width),
-                generator=generator,
+                (
+                    1,
+                    components.vae_latent_channels,
+                    block_state.num_latent_frames,
+                    block_state.latent_height,
+                    block_state.latent_width,
+                ),
+                generator=block_state.generator,
                 device=device,
                 dtype=torch.float32,
             )
-        video_rows = patchify_video_latents(latents.to(torch.float32), components.patch_size)
+        video_rows = patchify_video_latents(latents.to(device, torch.float32), patch_size)
 
-        if audio_latents is None:
+        if block_state.audio_latents is None:
             audio_rows = randn_tensor(
-                (num_audio_latents * MINIMAX_H3_AUDIO_CHANNELS, components.audio_latent_channels),
-                generator=generator,
+                (block_state.num_audio_latents * MINIMAX_H3_AUDIO_CHANNELS, components.audio_latent_channels),
+                generator=block_state.generator,
                 device=device,
                 dtype=torch.float32,
             )
         else:
-            audio_rows = audio_latents.to(torch.float32).permute(0, 2, 1).reshape(-1, components.audio_latent_channels)
-        return video_rows.to(device), audio_rows.to(device)
-
-    @torch.no_grad()
-    def __call__(self, components: MiniMaxH3ModularPipeline, state: PipelineState) -> PipelineState:
-        block_state = self.get_block_state(state)
+            audio_rows = (
+                block_state.audio_latents.to(device, torch.float32)
+                .permute(0, 2, 1)
+                .reshape(-1, components.audio_latent_channels)
+            )
 
-        latents, audio_latents = self.prepare_latents(
-            components,
-            block_state.num_latent_frames,
-            block_state.latent_height,
-            block_state.latent_width,
-            block_state.num_audio_latents,
-            components._execution_device,
-            block_state.generator,
-            block_state.latents,
-            block_state.audio_latents,
-        )
-        if block_state.condition_latents is not None:
-            latents = torch.cat([block_state.condition_latents, latents])
+        if condition_rows is not None:
+            video_rows = torch.cat([condition_rows, video_rows])
         if block_state.audio_condition_latents is not None:
-            audio_latents = torch.cat([block_state.audio_condition_latents, audio_latents])
-        block_state.latents, block_state.audio_latents = latents, audio_latents
+            audio_rows = torch.cat([block_state.audio_condition_latents.to(device), audio_rows])
+        block_state.latents, block_state.audio_latents = video_rows, audio_rows
 
         self.set_block_state(state, block_state)
         return components, state
diff --git a/src/diffusers/modular_pipelines/minimax_h3/packing.py b/src/diffusers/modular_pipelines/minimax_h3/packing.py
index c84f7e7f9aa8..94e14226c778 100644
--- a/src/diffusers/modular_pipelines/minimax_h3/packing.py
+++ b/src/diffusers/modular_pipelines/minimax_h3/packing.py
@@ -40,9 +40,6 @@
 
 import numpy as np
 import torch
-from PIL import Image
-
-from ...utils.torch_utils import randn_tensor
 
 
 # Per-row modality tags. They index the transformer's AdaLN table, so the values are a checkpoint contract.
@@ -213,36 +210,6 @@ def audio_latent_num_frames(num_frames: int) -> int:
     return int(round(num_frames / MINIMAX_H3_FPS * MINIMAX_H3_AUDIO_LATENTS_PER_SECOND))
 
 
-def prepare_keyframe_image(image, height: int, width: int, stretch: bool):
-    r"""
-    Put a keyframe onto the target canvas.
-
-    The first keyframe of a request is the geometry anchor and is *stretched* onto the canvas, while a second
-    keyframe follows that canvas and is cover-cropped (aspect-preserving max-scale LANCZOS resize plus a centre
-    crop). An image that already is the canvas is returned untouched, without a resampling pass.
-
-    Args:
-        image (`PIL.Image.Image`): The keyframe, in RGB and already EXIF-transposed.
-        height (`int`): Canvas height.
-        width (`int`): Canvas width.
-        stretch (`bool`): Whether to stretch (geometry anchor) instead of cover-cropping (follower).
-
-    Returns:
-        `PIL.Image.Image`: The prepared keyframe.
-    """
-    if image.size == (width, height):
-        return image
-    if stretch:
-        return image.resize((width, height), Image.Resampling.LANCZOS)
-
-    scale = max(width / image.size[0], height / image.size[1])
-    resized_size = (max(width, round(image.size[0] * scale)), max(height, round(image.size[1] * scale)))
-    left = max(0, (resized_size[0] - width) // 2)
-    top = max(0, (resized_size[1] - height) // 2)
-    resized = image.resize(resized_size, Image.Resampling.LANCZOS)
-    return resized.crop((left, top, left + width, top + height))
-
-
 def patchify_video_latents(latents: torch.Tensor, patch_size: tuple[int, int, int]) -> torch.Tensor:
     r"""
     Pack video latents into transformer rows.
@@ -496,43 +463,3 @@ def build_row_timesteps(
     row_timesteps[layout.audio_indices[layout.num_condition_audio_rows :]] = audio_timestep
     row_timesteps[layout.audio_indices[: layout.num_condition_audio_rows]] = condition_audio_timestep
     return torch.unique(row_timesteps, sorted=True, return_inverse=True)
-
-
-def keyframe_condition_noise(
-    condition_latent_shapes: tuple[tuple[int, int, int], ...],
-    patch_size: tuple[int, int, int],
-    latent_channels: int,
-    generator: torch.Generator | list[torch.Generator] | None = None,
-    device: torch.device | None = None,
-    dtype: torch.dtype = torch.float32,
-) -> torch.Tensor:
-    r"""
-    Draw the noise that the keyframe (or reference) conditioning rows are mixed with.
-
-    One draw per condition, in packed order, off the request's generator. The conditioning rows are prepared before
-    the target rows, so these are the *first* draws of a request, ahead of the video and audio noise of
-    [`~MiniMaxH3PrepareLatentsStep.prepare_latents`] — the order is part of what a generator reproduces.
-
-    Args:
-        condition_latent_shapes (`tuple[tuple[int, int, int], ...]`):
-            The `(num_latent_frames, latent_height, latent_width)` of every condition, in packed order.
-        patch_size (`tuple[int, int, int]`): The transformer's `(t, h, w)` patch.
-        latent_channels (`int`): Number of video latent channels.
-        generator (`torch.Generator`, *optional*): The generator of the request.
-        device (`torch.device`, *optional*): The device the noise is drawn on.
-        dtype (`torch.dtype`, defaults to `torch.float32`): The dtype of the noise.
-
-    Returns:
-        `torch.Tensor` of shape `(num_condition_rows, latent_channels * prod(patch_size))`: the noise rows,
-        concatenated in packed order.
-    """
-    rows = []
-    for num_latent_frames, latent_height, latent_width in condition_latent_shapes:
-        noise = randn_tensor(
-            (1, latent_channels, num_latent_frames, latent_height, latent_width),
-            generator=generator,
-            device=device,
-            dtype=dtype,
-        )
-        rows.append(patchify_video_latents(noise, patch_size))
-    return torch.cat(rows)

From 3f001c650c76b874c4ea18cfcb27d4c3e581c988 Mon Sep 17 00:00:00 2001
From: yiyixuxu <yixu310@gmail.com>
Date: Sun, 2 Aug 2026 18:53:15 +0000
Subject: [PATCH 05/16] Inline the MiniMax-H3 audio VAE's weight-norm conv
 helper

`_wn_conv1d` was a one-line alias for `weight_norm(nn.Conv1d(...))` behind ten
call sites, so reading any of them meant a detour.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
---
 .../autoencoder_kl_minimax_h3_audio.py        | 37 ++++++++++---------
 1 file changed, 19 insertions(+), 18 deletions(-)

diff --git a/src/diffusers/models/autoencoders/autoencoder_kl_minimax_h3_audio.py b/src/diffusers/models/autoencoders/autoencoder_kl_minimax_h3_audio.py
index c35c62e28ec3..0b24768642bb 100644
--- a/src/diffusers/models/autoencoders/autoencoder_kl_minimax_h3_audio.py
+++ b/src/diffusers/models/autoencoders/autoencoder_kl_minimax_h3_audio.py
@@ -93,10 +93,6 @@ class MiniMaxH3AudioEncoderOutput(BaseOutput):
     latent_dist: MiniMaxH3AudioDiagonalGaussianDistribution
 
 
-def _wn_conv1d(*args, **kwargs) -> nn.Module:
-    return weight_norm(nn.Conv1d(*args, **kwargs))
-
-
 def kaiser_sinc_filter1d(cutoff: float, half_width: float, kernel_size: int) -> torch.Tensor:
     r"""Kaiser-windowed sinc low-pass filter of shape `[1, 1, kernel_size]`.
 
@@ -234,9 +230,9 @@ def __init__(self, dim: int, dilation: int):
         super().__init__()
         self.block = nn.Sequential(
             MiniMaxH3AudioSnake1d(dim),
-            _wn_conv1d(dim, dim, kernel_size=7, dilation=dilation, padding=((7 - 1) * dilation) // 2),
+            weight_norm(nn.Conv1d(dim, dim, kernel_size=7, dilation=dilation, padding=((7 - 1) * dilation) // 2)),
             MiniMaxH3AudioSnake1d(dim),
-            _wn_conv1d(dim, dim, kernel_size=1),
+            weight_norm(nn.Conv1d(dim, dim, kernel_size=1)),
         )
 
     def forward(self, hidden_states: torch.Tensor) -> torch.Tensor:
@@ -257,12 +253,14 @@ def __init__(self, dim: int, stride: int):
             MiniMaxH3AudioResidualUnit(dim // 2, dilation=3),
             MiniMaxH3AudioResidualUnit(dim // 2, dilation=9),
             MiniMaxH3AudioSnake1d(dim // 2),
-            _wn_conv1d(
-                dim // 2,
-                dim,
-                kernel_size=2 * stride,
-                stride=stride,
-                padding=math.ceil(stride / 2),
+            weight_norm(
+                nn.Conv1d(
+                    dim // 2,
+                    dim,
+                    kernel_size=2 * stride,
+                    stride=stride,
+                    padding=math.ceil(stride / 2),
+                )
             ),
         )
 
@@ -275,13 +273,13 @@ class MiniMaxH3AudioEncoder(nn.Module):
 
     def __init__(self, d_model: int, strides: tuple[int, ...], d_latent: int):
         super().__init__()
-        block: list[nn.Module] = [_wn_conv1d(1, d_model, kernel_size=7, padding=3)]
+        block: list[nn.Module] = [weight_norm(nn.Conv1d(1, d_model, kernel_size=7, padding=3))]
         for stride in strides:
             d_model *= 2
             block.append(MiniMaxH3AudioEncoderBlock(d_model, stride=stride))
         block += [
             MiniMaxH3AudioSnake1d(d_model),
-            _wn_conv1d(d_model, d_latent, kernel_size=3, padding=1),
+            weight_norm(nn.Conv1d(d_model, d_latent, kernel_size=3, padding=1)),
         ]
         self.block = nn.Sequential(*block)
 
@@ -403,12 +401,15 @@ def __init__(self, channels: int, kernel_size: int, dilation: tuple[int, ...]):
         super().__init__()
         self.convs1 = nn.ModuleList(
             [
-                _wn_conv1d(channels, channels, kernel_size, dilation=d, padding=(kernel_size * d - d) // 2)
+                weight_norm(nn.Conv1d(channels, channels, kernel_size, dilation=d, padding=(kernel_size * d - d) // 2))
                 for d in dilation
             ]
         )
         self.convs2 = nn.ModuleList(
-            [_wn_conv1d(channels, channels, kernel_size, dilation=1, padding=(kernel_size - 1) // 2) for _ in dilation]
+            [
+                weight_norm(nn.Conv1d(channels, channels, kernel_size, dilation=1, padding=(kernel_size - 1) // 2))
+                for _ in dilation
+            ]
         )
         self.activations = nn.ModuleList(
             [
@@ -442,7 +443,7 @@ def __init__(
         self.num_kernels = len(resblock_kernel_sizes)
         self.num_upsamples = len(upsample_rates)
 
-        self.conv_pre = _wn_conv1d(in_channels, upsample_initial_channel, 7, 1, padding=3)
+        self.conv_pre = weight_norm(nn.Conv1d(in_channels, upsample_initial_channel, 7, 1, padding=3))
 
         # Each upsampler is wrapped in a one-element `ModuleList` in the original checkpoint
         # (`ups.<i>.0`); the extra nesting is kept so the state dict stays a passthrough.
@@ -471,7 +472,7 @@ def __init__(
                 self.resblocks.append(MiniMaxH3AudioAMPBlock(channels, kernel, tuple(dilation)))
 
         self.activation_post = MiniMaxH3AudioActivation1d(activation=MiniMaxH3AudioSnakeBeta(channels))
-        self.conv_post = _wn_conv1d(channels, 1, 7, 1, padding=3, bias=False)
+        self.conv_post = weight_norm(nn.Conv1d(channels, 1, 7, 1, padding=3, bias=False))
 
     def forward(self, hidden_states: torch.Tensor) -> torch.Tensor:
         hidden_states = self.conv_pre(hidden_states)

From d6050f4217aeebf543aaa402c982d6350eb2c44e Mon Sep 17 00:00:00 2001
From: yiyixuxu <yixu310@gmail.com>
Date: Sun, 2 Aug 2026 18:53:33 +0000
Subject: [PATCH 06/16] Give the MiniMax-H3 blocks their latents back
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

A second pass over the blockset, all of it structural — the generated video and
soundtrack are unchanged.

The decoders used to take packed rows plus five geometry scalars and unpack them
on the way in, so they could not accept latents from anywhere else and an
injected step between denoise and decode would have had to work in row space. An
after-denoise step now drops the conditioning rows and unpacks both modalities,
following `Flux2UnpackLatentsStep` and `QwenImageAfterDenoiseStep`, leaving the
decoders to denormalize and decode. `output_type="latent"` goes with it: popping
the decoder is how a modular pipeline hands back latents, and the branch had the
declared outputs lying about their own types.

`MiniMaxH3PackedSequence` is gone. It was the only internal dataclass in the
blockset and it made the layout step publish its index tensors twice, once as CPU
copies inside the dataclass and once as device copies on the block state. The
builders return a tuple and `set_timesteps` declares the four values it actually
reads instead of taking the whole layout.

The denoiser stops enumerating the rows of the packed sequence. The layout tags
`token_tags`, `position_ids` and the three index tensors as
`denoiser_input_fields` — their names are already the transformer's own — so the
denoise block declares one input and forwards what the signature accepts.

`encode_prompt` takes the conditioner it needs rather than the whole component
bag, and the modality tags it writes are arguments with defaults.

The `17` and `5` of the chunking were module constants duplicating the video
VAE's `clip_length` and `tokens_chunk_size`; they are read off the component now,
so a checkpoint that chunks differently cannot silently disagree with the packing.

Every remaining helper with one or two callers is inlined into them.

Two notes left in place: a TODO on firing the conditioner's offload hook by hand,
which needs a real answer rather than a workaround, and a check that the
conditioning rows the layout reserved match the conditioning that was encoded —
in a hand-assembled chain the canvas is user input, and the mismatch used to
surface as an `index_copy` shape error inside the transformer.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
---
 .../minimax_h3/before_denoise.py              | 154 +++++++++----
 .../minimax_h3/before_encoder.py              |  14 +-
 .../modular_pipelines/minimax_h3/decoders.py  | 195 ++++++++++------
 .../modular_pipelines/minimax_h3/denoise.py   | 213 ++++++++++--------
 .../modular_pipelines/minimax_h3/encoders.py  | 183 ++++++++-------
 .../minimax_h3/modular_blocks_minimax_h3.py   | 152 +++++++------
 .../minimax_h3/modular_pipeline.py            |  12 +
 .../modular_pipelines/minimax_h3/packing.py   | 151 +++----------
 .../minimax_h3/packing_ref2va.py              |  33 ++-
 9 files changed, 613 insertions(+), 494 deletions(-)

diff --git a/src/diffusers/modular_pipelines/minimax_h3/before_denoise.py b/src/diffusers/modular_pipelines/minimax_h3/before_denoise.py
index c0a1a0811dea..cecb04598e37 100644
--- a/src/diffusers/modular_pipelines/minimax_h3/before_denoise.py
+++ b/src/diffusers/modular_pipelines/minimax_h3/before_denoise.py
@@ -27,7 +27,6 @@
     MINIMAX_H3_KEYFRAME_NOISE_AUG,
     MINIMAX_H3_MAX_DURATION,
     MINIMAX_H3_MIN_DURATION,
-    MiniMaxH3PackedSequence,
     align_num_frames,
     audio_latent_num_frames,
     build_packed_sequence,
@@ -95,28 +94,36 @@ def intermediate_outputs(self) -> list[OutputParam]:
             OutputParam(
                 "num_audio_latents", type_hint=int, description="Number of generated audio latents per channel."
             ),
-            OutputParam(
-                "layout",
-                type_hint=MiniMaxH3PackedSequence,
-                description="The structural description of the packed sequence.",
-            ),
             OutputParam(
                 "position_ids",
                 type_hint=torch.Tensor,
+                kwargs_type="denoiser_input_fields",
                 description="The `(t, h, w)` rotary coordinate of every row, in float64.",
             ),
-            OutputParam("token_tags", type_hint=torch.Tensor, description="The modality tag of every row."),
+            OutputParam(
+                "token_tags",
+                type_hint=torch.Tensor,
+                kwargs_type="denoiser_input_fields",
+                description="The modality tag of every row.",
+            ),
             OutputParam(
                 "video_indices",
                 type_hint=torch.Tensor,
+                kwargs_type="denoiser_input_fields",
                 description="Sequence positions of the video rows, conditioning rows first.",
             ),
             OutputParam(
                 "audio_indices",
                 type_hint=torch.Tensor,
+                kwargs_type="denoiser_input_fields",
                 description="Sequence positions of the audio rows, reference rows first.",
             ),
-            OutputParam("text_indices", type_hint=torch.Tensor, description="Sequence positions of the text rows."),
+            OutputParam(
+                "text_indices",
+                type_hint=torch.Tensor,
+                kwargs_type="denoiser_input_fields",
+                description="Sequence positions of the text rows.",
+            ),
             OutputParam(
                 "num_condition_video_rows",
                 type_hint=int,
@@ -143,7 +150,9 @@ def __call__(self, components: MiniMaxH3ModularPipeline, state: PipelineState) -
                 f"{block_state.height}x{block_state.width}."
             )
 
-        aligned_num_frames = align_num_frames(block_state.num_frames)
+        frames_per_chunk = components.vae_frames_per_chunk
+        latents_per_chunk = components.vae_latents_per_chunk
+        aligned_num_frames = align_num_frames(block_state.num_frames, frames_per_chunk, latents_per_chunk)
         if aligned_num_frames != block_state.num_frames:
             logger.warning(
                 f"`num_frames` has to be of the form 17 * n + 5 for the video VAE; rounding {block_state.num_frames} "
@@ -162,12 +171,22 @@ def __call__(self, components: MiniMaxH3ModularPipeline, state: PipelineState) -
             )
 
         ratio = components.vae_spatial_compression_ratio
-        block_state.num_latent_frames = video_latent_num_frames(block_state.num_frames)
+        block_state.num_latent_frames = video_latent_num_frames(
+            block_state.num_frames, frames_per_chunk, latents_per_chunk
+        )
         block_state.latent_height = block_state.height // ratio
         block_state.latent_width = block_state.width // ratio
         block_state.num_audio_latents = audio_latent_num_frames(block_state.num_frames)
 
-        layout = build_packed_sequence(
+        (
+            position_ids,
+            token_tags,
+            video_indices,
+            audio_indices,
+            text_indices,
+            block_state.num_condition_video_rows,
+            block_state.num_condition_audio_rows,
+        ) = build_packed_sequence(
             block_state.text_token_tags,
             block_state.num_latent_frames,
             block_state.latent_height,
@@ -176,14 +195,11 @@ def __call__(self, components: MiniMaxH3ModularPipeline, state: PipelineState) -
             components.patch_size,
             block_state.keyframe_anchors,
         )
-        block_state.layout = layout
-        block_state.position_ids = layout.position_ids.to(device)
-        block_state.token_tags = layout.token_tags.to(device)
-        block_state.video_indices = layout.video_indices.to(device)
-        block_state.audio_indices = layout.audio_indices.to(device)
-        block_state.text_indices = layout.text_indices.to(device)
-        block_state.num_condition_video_rows = layout.num_condition_video_rows
-        block_state.num_condition_audio_rows = layout.num_condition_audio_rows
+        block_state.position_ids = position_ids.to(device)
+        block_state.token_tags = token_tags.to(device)
+        block_state.video_indices = video_indices.to(device)
+        block_state.audio_indices = audio_indices.to(device)
+        block_state.text_indices = text_indices.to(device)
 
         self.set_block_state(state, block_state)
         return components, state
@@ -237,28 +253,36 @@ def intermediate_outputs(self) -> list[OutputParam]:
             OutputParam(
                 "num_audio_latents", type_hint=int, description="Number of generated audio latents per channel."
             ),
-            OutputParam(
-                "layout",
-                type_hint=MiniMaxH3PackedSequence,
-                description="The structural description of the packed sequence.",
-            ),
             OutputParam(
                 "position_ids",
                 type_hint=torch.Tensor,
+                kwargs_type="denoiser_input_fields",
                 description="The `(t, h, w)` rotary coordinate of every row, in float64.",
             ),
-            OutputParam("token_tags", type_hint=torch.Tensor, description="The modality tag of every row."),
+            OutputParam(
+                "token_tags",
+                type_hint=torch.Tensor,
+                kwargs_type="denoiser_input_fields",
+                description="The modality tag of every row.",
+            ),
             OutputParam(
                 "video_indices",
                 type_hint=torch.Tensor,
+                kwargs_type="denoiser_input_fields",
                 description="Sequence positions of the video rows, conditioning rows first.",
             ),
             OutputParam(
                 "audio_indices",
                 type_hint=torch.Tensor,
+                kwargs_type="denoiser_input_fields",
                 description="Sequence positions of the audio rows, reference rows first.",
             ),
-            OutputParam("text_indices", type_hint=torch.Tensor, description="Sequence positions of the text rows."),
+            OutputParam(
+                "text_indices",
+                type_hint=torch.Tensor,
+                kwargs_type="denoiser_input_fields",
+                description="Sequence positions of the text rows.",
+            ),
             OutputParam(
                 "num_condition_video_rows",
                 type_hint=int,
@@ -279,12 +303,22 @@ def __call__(self, components: MiniMaxH3Ref2VAModularPipeline, state: PipelineSt
         # The canvas and the frame count are settled by the setup step: a `ref2va` soundtrack is truncated to the
         # generated duration as the references are prepared, so `num_frames` has to be final before that runs.
         ratio = components.vae_spatial_compression_ratio
-        block_state.num_latent_frames = video_latent_num_frames(block_state.num_frames)
+        block_state.num_latent_frames = video_latent_num_frames(
+            block_state.num_frames, components.vae_frames_per_chunk, components.vae_latents_per_chunk
+        )
         block_state.latent_height = block_state.height // ratio
         block_state.latent_width = block_state.width // ratio
         block_state.num_audio_latents = audio_latent_num_frames(block_state.num_frames)
 
-        layout = build_ref2va_packed_sequence(
+        (
+            position_ids,
+            token_tags,
+            video_indices,
+            audio_indices,
+            text_indices,
+            block_state.num_condition_video_rows,
+            block_state.num_condition_audio_rows,
+        ) = build_ref2va_packed_sequence(
             block_state.text_token_tags,
             block_state.prepared_references,
             block_state.num_latent_frames,
@@ -293,14 +327,11 @@ def __call__(self, components: MiniMaxH3Ref2VAModularPipeline, state: PipelineSt
             block_state.num_audio_latents,
             components.patch_size,
         )
-        block_state.layout = layout
-        block_state.position_ids = layout.position_ids.to(device)
-        block_state.token_tags = layout.token_tags.to(device)
-        block_state.video_indices = layout.video_indices.to(device)
-        block_state.audio_indices = layout.audio_indices.to(device)
-        block_state.text_indices = layout.text_indices.to(device)
-        block_state.num_condition_video_rows = layout.num_condition_video_rows
-        block_state.num_condition_audio_rows = layout.num_condition_audio_rows
+        block_state.position_ids = position_ids.to(device)
+        block_state.token_tags = token_tags.to(device)
+        block_state.video_indices = video_indices.to(device)
+        block_state.audio_indices = audio_indices.to(device)
+        block_state.text_indices = text_indices.to(device)
 
         self.set_block_state(state, block_state)
         return components, state
@@ -354,6 +385,12 @@ def inputs(self) -> list[InputParam]:
                 type_hint=torch.Tensor,
                 description="Pre-generated audio noise of shape `(2, 32, num_audio_latents)`.",
             ),
+            InputParam(
+                name="num_condition_video_rows",
+                type_hint=int,
+                default=0,
+                description="How many conditioning rows the layout reserved, which the packed conditioning must match.",
+            ),
             InputParam(
                 name="condition_latents",
                 type_hint=list[torch.Tensor],
@@ -409,6 +446,15 @@ def __call__(self, components: MiniMaxH3ModularPipeline, state: PipelineState) -
                 noised = components.scheduler.scale_noise(condition.to(device), MINIMAX_H3_KEYFRAME_NOISE_AUG, noise)
                 packed.append(patchify_video_latents(noised, patch_size))
             condition_rows = torch.cat(packed)
+            # In a hand-assembled chain the canvas reaching the layout is user input, so it can disagree with the
+            # keyframes that were actually encoded. Left alone the mismatch first surfaces as an `index_copy` shape
+            # error inside the transformer, 50 layers deep.
+            if condition_rows.shape[0] != block_state.num_condition_video_rows:
+                raise ValueError(
+                    f"The layout reserved {block_state.num_condition_video_rows} conditioning rows but the encoded "
+                    f"conditioning latents pack into {condition_rows.shape[0]}. The canvas the layout was built from "
+                    "and the one the conditioning was encoded at do not agree."
+                )
 
         latents = block_state.latents
         if latents is None:
@@ -474,10 +520,34 @@ def inputs(self) -> list[InputParam]:
         return [
             InputParam.template("num_inference_steps", required=True),
             InputParam(
-                name="layout",
-                type_hint=MiniMaxH3PackedSequence,
+                name="video_indices",
+                type_hint=torch.Tensor,
+                required=True,
+                description="Sequence positions of the video rows, conditioning rows first.",
+            ),
+            InputParam(
+                name="audio_indices",
+                type_hint=torch.Tensor,
                 required=True,
-                description="The structural description of the packed sequence.",
+                description="Sequence positions of the audio rows, reference rows first.",
+            ),
+            InputParam(
+                name="text_indices",
+                type_hint=torch.Tensor,
+                required=True,
+                description="Sequence positions of the text rows.",
+            ),
+            InputParam(
+                name="num_condition_video_rows",
+                type_hint=int,
+                default=0,
+                description="How many leading video rows are conditioning rows.",
+            ),
+            InputParam(
+                name="num_condition_audio_rows",
+                type_hint=int,
+                default=0,
+                description="How many leading audio rows are reference rows.",
             ),
         ]
 
@@ -510,7 +580,11 @@ def __call__(self, components: MiniMaxH3ModularPipeline, state: PipelineState) -
             tuple(
                 tensor.to(device)
                 for tensor in build_row_timesteps(
-                    block_state.layout,
+                    block_state.video_indices,
+                    block_state.audio_indices,
+                    block_state.num_condition_video_rows,
+                    block_state.num_condition_audio_rows,
+                    block_state.text_indices.numel(),
                     float(timestep),
                     float(audio_timestep),
                     max(float(timestep), MINIMAX_H3_KEYFRAME_NOISE_AUG),
diff --git a/src/diffusers/modular_pipelines/minimax_h3/before_encoder.py b/src/diffusers/modular_pipelines/minimax_h3/before_encoder.py
index f32e521002cd..86c045be683e 100644
--- a/src/diffusers/modular_pipelines/minimax_h3/before_encoder.py
+++ b/src/diffusers/modular_pipelines/minimax_h3/before_encoder.py
@@ -183,7 +183,13 @@ def _check_inputs(components, block_state) -> None:
             )
         # The duration the request generates is the one of the *aligned* frame count, so that is what the ceiling has
         # to hold for: 346 frames would otherwise pass the check and then be rounded up to 362, i.e. 15.083 seconds.
-        aligned_num_frames = None if block_state.num_frames is None else align_num_frames(block_state.num_frames)
+        aligned_num_frames = (
+            None
+            if block_state.num_frames is None
+            else align_num_frames(
+                block_state.num_frames, components.vae_frames_per_chunk, components.vae_latents_per_chunk
+            )
+        )
         duration = None if aligned_num_frames is None else aligned_num_frames / MINIMAX_H3_FPS
         if duration is not None and not MINIMAX_H3_MIN_DURATION <= duration <= MINIMAX_H3_MAX_DURATION:
             raise ValueError(
@@ -310,7 +316,9 @@ def prepare_references(
                     f"`references[{index}]` is {duration:g} seconds long, outside the "
                     f"{MINIMAX_H3_MIN_DURATION} to {MINIMAX_H3_MAX_DURATION} seconds MiniMax-H3 generates."
                 )
-            num_frames = align_num_frames(round(duration * MINIMAX_H3_FPS))
+            num_frames = align_num_frames(
+                round(duration * MINIMAX_H3_FPS), components.vae_frames_per_chunk, components.vae_latents_per_chunk
+            )
             # The duration the request generates is the one of the *aligned* frame count, so that is what the
             # ceiling has to hold for: a 14.99 second soundtrack rounds up to 362 frames, i.e. 15.083 seconds.
             if num_frames / MINIMAX_H3_FPS > MINIMAX_H3_MAX_DURATION:
@@ -320,7 +328,7 @@ def prepare_references(
                     f"{MINIMAX_H3_MAX_DURATION} seconds MiniMax-H3 generates. Pass `num_frames` to generate a "
                     "shorter video from this soundtrack."
                 )
-        num_frames = align_num_frames(num_frames)
+        num_frames = align_num_frames(num_frames, components.vae_frames_per_chunk, components.vae_latents_per_chunk)
 
         for reference, entry in zip(resolved, references):
             if reference.kind == "image":
diff --git a/src/diffusers/modular_pipelines/minimax_h3/decoders.py b/src/diffusers/modular_pipelines/minimax_h3/decoders.py
index fc4ee359267b..2eec15d15638 100644
--- a/src/diffusers/modular_pipelines/minimax_h3/decoders.py
+++ b/src/diffusers/modular_pipelines/minimax_h3/decoders.py
@@ -21,27 +21,123 @@
 from ..modular_pipeline import ModularPipelineBlocks, PipelineState
 from ..modular_pipeline_utils import ComponentSpec, InputParam, OutputParam
 from .modular_pipeline import MiniMaxH3ModularPipeline
-from .packing import (
-    MINIMAX_H3_PIXEL_MEAN,
-    MINIMAX_H3_PIXEL_STD,
-    unpack_audio_tokens,
-    unpatchify_video_tokens,
-)
+from .packing import MINIMAX_H3_AUDIO_CHANNELS, MINIMAX_H3_PIXEL_MEAN, MINIMAX_H3_PIXEL_STD
 
 
 logger = logging.get_logger(__name__)  # pylint: disable=invalid-name
 
 
+class MiniMaxH3AfterDenoiseStep(ModularPipelineBlocks):
+    model_name = "minimax-h3"
+
+    @property
+    def description(self) -> str:
+        return (
+            "Turns the denoised rows of the packed sequence back into latents: drops the conditioning rows the loop "
+            "never wrote, then unpacks the video rows into `(1, latent_channels, num_latent_frames, latent_height, "
+            "latent_width)` and the channel-major audio rows into the `(2, audio_latent_channels, num_audio_latents)` "
+            "the mono audio VAE consumes. The decoders then take latents from any source, and popping them leaves "
+            "latents in hand."
+        )
+
+    @property
+    def inputs(self) -> list[InputParam]:
+        return [
+            InputParam(
+                name="latents",
+                type_hint=torch.Tensor,
+                required=True,
+                description="The denoised video rows of the packed sequence, conditioning rows first.",
+            ),
+            InputParam(
+                name="audio_latents",
+                type_hint=torch.Tensor,
+                required=True,
+                description="The denoised audio rows of the packed sequence, reference rows first.",
+            ),
+            InputParam(
+                name="num_condition_video_rows",
+                type_hint=int,
+                default=0,
+                description="How many leading video rows are conditioning rows and are dropped here.",
+            ),
+            InputParam(
+                name="num_condition_audio_rows",
+                type_hint=int,
+                default=0,
+                description="How many leading audio rows are reference rows and are dropped here.",
+            ),
+            InputParam(
+                name="num_latent_frames", type_hint=int, required=True, description="Number of video latent frames."
+            ),
+            InputParam(name="latent_height", type_hint=int, required=True, description="Height of the video latents."),
+            InputParam(name="latent_width", type_hint=int, required=True, description="Width of the video latents."),
+            InputParam(
+                name="num_audio_latents",
+                type_hint=int,
+                required=True,
+                description="Number of audio latents per channel.",
+            ),
+        ]
+
+    @property
+    def intermediate_outputs(self) -> list[OutputParam]:
+        return [
+            OutputParam(
+                "latents",
+                type_hint=torch.Tensor,
+                description="The generated video latents, of shape `(1, latent_channels, num_latent_frames, "
+                "latent_height, latent_width)`.",
+            ),
+            OutputParam(
+                "audio_latents",
+                type_hint=torch.Tensor,
+                description="The generated audio latents, one batch item per stereo channel.",
+            ),
+        ]
+
+    @torch.no_grad()
+    def __call__(self, components: MiniMaxH3ModularPipeline, state: PipelineState) -> PipelineState:
+        block_state = self.get_block_state(state)
+        patch_t, patch_h, patch_w = components.patch_size
+        channels = components.vae_latent_channels
+
+        # The inverse of the patchify in the prepare-latents step: rows are frame-major then row-major.
+        rows = block_state.latents[block_state.num_condition_video_rows :]
+        rows = rows.reshape(
+            -1,
+            block_state.num_latent_frames // patch_t,
+            block_state.latent_height // patch_h,
+            block_state.latent_width // patch_w,
+            channels,
+            patch_t,
+            patch_h,
+            patch_w,
+        )
+        rows = rows.permute(0, 4, 1, 5, 2, 6, 3, 7)
+        block_state.latents = rows.reshape(
+            -1, channels, block_state.num_latent_frames, block_state.latent_height, block_state.latent_width
+        ).contiguous()
+
+        # Audio rows are channel-major, and the mono audio VAE takes the two stereo channels as two batch items.
+        audio_rows = block_state.audio_latents[block_state.num_condition_audio_rows :]
+        audio_rows = audio_rows.reshape(MINIMAX_H3_AUDIO_CHANNELS, block_state.num_audio_latents, audio_rows.shape[-1])
+        block_state.audio_latents = audio_rows.permute(0, 2, 1).contiguous()
+
+        self.set_block_state(state, block_state)
+        return components, state
+
+
 class MiniMaxH3VideoDecodeStep(ModularPipelineBlocks):
     model_name = "minimax-h3"
 
     @property
     def description(self) -> str:
         return (
-            "Unpacks the generated video rows back into latents, denormalizes them and decodes them into video. The "
-            "spatial tiling of the video VAE covers the canvas exactly, so the decoded frames need no crop back, but "
-            "the decode itself runs under float16 autocast even though the VAE weights are float32, and the VAE "
-            "produces ImageNet-normalized RGB that is reverted here."
+            "Denormalizes the generated video latents and decodes them into video. The spatial tiling of the video "
+            "VAE covers the canvas exactly, so the decoded frames need no crop back, but the decode itself runs under "
+            "float16 autocast even though the VAE weights are float32, and the VAE produces ImageNet-normalized RGB "
+            "that is reverted here."
         )
 
     @property
@@ -65,22 +161,9 @@ def inputs(self) -> list[InputParam]:
                 name="latents",
                 type_hint=torch.Tensor,
                 required=True,
-                description="The denoised video rows of the packed sequence, conditioning rows first.",
-            ),
-            InputParam(
-                name="num_condition_video_rows",
-                type_hint=int,
-                default=0,
-                description="How many leading video rows are conditioning rows and are dropped here.",
-            ),
-            InputParam(
-                name="num_latent_frames", type_hint=int, required=True, description="Number of video latent frames."
-            ),
-            InputParam(name="latent_height", type_hint=int, required=True, description="Height of the video latents."),
-            InputParam(name="latent_width", type_hint=int, required=True, description="Width of the video latents."),
-            InputParam.template(
-                "output_type", description="Output format: 'pil', 'np', 'pt' or 'latent' for the raw latents."
+                description="The generated video latents.",
             ),
+            InputParam.template("output_type", description="Output format: 'pil', 'np' or 'pt'."),
         ]
 
     @property
@@ -92,29 +175,16 @@ def __call__(self, components: MiniMaxH3ModularPipeline, state: PipelineState) -
         block_state = self.get_block_state(state)
         device = components._execution_device
 
-        latents = unpatchify_video_tokens(
-            block_state.latents[block_state.num_condition_video_rows :],
-            block_state.num_latent_frames,
-            block_state.latent_height,
-            block_state.latent_width,
-            components.vae_latent_channels,
-            components.patch_size,
-        )
         latents_mean = torch.tensor(components.vae.config.latents_mean, device=device).view(1, -1, 1, 1, 1)
         latents_std = torch.tensor(components.vae.config.latents_std, device=device).view(1, -1, 1, 1, 1)
-        latents = latents * latents_std + latents_mean
-
-        if block_state.output_type == "latent":
-            block_state.videos = latents
-        else:
-            with torch.autocast(device_type=device.type, dtype=torch.float16, enabled=device.type == "cuda"):
-                video = components.vae.decode(latents, return_dict=False)[0]
-            pixel_mean = torch.tensor(MINIMAX_H3_PIXEL_MEAN, device=device).view(1, -1, 1, 1, 1)
-            pixel_std = torch.tensor(MINIMAX_H3_PIXEL_STD, device=device).view(1, -1, 1, 1, 1)
-            video = (video.float() * pixel_std + pixel_mean).clamp(0, 1)
-            block_state.videos = components.video_processor.postprocess_video(
-                video, output_type=block_state.output_type
-            )
+        latents = block_state.latents * latents_std + latents_mean
+
+        with torch.autocast(device_type=device.type, dtype=torch.float16, enabled=device.type == "cuda"):
+            video = components.vae.decode(latents, return_dict=False)[0]
+        pixel_mean = torch.tensor(MINIMAX_H3_PIXEL_MEAN, device=device).view(1, -1, 1, 1, 1)
+        pixel_std = torch.tensor(MINIMAX_H3_PIXEL_STD, device=device).view(1, -1, 1, 1, 1)
+        video = (video.float() * pixel_std + pixel_mean).clamp(0, 1)
+        block_state.videos = components.video_processor.postprocess_video(video, output_type=block_state.output_type)
 
         self.set_block_state(state, block_state)
         return components, state
@@ -126,8 +196,8 @@ class MiniMaxH3AudioDecodeStep(ModularPipelineBlocks):
     @property
     def description(self) -> str:
         return (
-            "Unpacks the generated audio rows back into latents, denormalizes them and decodes them into a stereo "
-            "waveform. The audio VAE is mono and takes the two stereo channels as two batch items."
+            "Denormalizes the generated audio latents and decodes them into a stereo waveform. The audio VAE is mono "
+            "and takes the two stereo channels as two batch items."
         )
 
     @property
@@ -141,22 +211,7 @@ def inputs(self) -> list[InputParam]:
                 name="audio_latents",
                 type_hint=torch.Tensor,
                 required=True,
-                description="The denoised audio rows of the packed sequence, reference rows first.",
-            ),
-            InputParam(
-                name="num_condition_audio_rows",
-                type_hint=int,
-                default=0,
-                description="How many leading audio rows are reference rows and are dropped here.",
-            ),
-            InputParam(
-                name="num_audio_latents",
-                type_hint=int,
-                required=True,
-                description="Number of audio latents per channel.",
-            ),
-            InputParam.template(
-                "output_type", description="Output format: 'pil', 'np', 'pt' or 'latent' for the raw latents."
+                description="The generated audio latents, one batch item per stereo channel.",
             ),
         ]
 
@@ -180,18 +235,12 @@ def __call__(self, components: MiniMaxH3ModularPipeline, state: PipelineState) -
         block_state = self.get_block_state(state)
         device = components._execution_device
 
-        audio_latents = unpack_audio_tokens(
-            block_state.audio_latents[block_state.num_condition_audio_rows :], block_state.num_audio_latents
-        )
         audio_latents_mean = torch.tensor(components.audio_vae.config.latents_mean, device=device).view(1, -1, 1)
         audio_latents_std = torch.tensor(components.audio_vae.config.latents_std, device=device).view(1, -1, 1)
-        audio_latents = audio_latents * audio_latents_std + audio_latents_mean
+        audio_latents = block_state.audio_latents * audio_latents_std + audio_latents_mean
 
-        if block_state.output_type == "latent":
-            block_state.audio = audio_latents
-        else:
-            audio = components.audio_vae.decode(audio_latents, return_dict=False)[0]
-            block_state.audio = audio.float().permute(1, 0, 2)
+        audio = components.audio_vae.decode(audio_latents, return_dict=False)[0]
+        block_state.audio = audio.float().permute(1, 0, 2)
         block_state.sampling_rate = components.audio_sampling_rate
 
         self.set_block_state(state, block_state)
diff --git a/src/diffusers/modular_pipelines/minimax_h3/denoise.py b/src/diffusers/modular_pipelines/minimax_h3/denoise.py
index d149273371bb..156242907339 100644
--- a/src/diffusers/modular_pipelines/minimax_h3/denoise.py
+++ b/src/diffusers/modular_pipelines/minimax_h3/denoise.py
@@ -12,6 +12,8 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+import inspect
+
 import torch
 
 from ...models import MiniMaxH3Transformer3DModel
@@ -30,91 +32,6 @@
 logger = logging.get_logger(__name__)  # pylint: disable=invalid-name
 
 
-def _denoiser_inputs() -> list[InputParam]:
-    r"""Everything one MiniMax-H3 forward reads, beyond the transformer itself."""
-    return [
-        InputParam(
-            name="latents",
-            type_hint=torch.Tensor,
-            required=True,
-            description="The video rows of the packed sequence, conditioning rows first.",
-        ),
-        InputParam(
-            name="audio_latents",
-            type_hint=torch.Tensor,
-            required=True,
-            description="The channel-major audio rows of the packed sequence, reference rows first.",
-        ),
-        InputParam.template("prompt_embeds"),
-        InputParam(
-            name="row_timestep_plan",
-            type_hint=list,
-            required=True,
-            description="One `(timestep, timestep_indices)` pair per step.",
-        ),
-        InputParam(
-            name="token_tags", type_hint=torch.Tensor, required=True, description="The modality tag of every row."
-        ),
-        InputParam(
-            name="position_ids",
-            type_hint=torch.Tensor,
-            required=True,
-            description="The `(t, h, w)` rotary coordinate of every row.",
-        ),
-        InputParam(
-            name="video_indices",
-            type_hint=torch.Tensor,
-            required=True,
-            description="Sequence positions of the video rows.",
-        ),
-        InputParam(
-            name="audio_indices",
-            type_hint=torch.Tensor,
-            required=True,
-            description="Sequence positions of the audio rows.",
-        ),
-        InputParam(
-            name="text_indices",
-            type_hint=torch.Tensor,
-            required=True,
-            description="Sequence positions of the text rows.",
-        ),
-        InputParam.template("attention_kwargs"),
-    ]
-
-
-def _denoiser_outputs() -> list[OutputParam]:
-    return [
-        OutputParam(
-            "noise_pred", type_hint=torch.Tensor, description="Predicted velocity of the video rows of the sequence."
-        ),
-        OutputParam(
-            "audio_noise_pred",
-            type_hint=torch.Tensor,
-            description="Predicted velocity of the audio rows of the sequence.",
-        ),
-    ]
-
-
-def _predict_velocity(transformer: MiniMaxH3Transformer3DModel, block_state: BlockState, i: int):
-    r"""One MiniMax-H3 forward pass: every row of the packed sequence, at its own noise level, at once."""
-    unique_timesteps, timestep_indices = block_state.row_timestep_plan[i]
-    return transformer(
-        hidden_states=block_state.latents[None],
-        audio_hidden_states=block_state.audio_latents[None],
-        encoder_hidden_states=block_state.prompt_embeds,
-        timestep=unique_timesteps,
-        timestep_indices=timestep_indices,
-        token_tags=block_state.token_tags,
-        position_ids=block_state.position_ids,
-        video_indices=block_state.video_indices,
-        audio_indices=block_state.audio_indices,
-        text_indices=block_state.text_indices,
-        attention_kwargs=block_state.attention_kwargs,
-        return_dict=False,
-    )
-
-
 class MiniMaxH3LoopDenoiser(ModularPipelineBlocks):
     model_name = "minimax-h3"
 
@@ -132,16 +49,71 @@ def expected_components(self) -> list[ComponentSpec]:
 
     @property
     def inputs(self) -> list[InputParam]:
-        return _denoiser_inputs()
+        return [
+            InputParam(
+                name="latents",
+                type_hint=torch.Tensor,
+                required=True,
+                description="The video rows of the packed sequence, conditioning rows first.",
+            ),
+            InputParam(
+                name="audio_latents",
+                type_hint=torch.Tensor,
+                required=True,
+                description="The channel-major audio rows of the packed sequence, reference rows first.",
+            ),
+            InputParam.template("prompt_embeds"),
+            InputParam(
+                name="row_timestep_plan",
+                type_hint=list,
+                required=True,
+                description="One `(timestep, timestep_indices)` pair per step.",
+            ),
+            InputParam(
+                kwargs_type="denoiser_input_fields",
+                description=(
+                    "The structural description of the packed sequence the transformer reads by name: `token_tags`, "
+                    "`position_ids` and the three row-index tensors."
+                ),
+            ),
+            InputParam.template("attention_kwargs"),
+        ]
 
     @property
     def intermediate_outputs(self) -> list[OutputParam]:
-        return _denoiser_outputs()
+        return [
+            OutputParam(
+                "noise_pred",
+                type_hint=torch.Tensor,
+                description="Predicted velocity of the video rows of the sequence.",
+            ),
+            OutputParam(
+                "audio_noise_pred",
+                type_hint=torch.Tensor,
+                description="Predicted velocity of the audio rows of the sequence.",
+            ),
+        ]
 
     @torch.no_grad()
     def __call__(self, components: MiniMaxH3ModularPipeline, block_state: BlockState, i: int, t: torch.Tensor):
-        block_state.noise_pred, block_state.audio_noise_pred = _predict_velocity(
-            components.transformer, block_state, i
+        transformer = components.transformer
+        unique_timesteps, timestep_indices = block_state.row_timestep_plan[i]
+        # The layout tags its outputs `denoiser_input_fields`, and their names are the transformer's own parameter
+        # names, so the rows of the packed sequence are described to it without this block enumerating them.
+        layout_kwargs = {
+            name: value
+            for name, value in block_state.denoiser_input_fields.items()
+            if name in inspect.signature(transformer.forward).parameters
+        }
+        block_state.noise_pred, block_state.audio_noise_pred = transformer(
+            hidden_states=block_state.latents[None],
+            audio_hidden_states=block_state.audio_latents[None],
+            encoder_hidden_states=block_state.prompt_embeds,
+            timestep=unique_timesteps,
+            timestep_indices=timestep_indices,
+            attention_kwargs=block_state.attention_kwargs,
+            return_dict=False,
+            **layout_kwargs,
         )
         return components, block_state
 
@@ -162,16 +134,71 @@ def expected_components(self) -> list[ComponentSpec]:
 
     @property
     def inputs(self) -> list[InputParam]:
-        return _denoiser_inputs()
+        return [
+            InputParam(
+                name="latents",
+                type_hint=torch.Tensor,
+                required=True,
+                description="The video rows of the packed sequence, conditioning rows first.",
+            ),
+            InputParam(
+                name="audio_latents",
+                type_hint=torch.Tensor,
+                required=True,
+                description="The channel-major audio rows of the packed sequence, reference rows first.",
+            ),
+            InputParam.template("prompt_embeds"),
+            InputParam(
+                name="row_timestep_plan",
+                type_hint=list,
+                required=True,
+                description="One `(timestep, timestep_indices)` pair per step.",
+            ),
+            InputParam(
+                kwargs_type="denoiser_input_fields",
+                description=(
+                    "The structural description of the packed sequence the transformer reads by name: `token_tags`, "
+                    "`position_ids` and the three row-index tensors."
+                ),
+            ),
+            InputParam.template("attention_kwargs"),
+        ]
 
     @property
     def intermediate_outputs(self) -> list[OutputParam]:
-        return _denoiser_outputs()
+        return [
+            OutputParam(
+                "noise_pred",
+                type_hint=torch.Tensor,
+                description="Predicted velocity of the video rows of the sequence.",
+            ),
+            OutputParam(
+                "audio_noise_pred",
+                type_hint=torch.Tensor,
+                description="Predicted velocity of the audio rows of the sequence.",
+            ),
+        ]
 
     @torch.no_grad()
     def __call__(self, components: MiniMaxH3Ref2VAModularPipeline, block_state: BlockState, i: int, t: torch.Tensor):
-        block_state.noise_pred, block_state.audio_noise_pred = _predict_velocity(
-            components.transformer_ref, block_state, i
+        transformer = components.transformer_ref
+        unique_timesteps, timestep_indices = block_state.row_timestep_plan[i]
+        # The layout tags its outputs `denoiser_input_fields`, and their names are the transformer's own parameter
+        # names, so the rows of the packed sequence are described to it without this block enumerating them.
+        layout_kwargs = {
+            name: value
+            for name, value in block_state.denoiser_input_fields.items()
+            if name in inspect.signature(transformer.forward).parameters
+        }
+        block_state.noise_pred, block_state.audio_noise_pred = transformer(
+            hidden_states=block_state.latents[None],
+            audio_hidden_states=block_state.audio_latents[None],
+            encoder_hidden_states=block_state.prompt_embeds,
+            timestep=unique_timesteps,
+            timestep_indices=timestep_indices,
+            attention_kwargs=block_state.attention_kwargs,
+            return_dict=False,
+            **layout_kwargs,
         )
         return components, block_state
 
diff --git a/src/diffusers/modular_pipelines/minimax_h3/encoders.py b/src/diffusers/modular_pipelines/minimax_h3/encoders.py
index 26e3e2b55e5c..e70a40fde61b 100644
--- a/src/diffusers/modular_pipelines/minimax_h3/encoders.py
+++ b/src/diffusers/modular_pipelines/minimax_h3/encoders.py
@@ -40,40 +40,6 @@
 logger = logging.get_logger(__name__)  # pylint: disable=invalid-name
 
 
-def _check_prompt(prompt) -> None:
-    r"""MiniMax-H3 packs one request into one sequence, so a batch of prompts is not a thing."""
-    if not isinstance(prompt, str):
-        raise ValueError(
-            f"MiniMax-H3 packs one request into one sequence, so `prompt` must be a single string, got {type(prompt)}."
-        )
-
-
-def _conditioner_components() -> list[ComponentSpec]:
-    r"""MiniMax-H3's conditioner: a Qwen3-VL read at its 50th decoder layer, with its language-model head unused."""
-    return [
-        ComponentSpec("text_encoder", Qwen3VLForConditionalGeneration),
-        ComponentSpec("tokenizer", Qwen2TokenizerFast),
-        ComponentSpec("processor", Qwen3VLProcessor),
-    ]
-
-
-def _conditioner_outputs() -> list[OutputParam]:
-    return [
-        OutputParam.template(
-            "prompt_embeds",
-            description=(
-                "The hidden state MiniMax-H3 conditions on, of shape `(1, num_text_tokens, 5120)`, read after the "
-                "50th decoder layer of the Qwen3-VL conditioner."
-            ),
-        ),
-        OutputParam(
-            "text_token_tags",
-            type_hint=torch.Tensor,
-            description="The per-row modality tag of every row of `prompt_embeds`; a vision block is tagged as video.",
-        ),
-    ]
-
-
 class MiniMaxH3TextEncoderStep(ModularPipelineBlocks):
     model_name = "minimax-h3"
 
@@ -87,7 +53,11 @@ def description(self) -> str:
 
     @property
     def expected_components(self) -> list[ComponentSpec]:
-        return _conditioner_components()
+        return [
+            ComponentSpec("text_encoder", Qwen3VLForConditionalGeneration),
+            ComponentSpec("tokenizer", Qwen2TokenizerFast),
+            ComponentSpec("processor", Qwen3VLProcessor),
+        ]
 
     @property
     def inputs(self) -> list[InputParam]:
@@ -102,15 +72,34 @@ def inputs(self) -> list[InputParam]:
 
     @property
     def intermediate_outputs(self) -> list[OutputParam]:
-        return _conditioner_outputs()
+        return [
+            OutputParam.template(
+                "prompt_embeds",
+                description=(
+                    "The hidden state MiniMax-H3 conditions on, of shape `(1, num_text_tokens, 5120)`, read after the "
+                    "50th decoder layer of the Qwen3-VL conditioner."
+                ),
+            ),
+            OutputParam(
+                "text_token_tags",
+                type_hint=torch.Tensor,
+                description=(
+                    "The per-row modality tag of every row of `prompt_embeds`; a vision block is tagged as video."
+                ),
+            ),
+        ]
 
     @staticmethod
     def encode_prompt(
-        components,
+        text_encoder,
+        tokenizer,
+        processor,
         prompt: str,
         images: list | None = None,
         device: torch.device | None = None,
         dtype: torch.dtype | None = None,
+        text_tag: int = MINIMAX_H3_TEXT_TAG,
+        video_tag: int = MINIMAX_H3_VIDEO_TAG,
     ) -> tuple[torch.Tensor, torch.Tensor]:
         r"""
         Build MiniMax-H3's presentation of a request and encode it.
@@ -131,10 +120,8 @@ def encode_prompt(
             `tuple[torch.Tensor, torch.Tensor]`: the `(1, num_text_tokens, 5120)` hidden states and the
             `(num_text_tokens,)` per-row modality tags.
         """
-        device = device or components._execution_device
-        dtype = dtype or components.transformer.dtype
 
-        num_layers = components.text_encoder.config.text_config.num_hidden_layers
+        num_layers = text_encoder.config.text_config.num_hidden_layers
         if num_layers <= MINIMAX_H3_TEXT_ENCODER_LAYER:
             raise ValueError(
                 f"MiniMax-H3 conditions on `hidden_states[{MINIMAX_H3_TEXT_ENCODER_LAYER}]` of its Qwen3-VL "
@@ -146,42 +133,46 @@ def encode_prompt(
         pixel_values, image_grid_thw = None, None
         token_ids, token_tags = [], []
         if images:
-            vision = components.processor.image_processor(images=images, return_tensors="pt")
+            vision = processor.image_processor(images=images, return_tensors="pt")
             pixel_values, image_grid_thw = vision["pixel_values"], vision["image_grid_thw"]
-            merge_size = components.processor.image_processor.merge_size**2
+            merge_size = processor.image_processor.merge_size**2
             for index in range(len(images)):
                 num_image_tokens = int(image_grid_thw[index].prod()) // merge_size
-                label_ids = components.tokenizer(f"<Picture {index + 1}>: ", add_special_tokens=False)["input_ids"]
+                label_ids = tokenizer(f"<Picture {index + 1}>: ", add_special_tokens=False)["input_ids"]
                 vision_ids = (
-                    [components.tokenizer.convert_tokens_to_ids("<|vision_start|>")]
-                    + [components.tokenizer.convert_tokens_to_ids("<|image_pad|>")] * num_image_tokens
-                    + [components.tokenizer.convert_tokens_to_ids("<|vision_end|>")]
+                    [tokenizer.convert_tokens_to_ids("<|vision_start|>")]
+                    + [tokenizer.convert_tokens_to_ids("<|image_pad|>")] * num_image_tokens
+                    + [tokenizer.convert_tokens_to_ids("<|vision_end|>")]
                 )
                 token_ids += label_ids + vision_ids
-                token_tags += [MINIMAX_H3_TEXT_TAG] * len(label_ids) + [MINIMAX_H3_VIDEO_TAG] * len(vision_ids)
-        prompt_ids = components.tokenizer(prompt, add_special_tokens=False)["input_ids"]
+                token_tags += [text_tag] * len(label_ids) + [video_tag] * len(vision_ids)
+        prompt_ids = tokenizer(prompt, add_special_tokens=False)["input_ids"]
         token_ids += prompt_ids
-        token_tags += [MINIMAX_H3_TEXT_TAG] * len(prompt_ids)
+        token_tags += [text_tag] * len(prompt_ids)
 
         input_ids = torch.tensor([token_ids], dtype=torch.long, device=device)
         # Qwen3-VL lays its 3D rotary positions out per modality run, which it reads off the token type ids the
         # processor derives from the vision pad ids (`0` text, `1` image, `2` video).
         mm_token_type_ids = torch.tensor(
-            components.processor.create_mm_token_type_ids([token_ids]), dtype=torch.long, device=device
+            processor.create_mm_token_type_ids([token_ids]), dtype=torch.long, device=device
         )
         # `text_encoder.model` is a submodule, and a CPU-offload hook — accelerate's or the one the
         # `ComponentsManager` attaches — wraps the *top-level* module's `forward` alone, so calling the submodule
         # directly would leave the conditioner on the CPU. Fire the hook by hand instead of routing through
         # `text_encoder(...)`: MiniMax-H3 reads `hidden_states[50]` and never uses the language-model head, whose
         # vocabulary-wide projection over every token is all the top-level forward would add.
-        hook = getattr(components.text_encoder, "_hf_hook", None)
+        # TODO: firing another module's offload hook by hand is not something a block should do. It is here
+        # because MiniMax-H3 reads `hidden_states[50]` off `text_encoder.model` while the hook wraps only the
+        # top-level `forward`. Needs a real answer — an opt-in on the conditioner, or a hook that follows
+        # submodule calls.
+        hook = getattr(text_encoder, "_hf_hook", None)
         if hook is not None and hasattr(hook, "pre_forward"):
-            hook.pre_forward(components.text_encoder)
-        outputs = components.text_encoder.model(
+            hook.pre_forward(text_encoder)
+        outputs = text_encoder.model(
             input_ids=input_ids,
             attention_mask=torch.ones_like(input_ids),
             mm_token_type_ids=mm_token_type_ids,
-            pixel_values=None if pixel_values is None else pixel_values.to(device, components.text_encoder.dtype),
+            pixel_values=None if pixel_values is None else pixel_values.to(device, text_encoder.dtype),
             image_grid_thw=None if image_grid_thw is None else image_grid_thw.to(device),
             use_cache=False,
             output_hidden_states=True,
@@ -192,12 +183,18 @@ def encode_prompt(
     @torch.no_grad()
     def __call__(self, components: MiniMaxH3ModularPipeline, state: PipelineState) -> PipelineState:
         block_state = self.get_block_state(state)
-        _check_prompt(block_state.prompt)
+        if not isinstance(block_state.prompt, str):
+            raise ValueError(
+                "MiniMax-H3 packs one request into one sequence, so `prompt` must be a single string, got "
+                f"{type(block_state.prompt)}."
+            )
 
         # `encode_prompt` defaults the embedding dtype to the denoiser's; a text encoder block has no denoiser of
         # its own — it is meant to run on its own — so it emits the conditioner's dtype, as every other model does.
         block_state.prompt_embeds, block_state.text_token_tags = self.encode_prompt(
-            components,
+            components.text_encoder,
+            components.tokenizer,
+            components.processor,
             block_state.prompt,
             block_state.keyframes,
             device=components._execution_device,
@@ -310,7 +307,11 @@ def description(self) -> str:
 
     @property
     def expected_components(self) -> list[ComponentSpec]:
-        return _conditioner_components()
+        return [
+            ComponentSpec("text_encoder", Qwen3VLForConditionalGeneration),
+            ComponentSpec("tokenizer", Qwen2TokenizerFast),
+            ComponentSpec("processor", Qwen3VLProcessor),
+        ]
 
     @property
     def inputs(self) -> list[InputParam]:
@@ -326,11 +327,28 @@ def inputs(self) -> list[InputParam]:
 
     @property
     def intermediate_outputs(self) -> list[OutputParam]:
-        return _conditioner_outputs()
+        return [
+            OutputParam.template(
+                "prompt_embeds",
+                description=(
+                    "The hidden state MiniMax-H3 conditions on, of shape `(1, num_text_tokens, 5120)`, read after the "
+                    "50th decoder layer of the Qwen3-VL conditioner."
+                ),
+            ),
+            OutputParam(
+                "text_token_tags",
+                type_hint=torch.Tensor,
+                description=(
+                    "The per-row modality tag of every row of `prompt_embeds`; a vision block is tagged as video."
+                ),
+            ),
+        ]
 
     @staticmethod
     def encode_prompt(
-        components,
+        text_encoder,
+        tokenizer,
+        processor,
         prompt: str,
         references: list[MiniMaxH3PreparedReference],
         device: torch.device | None = None,
@@ -358,10 +376,8 @@ def encode_prompt(
             `tuple[torch.Tensor, torch.Tensor]`: the `(1, num_text_tokens, 5120)` hidden states and the
             `(num_text_tokens,)` per-row modality tags.
         """
-        device = device or components._execution_device
-        dtype = dtype or components.transformer_ref.dtype
 
-        num_layers = components.text_encoder.config.text_config.num_hidden_layers
+        num_layers = text_encoder.config.text_config.num_hidden_layers
         if num_layers <= MINIMAX_H3_TEXT_ENCODER_LAYER:
             raise ValueError(
                 f"MiniMax-H3 conditions on `hidden_states[{MINIMAX_H3_TEXT_ENCODER_LAYER}]` of its Qwen3-VL "
@@ -370,11 +386,11 @@ def encode_prompt(
                 f"{MINIMAX_H3_TEXT_ENCODER_LAYER} layers is post-norm and is not the conditioning MiniMax-H3 expects."
             )
 
-        merge_size = components.processor.image_processor.merge_size**2
+        merge_size = processor.image_processor.merge_size**2
         pixel_values, image_grid_thw, image_token_counts = None, None, []
         images = [reference.image for reference in references if reference.kind == "image"]
         if images:
-            vision = components.processor.image_processor(images=images, return_tensors="pt")
+            vision = processor.image_processor(images=images, return_tensors="pt")
             pixel_values, image_grid_thw = vision["pixel_values"], vision["image_grid_thw"]
             image_token_counts = [int(grid.prod()) // merge_size for grid in image_grid_thw]
 
@@ -384,7 +400,7 @@ def encode_prompt(
             sampled = [sample_reference_video_frames(reference.frames) for reference in videos]
             for reference, (_, block_timestamps) in zip(videos, sampled):
                 reference.block_timestamps = block_timestamps
-            vision = components.processor.video_processor(
+            vision = processor.video_processor(
                 videos=[np.stack(frames) for frames, _ in sampled], do_sample_frames=False, return_tensors="pt"
             )
             pixel_values_videos, video_grid_thw = vision["pixel_values_videos"], vision["video_grid_thw"]
@@ -397,30 +413,34 @@ def encode_prompt(
                     )
 
         token_ids, token_tags = build_ref2va_presentation(
-            components.tokenizer, prompt, references, image_token_counts, video_block_token_counts
+            tokenizer, prompt, references, image_token_counts, video_block_token_counts
         )
         input_ids = torch.tensor([token_ids], dtype=torch.long, device=device)
         # Qwen3-VL lays its 3D rotary positions out per modality run, which it reads off the token type ids the
         # processor derives from the vision pad ids (`0` text, `1` image, `2` video).
         mm_token_type_ids = torch.tensor(
-            components.processor.create_mm_token_type_ids([token_ids]), dtype=torch.long, device=device
+            processor.create_mm_token_type_ids([token_ids]), dtype=torch.long, device=device
         )
         # `text_encoder.model` is a submodule, and a CPU-offload hook — accelerate's or the one the
         # `ComponentsManager` attaches — wraps the *top-level* module's `forward` alone, so calling the submodule
         # directly would leave the conditioner on the CPU. Fire the hook by hand instead of routing through
         # `text_encoder(...)`: MiniMax-H3 reads `hidden_states[50]` and never uses the language-model head, whose
         # vocabulary-wide projection over every token is all the top-level forward would add.
-        hook = getattr(components.text_encoder, "_hf_hook", None)
+        # TODO: firing another module's offload hook by hand is not something a block should do. It is here
+        # because MiniMax-H3 reads `hidden_states[50]` off `text_encoder.model` while the hook wraps only the
+        # top-level `forward`. Needs a real answer — an opt-in on the conditioner, or a hook that follows
+        # submodule calls.
+        hook = getattr(text_encoder, "_hf_hook", None)
         if hook is not None and hasattr(hook, "pre_forward"):
-            hook.pre_forward(components.text_encoder)
-        outputs = components.text_encoder.model(
+            hook.pre_forward(text_encoder)
+        outputs = text_encoder.model(
             input_ids=input_ids,
             attention_mask=torch.ones_like(input_ids),
             mm_token_type_ids=mm_token_type_ids,
-            pixel_values=None if pixel_values is None else pixel_values.to(device, components.text_encoder.dtype),
+            pixel_values=None if pixel_values is None else pixel_values.to(device, text_encoder.dtype),
             image_grid_thw=None if image_grid_thw is None else image_grid_thw.to(device),
             pixel_values_videos=(
-                None if pixel_values_videos is None else pixel_values_videos.to(device, components.text_encoder.dtype)
+                None if pixel_values_videos is None else pixel_values_videos.to(device, text_encoder.dtype)
             ),
             video_grid_thw=None if video_grid_thw is None else video_grid_thw.to(device),
             use_cache=False,
@@ -432,12 +452,18 @@ def encode_prompt(
     @torch.no_grad()
     def __call__(self, components: MiniMaxH3Ref2VAModularPipeline, state: PipelineState) -> PipelineState:
         block_state = self.get_block_state(state)
-        _check_prompt(block_state.prompt)
+        if not isinstance(block_state.prompt, str):
+            raise ValueError(
+                "MiniMax-H3 packs one request into one sequence, so `prompt` must be a single string, got "
+                f"{type(block_state.prompt)}."
+            )
 
         # `encode_prompt` defaults the embedding dtype to the denoiser's; a text encoder block has no denoiser of
         # its own — it is meant to run on its own — so it emits the conditioner's dtype, as every other model does.
         block_state.prompt_embeds, block_state.text_token_tags = self.encode_prompt(
-            components,
+            components.text_encoder,
+            components.tokenizer,
+            components.processor,
             block_state.prompt,
             block_state.prepared_references,
             device=components._execution_device,
@@ -524,7 +550,6 @@ def encode_references(
             video rows and the `(num_condition_audio_rows, audio_latent_channels)` audio rows, both float32 on CPU and
             both `None` when the references carry no such rows.
         """
-        device = device or components._execution_device
         latents_mean = torch.tensor(components.vae.config.latents_mean).view(1, -1, 1, 1, 1)
         latents_std = torch.tensor(components.vae.config.latents_std).view(1, -1, 1, 1, 1)
         pixel_mean = torch.tensor(MINIMAX_H3_PIXEL_MEAN, device=device).view(1, -1, 1, 1, 1)
@@ -538,7 +563,13 @@ def encode_references(
                 if reference.kind == "image":
                     pixels = torch.from_numpy(np.array(reference.image)).to(device).permute(2, 0, 1)[None, :, None]
                 else:
-                    frames = reference.frames[: trim_reference_num_frames(reference.frames.shape[0])]
+                    frames = reference.frames[
+                        : trim_reference_num_frames(
+                            reference.frames.shape[0],
+                            components.vae_frames_per_chunk,
+                            components.vae_latents_per_chunk,
+                        )
+                    ]
                     pixels = torch.from_numpy(frames.copy()).to(device).permute(3, 0, 1, 2)[None]
                 pixels = (pixels.to(torch.float32).div(255.0) - pixel_mean) / pixel_std
                 # A single frame is encoded by the (tiled) spatial encoder alone; a video goes through the temporal
diff --git a/src/diffusers/modular_pipelines/minimax_h3/modular_blocks_minimax_h3.py b/src/diffusers/modular_pipelines/minimax_h3/modular_blocks_minimax_h3.py
index 90c2c8621fec..bfe300c4f09e 100644
--- a/src/diffusers/modular_pipelines/minimax_h3/modular_blocks_minimax_h3.py
+++ b/src/diffusers/modular_pipelines/minimax_h3/modular_blocks_minimax_h3.py
@@ -23,7 +23,7 @@
     MiniMaxH3SetTimestepsStep,
 )
 from .before_encoder import MiniMaxH3Ref2VASetupStep, MiniMaxH3ResizeStep
-from .decoders import MiniMaxH3AudioDecodeStep, MiniMaxH3VideoDecodeStep
+from .decoders import MiniMaxH3AfterDenoiseStep, MiniMaxH3AudioDecodeStep, MiniMaxH3VideoDecodeStep
 from .denoise import MiniMaxH3DenoiseStep, MiniMaxH3Ref2VADenoiseStep
 from .encoders import (
     MiniMaxH3KeyframeVaeEncoderStep,
@@ -51,29 +51,33 @@ class MiniMaxH3AutoResizeStep(ConditionalPipelineBlocks):
     """
     Keyframe canvas block.
        - MiniMaxH3ResizeStep runs for the `fl2va` task, whichever of the two keyframes is given.
-       - when neither `image` nor `last_image` is provided (`t2va`), this block is skipped and the layout step falls
-         back to MiniMax-H3's own 16:9 canvas.
+       - when neither `image` nor `last_image` is provided (`t2va`), this block is skipped and the layout step falls back to MiniMax-H3's own 16:9 canvas.
 
       Components:
           image_processor (`VaeImageProcessor`)
 
       Inputs:
           image (`Image`, *optional*):
-              Keyframe the video starts from.
+              Keyframe the video starts from. It is *stretched* onto the target canvas, which by default is derived from its own
+              aspect ratio.
           last_image (`Image`, *optional*):
-              Keyframe the video ends on.
+              Keyframe the video ends on. Can be passed on its own to generate *up to* a frame. Combined with `image` it is the
+              follower of the two and is cover-cropped onto the canvas.
           height (`int`, *optional*):
               Height of the generated video in pixels, a multiple of 32.
           width (`int`, *optional*):
               Width of the generated video in pixels, a multiple of 32.
 
       Outputs:
-          height (`int`), width (`int`):
-              The resolved canvas.
+          height (`int`):
+              Resolved height of the generated video in pixels.
+          width (`int`):
+              Resolved width of the generated video in pixels.
           keyframes (`list`):
-              The keyframes put onto that canvas, in packed order.
+              The keyframes put onto the target canvas, in packed order.
           keyframe_anchors (`tuple`):
-              Which end of the video every keyframe is anchored to, in packed order.
+              Which end of the video every keyframe is anchored to, in packed order. Positional with `keyframes`, so both are
+              resolved here.
     """
 
     model_name = "minimax-h3"
@@ -108,12 +112,13 @@ class MiniMaxH3AutoKeyframeVaeEncoderStep(ConditionalPipelineBlocks):
           vae (`AutoencoderKLMiniMaxH3`)
 
       Inputs:
-          keyframes (`list`):
+          keyframes (`list`, *optional*):
               The keyframes put onto the target canvas, in packed order.
 
       Outputs:
           condition_latents (`list`):
-              The normalized video conditioning latents, one tensor per keyframe, in packed order.
+              The normalized video conditioning latents, one `(1, latent_channels, 1, latent_height, latent_width)` tensor per
+              keyframe, in packed order.
     """
 
     model_name = "minimax-h3"
@@ -142,27 +147,17 @@ class MiniMaxH3DecodeStep(SequentialPipelineBlocks):
     Decodes the denoised rows of the packed sequence into the generated video and its soundtrack.
 
       Components:
-          vae (`AutoencoderKLMiniMaxH3`) video_processor (`VideoProcessor`) audio_vae (`AutoencoderKLMiniMaxH3Audio`)
+          vae (`AutoencoderKLMiniMaxH3`)
+          video_processor (`VideoProcessor`)
+          audio_vae (`AutoencoderKLMiniMaxH3Audio`)
 
       Inputs:
           latents (`Tensor`):
-              The denoised video rows of the packed sequence, conditioning rows first.
-          num_condition_video_rows (`int`, *optional*, defaults to 0):
-              How many leading video rows are conditioning rows and are dropped here.
-          num_latent_frames (`int`):
-              Number of video latent frames.
-          latent_height (`int`):
-              Height of the video latents.
-          latent_width (`int`):
-              Width of the video latents.
+              The generated video latents.
           output_type (`str`, *optional*, defaults to pil):
-              Output format: 'pil', 'np', 'pt' or 'latent' for the raw latents.
+              Output format: 'pil', 'np' or 'pt'.
           audio_latents (`Tensor`):
-              The denoised audio rows of the packed sequence, reference rows first.
-          num_condition_audio_rows (`int`, *optional*, defaults to 0):
-              How many leading audio rows are reference rows and are dropped here.
-          num_audio_latents (`int`):
-              Number of audio latents per channel.
+              The generated audio latents, one batch item per stereo channel.
 
       Outputs:
           videos (`list`):
@@ -189,8 +184,7 @@ def outputs(self):
 # auto_docstring
 class MiniMaxH3Blocks(SequentialPipelineBlocks):
     """
-    Modular pipeline blocks for joint video + audio generation with MiniMax-H3, covering the `t2va` (text only) and
-    `fl2va` (first and/or last keyframe) tasks of the FL2VA checkpoint.
+    Modular pipeline blocks for joint video + audio generation with MiniMax-H3, covering the `t2va` (text only) and `fl2va` (first and/or last keyframe) tasks of the FL2VA checkpoint.
 
       Supported workflows:
         - `t2va`: requires `prompt`
@@ -198,45 +192,58 @@ class MiniMaxH3Blocks(SequentialPipelineBlocks):
         - `fl2va_last_frame`: requires `prompt`, `last_image`
 
       Components:
-          text_encoder (`Qwen3VLForConditionalGeneration`) tokenizer (`Qwen2Tokenizer`) processor (`Qwen3VLProcessor`)
-          vae (`AutoencoderKLMiniMaxH3`) scheduler (`MiniMaxH3Scheduler`) audio_scheduler (`MiniMaxH3Scheduler`)
-          transformer (`MiniMaxH3Transformer3DModel`) video_processor (`VideoProcessor`) audio_vae
-          (`AutoencoderKLMiniMaxH3Audio`)
+          image_processor (`VaeImageProcessor`)
+          text_encoder (`Qwen3VLForConditionalGeneration`)
+          tokenizer (`Qwen2Tokenizer`)
+          processor (`Qwen3VLProcessor`)
+          vae (`AutoencoderKLMiniMaxH3`)
+          scheduler (`MiniMaxH3Scheduler`)
+          audio_scheduler (`MiniMaxH3Scheduler`)
+          transformer (`MiniMaxH3Transformer3DModel`)
+          video_processor (`VideoProcessor`)
+          audio_vae (`AutoencoderKLMiniMaxH3Audio`)
 
       Inputs:
           image (`Image`, *optional*):
-              Keyframe the video starts from. It is *stretched* onto the target canvas, which by default is derived
-              from its own aspect ratio.
+              Keyframe the video starts from. It is *stretched* onto the target canvas, which by default is derived from its own
+              aspect ratio.
           last_image (`Image`, *optional*):
-              Keyframe the video ends on. Can be passed on its own to generate *up to* a frame. Combined with `image`
-              it is the follower of the two and is cover-cropped onto the canvas.
+              Keyframe the video ends on. Can be passed on its own to generate *up to* a frame. Combined with `image` it is the
+              follower of the two and is cover-cropped onto the canvas.
           height (`int`, *optional*):
               Height of the generated video in pixels, a multiple of 32.
           width (`int`, *optional*):
               Width of the generated video in pixels, a multiple of 32.
-          num_frames (`int`, *optional*, defaults to 124):
-              Number of frames to generate, at the fixed 24 fps. Snapped up to the next `17 * n + 5` the video VAE can
-              decode; the resulting duration must stay between 5 and 15 seconds.
           prompt (`str`):
               The prompt to guide generation, a single string.
+          keyframes (`list`, *optional*):
+              The keyframes put onto the target canvas, in packed order (empty or None for `t2va`).
+          num_frames (`int`, *optional*, defaults to 124):
+              Number of frames to generate, at the fixed 24 fps. Snapped up to the next `17 * n + 5` the video VAE can decode;
+              the resulting duration must stay between 5 and 15 seconds.
+          keyframe_anchors (`tuple`, *optional*, defaults to ()):
+              Which end of the video every keyframe is anchored to, in packed order.
           generator (`Generator`, *optional*):
-              The generator of the request. The conditioning noise is drawn from it before the target noise of the
-              prepare-latents step.
+              The generator of the request. The video noise is drawn from it first, then the audio noise.
           latents (`Tensor`, *optional*):
-              Pre-generated video noise of shape `(1, 24, num_latent_frames, latent_height, latent_width)`, used
-              instead of the draw.
+              Pre-generated video noise of shape `(1, 24, num_latent_frames, latent_height, latent_width)`, used instead of the
+              draw.
           audio_latents (`Tensor`, *optional*):
               Pre-generated audio noise of shape `(2, 32, num_audio_latents)`.
-          condition_latents (`Tensor`, *optional*):
-              The video conditioning rows to prepend, or None for a request that has none.
+          condition_latents (`list`, *optional*):
+              The encoded video conditioning latents, one `(1, latent_channels, num_latent_frames, latent_height, latent_width)`
+              tensor per condition in packed order, or None for a request that has none. Noised and packed here.
           audio_condition_latents (`Tensor`, *optional*):
               The audio conditioning rows to prepend, or None for a request that has none.
           num_inference_steps (`int`):
               The number of denoising steps.
+          **denoiser_input_fields (`None`, *optional*):
+              The structural description of the packed sequence the transformer reads by name: `token_tags`, `position_ids` and
+              the three row-index tensors.
           attention_kwargs (`dict`, *optional*):
               Additional kwargs for attention processors.
           output_type (`str`, *optional*, defaults to pil):
-              Output format: 'pil', 'np', 'pt' or 'latent' for the raw latents.
+              Output format: 'pil', 'np' or 'pt'.
 
       Outputs:
           videos (`list`):
@@ -256,6 +263,7 @@ class MiniMaxH3Blocks(SequentialPipelineBlocks):
         MiniMaxH3PrepareLatentsStep,
         MiniMaxH3SetTimestepsStep,
         MiniMaxH3DenoiseStep,
+        MiniMaxH3AfterDenoiseStep,
         MiniMaxH3DecodeStep,
     ]
     block_names = [
@@ -266,6 +274,7 @@ class MiniMaxH3Blocks(SequentialPipelineBlocks):
         "prepare_latents",
         "set_timesteps",
         "denoise",
+        "after_denoise",
         "decode",
     ]
     # One repository holds both checkpoint partitions, so the two blocksets are two workflows over one shared
@@ -293,51 +302,56 @@ def outputs(self):
 # auto_docstring
 class MiniMaxH3Ref2VABlocks(SequentialPipelineBlocks):
     """
-    Modular pipeline blocks for joint video + audio generation from an ordered list of image, video and audio
-    references with MiniMax-H3, the `ref2va` task of the Ref2VA checkpoint.
+    Modular pipeline blocks for joint video + audio generation from an ordered list of image, video and audio references with MiniMax-H3, the `ref2va` task of the Ref2VA checkpoint.
 
       Supported workflows:
         - `ref2va`: requires `prompt`, `references`
 
       Components:
-          text_encoder (`Qwen3VLForConditionalGeneration`) tokenizer (`Qwen2Tokenizer`) processor (`Qwen3VLProcessor`)
-          vae (`AutoencoderKLMiniMaxH3`) audio_vae (`AutoencoderKLMiniMaxH3Audio`) scheduler (`MiniMaxH3Scheduler`)
-          audio_scheduler (`MiniMaxH3Scheduler`) transformer_ref (`MiniMaxH3Transformer3DModel`) video_processor
-          (`VideoProcessor`)
+          text_encoder (`Qwen3VLForConditionalGeneration`)
+          tokenizer (`Qwen2Tokenizer`)
+          processor (`Qwen3VLProcessor`)
+          vae (`AutoencoderKLMiniMaxH3`)
+          audio_vae (`AutoencoderKLMiniMaxH3Audio`)
+          scheduler (`MiniMaxH3Scheduler`)
+          audio_scheduler (`MiniMaxH3Scheduler`)
+          transformer_ref (`MiniMaxH3Transformer3DModel`)
+          video_processor (`VideoProcessor`)
 
       Inputs:
           references (`list`):
-              The references to condition on, **in the order the model should read them**: the order labels them in the
-              prompt presentation and lays them out on the shared rotary clock, so a different order is a different
-              request. Every [`MiniMaxH3Reference`] carries exactly one medium, a path or in-memory media — `image` (at
-              most 9), `video` at its own `fps` (at most 3, whose `audio` soundtrack is conditioned on as well), or
-              `audio` at its own `sample_rate` (at most 3) — for at most 12 references in total, and audio references
-              cannot be the only ones. A path is decoded when the reference is built, so these blocks only ever see
-              pixels and samples.
+              The references to condition on, **in the order the model should read them**: the order labels them in the prompt
+              presentation and lays them out on the shared rotary clock, so a different order is a different request. Every
+              [`MiniMaxH3Reference`] carries exactly one medium, a path or in-memory media — `image` (at most 9), `video` at its
+              own `fps` (at most 3, whose `audio` soundtrack is conditioned on as well), or `audio` at its own `sample_rate` (at
+              most 3) — for at most 12 references in total, and audio references cannot be the only ones. A path is decoded when
+              the reference is built, so these blocks only ever see pixels and samples.
           height (`int`, *optional*):
               Height of the generated video in pixels, a multiple of 32.
           width (`int`, *optional*):
               Width of the generated video in pixels, a multiple of 32.
           num_frames (`int`, *optional*):
-              Number of frames to generate, at the fixed 24 fps. Snapped up to the next `17 * n + 5` the video VAE can
-              decode. May be left out, but only when exactly one reference carries audio, in which case the duration is
-              that soundtrack's.
+              Number of frames to generate, at the fixed 24 fps. Snapped up to the next `17 * n + 5` the video VAE can decode.
+              May be left out, but only when exactly one reference carries audio, in which case the duration is that
+              soundtrack's.
           prompt (`str`):
               The prompt to guide generation, a single string.
           generator (`Generator`, *optional*):
-              The generator of the request. The conditioning noise is drawn from it before the target noise of the
-              prepare-latents step.
+              The generator of the request. The video noise is drawn from it first, then the audio noise.
           latents (`Tensor`, *optional*):
-              Pre-generated video noise of shape `(1, 24, num_latent_frames, latent_height, latent_width)`, used
-              instead of the draw.
+              Pre-generated video noise of shape `(1, 24, num_latent_frames, latent_height, latent_width)`, used instead of the
+              draw.
           audio_latents (`Tensor`, *optional*):
               Pre-generated audio noise of shape `(2, 32, num_audio_latents)`.
           num_inference_steps (`int`):
               The number of denoising steps.
+          **denoiser_input_fields (`None`, *optional*):
+              The structural description of the packed sequence the transformer reads by name: `token_tags`, `position_ids` and
+              the three row-index tensors.
           attention_kwargs (`dict`, *optional*):
               Additional kwargs for attention processors.
           output_type (`str`, *optional*, defaults to pil):
-              Output format: 'pil', 'np', 'pt' or 'latent' for the raw latents.
+              Output format: 'pil', 'np' or 'pt'.
 
       Outputs:
           videos (`list`):
@@ -359,6 +373,7 @@ class MiniMaxH3Ref2VABlocks(SequentialPipelineBlocks):
         MiniMaxH3PrepareLatentsStep,
         MiniMaxH3SetTimestepsStep,
         MiniMaxH3Ref2VADenoiseStep,
+        MiniMaxH3AfterDenoiseStep,
         MiniMaxH3DecodeStep,
     ]
     block_names = [
@@ -369,6 +384,7 @@ class MiniMaxH3Ref2VABlocks(SequentialPipelineBlocks):
         "prepare_latents",
         "set_timesteps",
         "denoise",
+        "after_denoise",
         "decode",
     ]
     # The `ref2va` task name, i.e. the value a `workflow=` argument to `ModularPipeline.from_pretrained` would take
diff --git a/src/diffusers/modular_pipelines/minimax_h3/modular_pipeline.py b/src/diffusers/modular_pipelines/minimax_h3/modular_pipeline.py
index 97ab2314beaa..125b002d1305 100644
--- a/src/diffusers/modular_pipelines/minimax_h3/modular_pipeline.py
+++ b/src/diffusers/modular_pipelines/minimax_h3/modular_pipeline.py
@@ -62,6 +62,18 @@ def vae_latent_channels(self):
             return self.vae.config.latent_channels
         return 24
 
+    @property
+    def vae_frames_per_chunk(self):
+        if getattr(self, "vae", None) is not None:
+            return self.vae.config.clip_length
+        return 17
+
+    @property
+    def vae_latents_per_chunk(self):
+        if getattr(self, "vae", None) is not None:
+            return self.vae.tokens_chunk_size
+        return 5
+
     @property
     def audio_sampling_rate(self):
         if getattr(self, "audio_vae", None) is not None:
diff --git a/src/diffusers/modular_pipelines/minimax_h3/packing.py b/src/diffusers/modular_pipelines/minimax_h3/packing.py
index 94e14226c778..a76badbc9960 100644
--- a/src/diffusers/modular_pipelines/minimax_h3/packing.py
+++ b/src/diffusers/modular_pipelines/minimax_h3/packing.py
@@ -36,8 +36,6 @@
 backends available.
 """
 
-from dataclasses import dataclass
-
 import numpy as np
 import torch
 
@@ -58,11 +56,6 @@
 MINIMAX_H3_MIN_DURATION = 5.0
 MINIMAX_H3_MAX_DURATION = 15.0
 
-# The video VAE encodes 17 pixel frames per chunk and drops the 3 trailing latent frames of every chunk, so
-# `17 * n + 5` pixel frames map to `5 * n + 2` latent frames.
-MINIMAX_H3_FRAMES_PER_CHUNK = 17
-MINIMAX_H3_LATENTS_PER_CHUNK = 5
-
 # The pixel convention of the video VAE: ImageNet-normalized RGB over a `[0, 1]` base range.
 MINIMAX_H3_PIXEL_MEAN = (0.485, 0.456, 0.406)
 MINIMAX_H3_PIXEL_STD = (0.229, 0.224, 0.225)
@@ -91,40 +84,6 @@
 _ROPE_SPATIAL_SCALE = 32
 
 
-@dataclass
-class MiniMaxH3PackedSequence:
-    r"""
-    The structural description of one packed MiniMax-H3 sequence.
-
-    Attributes:
-        sequence_length (`int`):
-            Total number of rows, `L + C + A + V`.
-        position_ids (`torch.Tensor` of shape `(sequence_length, 3)`, float64):
-            The `(t, h, w)` rotary coordinate of every row.
-        token_tags (`torch.Tensor` of shape `(sequence_length,)`):
-            The modality tag of every row.
-        video_indices (`torch.Tensor`):
-            Sequence positions of the video rows: the keyframe conditioning rows first, then the target rows.
-        audio_indices (`torch.Tensor`):
-            Sequence positions of the audio rows: reference rows first (`ref2va` only), then the target rows.
-        text_indices (`torch.Tensor`):
-            Sequence positions of the text rows.
-        num_condition_video_rows (`int`):
-            How many leading entries of `video_indices` are conditioning rows rather than generated rows.
-        num_condition_audio_rows (`int`):
-            How many leading entries of `audio_indices` are reference rows rather than generated rows.
-    """
-
-    sequence_length: int
-    position_ids: torch.Tensor
-    token_tags: torch.Tensor
-    video_indices: torch.Tensor
-    audio_indices: torch.Tensor
-    text_indices: torch.Tensor
-    num_condition_video_rows: int
-    num_condition_audio_rows: int
-
-
 def resolve_canvas_size(aspect_width: float, aspect_height: float) -> tuple[int, int]:
     r"""
     Resolve a display aspect ratio into a MiniMax-H3 canvas.
@@ -163,24 +122,26 @@ def resolve_canvas_size(aspect_width: float, aspect_height: float) -> tuple[int,
     return max(multiple, round(height / multiple) * multiple), max(multiple, round(width / multiple) * multiple)
 
 
-def align_num_frames(num_frames: int) -> int:
+def align_num_frames(num_frames: int, frames_per_chunk: int, latents_per_chunk: int) -> int:
     r"""
-    Snap a frame count up to the next `17 * n + 5` the video VAE can encode.
+    Snap a frame count up to the next `frames_per_chunk * n + latents_per_chunk` the video VAE can encode.
 
     Args:
         num_frames (`int`): The requested number of frames.
+        frames_per_chunk (`int`): Pixel frames the video VAE encodes per chunk, its `clip_length`.
+        latents_per_chunk (`int`): Latent frames a chunk keeps, the VAE's `tokens_chunk_size`.
 
     Returns:
         `int`: The aligned number of frames.
     """
     if num_frames < 1:
         raise ValueError(f"`num_frames` must be positive, got {num_frames}.")
-    while num_frames % MINIMAX_H3_FRAMES_PER_CHUNK != MINIMAX_H3_LATENTS_PER_CHUNK:
+    while num_frames % frames_per_chunk != latents_per_chunk:
         num_frames += 1
     return num_frames
 
 
-def video_latent_num_frames(num_frames: int) -> int:
+def video_latent_num_frames(num_frames: int, frames_per_chunk: int, latents_per_chunk: int) -> int:
     r"""
     The number of latent frames the video VAE produces for a `17 * n + 5` frame count.
 
@@ -190,11 +151,11 @@ def video_latent_num_frames(num_frames: int) -> int:
     Returns:
         `int`: The number of latent frames, `5 * n + 2`.
     """
-    if num_frames % MINIMAX_H3_FRAMES_PER_CHUNK != MINIMAX_H3_LATENTS_PER_CHUNK:
-        raise ValueError(f"`num_frames` must be of the form 17 * n + 5, got {num_frames}.")
-    return (
-        num_frames - MINIMAX_H3_LATENTS_PER_CHUNK
-    ) // MINIMAX_H3_FRAMES_PER_CHUNK * MINIMAX_H3_LATENTS_PER_CHUNK + 2
+    if num_frames % frames_per_chunk != latents_per_chunk:
+        raise ValueError(
+            f"`num_frames` must be of the form {frames_per_chunk} * n + {latents_per_chunk}, got {num_frames}."
+        )
+    return (num_frames - latents_per_chunk) // frames_per_chunk * latents_per_chunk + 2
 
 
 def audio_latent_num_frames(num_frames: int) -> int:
@@ -242,59 +203,6 @@ def patchify_video_latents(latents: torch.Tensor, patch_size: tuple[int, int, in
     return latents.reshape(-1, channels * patch_t * patch_h * patch_w).contiguous()
 
 
-def unpatchify_video_tokens(
-    rows: torch.Tensor,
-    num_latent_frames: int,
-    latent_height: int,
-    latent_width: int,
-    channels: int,
-    patch_size: tuple[int, int, int],
-) -> torch.Tensor:
-    r"""
-    Unpack transformer rows back into video latents. The inverse of [`patchify_video_latents`].
-
-    Args:
-        rows (`torch.Tensor` of shape `(num_patches, channels * prod(patch_size))`): The packed rows.
-        num_latent_frames (`int`): Number of latent frames.
-        latent_height (`int`): Latent height.
-        latent_width (`int`): Latent width.
-        channels (`int`): Number of latent channels.
-        patch_size (`tuple[int, int, int]`): The `(t, h, w)` patch.
-
-    Returns:
-        `torch.Tensor` of shape `(batch_size, channels, num_latent_frames, latent_height, latent_width)`.
-    """
-    patch_t, patch_h, patch_w = patch_size
-    rows = rows.reshape(
-        -1,
-        num_latent_frames // patch_t,
-        latent_height // patch_h,
-        latent_width // patch_w,
-        channels,
-        patch_t,
-        patch_h,
-        patch_w,
-    )
-    rows = rows.permute(0, 4, 1, 5, 2, 6, 3, 7)
-    return rows.reshape(-1, channels, num_latent_frames, latent_height, latent_width).contiguous()
-
-
-def unpack_audio_tokens(rows: torch.Tensor, num_audio_latents: int) -> torch.Tensor:
-    r"""
-    Unpack the channel-major audio rows into audio VAE latents.
-
-    Args:
-        rows (`torch.Tensor` of shape `(num_audio_latents * 2, latent_channels)`): The packed audio rows.
-        num_audio_latents (`int`): Number of audio latents per channel.
-
-    Returns:
-        `torch.Tensor` of shape `(2, latent_channels, num_audio_latents)`: One batch item per stereo channel, which
-        is what the mono audio VAE consumes.
-    """
-    rows = rows.reshape(MINIMAX_H3_AUDIO_CHANNELS, num_audio_latents, rows.shape[-1])
-    return rows.permute(0, 2, 1).contiguous()
-
-
 def _spatial_position_grid(dim: int, patch: int, sqrt_area: float) -> torch.Tensor:
     r"""
     One aspect-normalized spatial rotary axis: `dim // patch` coordinates centred on the unit interval, scaled up by
@@ -341,7 +249,7 @@ def build_packed_sequence(
     num_audio_latents: int,
     patch_size: tuple[int, int, int],
     keyframe_anchors: tuple[str, ...] = (),
-) -> MiniMaxH3PackedSequence:
+) -> tuple[torch.Tensor, torch.Tensor, torch.Tensor, torch.Tensor, torch.Tensor, int, int]:
     r"""
     Build the `[text | keyframe conditions | target audio | target video]` layout used by the `t2va` and `fl2va`
     tasks.
@@ -360,7 +268,8 @@ def build_packed_sequence(
             latent frame, `"last"` at the last one.
 
     Returns:
-        [`MiniMaxH3PackedSequence`]
+        `tuple`: `position_ids`, `token_tags`, `video_indices`, `audio_indices`, `text_indices`, and the number of
+        leading video and audio rows that are conditioning rather than generated.
     """
     _, patch_h, patch_w = patch_size
     rows_per_frame = (latent_height // patch_h) * (latent_width // patch_w)
@@ -421,20 +330,15 @@ def build_packed_sequence(
     token_tags[audio_indices] = MINIMAX_H3_AUDIO_TAG
     token_tags[video_indices] = MINIMAX_H3_VIDEO_TAG
 
-    return MiniMaxH3PackedSequence(
-        sequence_length=sequence_length,
-        position_ids=position_ids,
-        token_tags=token_tags,
-        video_indices=video_indices,
-        audio_indices=audio_indices,
-        text_indices=text_indices,
-        num_condition_video_rows=num_condition_rows,
-        num_condition_audio_rows=0,
-    )
+    return position_ids, token_tags, video_indices, audio_indices, text_indices, num_condition_rows, 0
 
 
 def build_row_timesteps(
-    layout: MiniMaxH3PackedSequence,
+    video_indices: torch.Tensor,
+    audio_indices: torch.Tensor,
+    num_condition_video_rows: int,
+    num_condition_audio_rows: int,
+    num_text_tokens: int,
     video_timestep: float,
     audio_timestep: float,
     condition_video_timestep: float,
@@ -449,7 +353,11 @@ def build_row_timesteps(
     output head and inherit the video timestep.
 
     Args:
-        layout ([`MiniMaxH3PackedSequence`]): The packed layout.
+        video_indices (`torch.Tensor`): Sequence positions of the video rows, conditioning rows first.
+        audio_indices (`torch.Tensor`): Sequence positions of the audio rows, reference rows first.
+        num_condition_video_rows (`int`): How many leading video rows are conditioning rows.
+        num_condition_audio_rows (`int`): How many leading audio rows are reference rows.
+        num_text_tokens (`int`): Number of text rows, which never reach an output head.
         video_timestep (`float`): Timestep of the generated video rows.
         audio_timestep (`float`): Timestep of the generated audio rows.
         condition_video_timestep (`float`): Timestep of the video conditioning rows.
@@ -458,8 +366,9 @@ def build_row_timesteps(
     Returns:
         `tuple[torch.Tensor, torch.Tensor]`: the distinct timesteps, sorted, and the index of every row into them.
     """
-    row_timesteps = torch.full((layout.sequence_length,), video_timestep, dtype=torch.float32)
-    row_timesteps[layout.video_indices[: layout.num_condition_video_rows]] = condition_video_timestep
-    row_timesteps[layout.audio_indices[layout.num_condition_audio_rows :]] = audio_timestep
-    row_timesteps[layout.audio_indices[: layout.num_condition_audio_rows]] = condition_audio_timestep
+    sequence_length = int(video_indices.numel() + audio_indices.numel() + num_text_tokens)
+    row_timesteps = torch.full((sequence_length,), video_timestep, dtype=torch.float32)
+    row_timesteps[video_indices[:num_condition_video_rows]] = condition_video_timestep
+    row_timesteps[audio_indices[num_condition_audio_rows:]] = audio_timestep
+    row_timesteps[audio_indices[:num_condition_audio_rows]] = condition_audio_timestep
     return torch.unique(row_timesteps, sorted=True, return_inverse=True)
diff --git a/src/diffusers/modular_pipelines/minimax_h3/packing_ref2va.py b/src/diffusers/modular_pipelines/minimax_h3/packing_ref2va.py
index 3518c9558a0c..f68fd0217028 100644
--- a/src/diffusers/modular_pipelines/minimax_h3/packing_ref2va.py
+++ b/src/diffusers/modular_pipelines/minimax_h3/packing_ref2va.py
@@ -59,11 +59,8 @@
     MINIMAX_H3_AUDIO_TAG,
     MINIMAX_H3_CANVAS_MULTIPLE,
     MINIMAX_H3_FPS,
-    MINIMAX_H3_FRAMES_PER_CHUNK,
-    MINIMAX_H3_LATENTS_PER_CHUNK,
     MINIMAX_H3_TEXT_TAG,
     MINIMAX_H3_VIDEO_TAG,
-    MiniMaxH3PackedSequence,
     _spatial_position_grid,
     _temporal_position_grid,
     resolve_canvas_size,
@@ -440,7 +437,7 @@ def build_ref2va_packed_sequence(
     latent_width: int,
     num_audio_latents: int,
     patch_size: tuple[int, int, int],
-) -> MiniMaxH3PackedSequence:
+) -> tuple[torch.Tensor, torch.Tensor, torch.Tensor, torch.Tensor, torch.Tensor, int, int]:
     r"""
     Build the `[text | reference blocks | target audio | target video]` layout of the `ref2va` task.
 
@@ -457,7 +454,8 @@ def build_ref2va_packed_sequence(
         patch_size (`tuple[int, int, int]`): The transformer's `(t, h, w)` patch.
 
     Returns:
-        [`MiniMaxH3PackedSequence`]
+        `tuple`: `position_ids`, `token_tags`, `video_indices`, `audio_indices`, `text_indices`, and the number of
+        leading video and audio rows that are references rather than generated.
     """
     _, patch_h, patch_w = patch_size
     num_text_tokens = text_token_tags.shape[0]
@@ -539,15 +537,14 @@ def build_ref2va_packed_sequence(
     token_tags[audio_indices] = MINIMAX_H3_AUDIO_TAG
     token_tags[video_indices] = MINIMAX_H3_VIDEO_TAG
 
-    return MiniMaxH3PackedSequence(
-        sequence_length=sequence_length,
-        position_ids=position_ids,
-        token_tags=token_tags,
-        video_indices=video_indices,
-        audio_indices=audio_indices,
-        text_indices=text_indices,
-        num_condition_video_rows=num_reference_video_rows,
-        num_condition_audio_rows=num_reference_audio_rows,
+    return (
+        position_ids,
+        token_tags,
+        video_indices,
+        audio_indices,
+        text_indices,
+        num_reference_video_rows,
+        num_reference_audio_rows,
     )
 
 
@@ -819,7 +816,7 @@ def emit(segment: tuple[list[int], list[int]]) -> None:
     return token_ids, token_tags
 
 
-def trim_reference_num_frames(num_frames: int) -> int:
+def trim_reference_num_frames(num_frames: int, frames_per_chunk: int, latents_per_chunk: int) -> int:
     r"""
     Snap a reference video's frame count *down* to a `17 * n + 5` the video VAE encodes without padding.
 
@@ -834,8 +831,4 @@ def trim_reference_num_frames(num_frames: int) -> int:
     """
     if num_frames < 1:
         raise ValueError(f"A reference video must have at least one frame, got {num_frames}.")
-    return (
-        max(1, (num_frames - MINIMAX_H3_LATENTS_PER_CHUNK) // MINIMAX_H3_FRAMES_PER_CHUNK)
-        * MINIMAX_H3_FRAMES_PER_CHUNK
-        + MINIMAX_H3_LATENTS_PER_CHUNK
-    )
+    return max(1, (num_frames - latents_per_chunk) // frames_per_chunk) * frames_per_chunk + latents_per_chunk

From 5e846542656a47ffc0d9c01967d9a73bb59df8d6 Mon Sep 17 00:00:00 2001
From: yiyixuxu <yixu310@gmail.com>
Date: Mon, 3 Aug 2026 16:32:15 +0000
Subject: [PATCH 07/16] Give each MiniMax-H3 reference its own type
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

`MiniMaxH3Reference` was one dataclass standing in for three unrelated shapes,
with a `__post_init__` policing which of its five fields may co-occur and four
path-decoding branches inside the constructor. It splits into
`MiniMaxH3ImageReference`, `MiniMaxH3VideoReference` (frames, fps, and the
video's own soundtrack) and `MiniMaxH3AudioReference` under an empty base, so
the types say what the check used to. Opening media files moves out of the
dataclass entirely — the blocks' own contract says they never open files — into
an opt-in `MiniMaxH3Ref2VALoadReferencesStep` plus exported
`decode_reference_video` / `decode_reference_audio` helpers, so a path becomes
a request in exactly one place.

The module constants stop leaking into the blocks. Everything read by more than
one block — fps, the duration bounds, the canvas multiple, the text-encoder
layer, the pixel stats, the encode seed, the modality tags — becomes a property
on the pipeline, read as `components.fps` the way the blocks already read
`components.patch_size`; `canvas_multiple` genuinely derives, as the VAE's
spatial compression times the patch width. The per-modality reference limits
are read by the setup step alone and become its `__init__` config.

`MiniMaxH3PreparedReference` is deleted. The reference encoder used to write
latent geometry into objects it declared as an input, and the layout step read
it back — an undeclared boundary, and a hand-assembled chain that skipped the
encoder built a packed sequence with zero reference rows and no error. The
layout now reads geometry off the shapes of the `condition_latents` it already
receives, and `audio_condition_latents` becomes a list so the per-reference
counts survive. The setup step emits normalized media as the same public
reference types, the `image` -> `keyframes` pattern the resize step already
uses for the prepared/raw boundary.

The generated frames and audio are bit-exact on the documented cases: the
reference split swept alone; the constants move is verified property-by-
property against the values it replaced, with the layout builder byte-identical
old-vs-new on synthetic layouts, and the combined tree swept after the
follow-up commit.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 .../modular_pipelines/minimax_h3/__init__.py  |  24 +-
 .../minimax_h3/before_denoise.py              |  68 +--
 .../minimax_h3/before_encoder.py              | 186 +++++---
 .../modular_pipelines/minimax_h3/decoders.py  |   7 +-
 .../modular_pipelines/minimax_h3/encoders.py  | 134 +++---
 .../minimax_h3/modular_pipeline.py            |  82 ++++
 .../modular_pipelines/minimax_h3/packing.py   |  29 +-
 .../minimax_h3/packing_ref2va.py              | 439 ++++++------------
 .../minimax_h3/reference_loading.py           | 272 +++++++++++
 .../test_modular_pipeline_minimax_h3.py       | 266 +++++++----
 10 files changed, 933 insertions(+), 574 deletions(-)
 create mode 100644 src/diffusers/modular_pipelines/minimax_h3/reference_loading.py

diff --git a/src/diffusers/modular_pipelines/minimax_h3/__init__.py b/src/diffusers/modular_pipelines/minimax_h3/__init__.py
index 6f492f17eff1..eac92574b60c 100644
--- a/src/diffusers/modular_pipelines/minimax_h3/__init__.py
+++ b/src/diffusers/modular_pipelines/minimax_h3/__init__.py
@@ -23,7 +23,17 @@
 else:
     _import_structure["modular_blocks_minimax_h3"] = ["MiniMaxH3Blocks", "MiniMaxH3Ref2VABlocks"]
     _import_structure["modular_pipeline"] = ["MiniMaxH3ModularPipeline", "MiniMaxH3Ref2VAModularPipeline"]
-    _import_structure["packing_ref2va"] = ["MiniMaxH3Reference"]
+    _import_structure["packing_ref2va"] = [
+        "MiniMaxH3AudioReference",
+        "MiniMaxH3ImageReference",
+        "MiniMaxH3Reference",
+        "MiniMaxH3VideoReference",
+    ]
+    _import_structure["reference_loading"] = [
+        "MiniMaxH3Ref2VALoadReferencesStep",
+        "decode_reference_audio",
+        "decode_reference_video",
+    ]
 
 if TYPE_CHECKING or DIFFUSERS_SLOW_IMPORT:
     try:
@@ -34,7 +44,17 @@
     else:
         from .modular_blocks_minimax_h3 import MiniMaxH3Blocks, MiniMaxH3Ref2VABlocks
         from .modular_pipeline import MiniMaxH3ModularPipeline, MiniMaxH3Ref2VAModularPipeline
-        from .packing_ref2va import MiniMaxH3Reference
+        from .packing_ref2va import (
+            MiniMaxH3AudioReference,
+            MiniMaxH3ImageReference,
+            MiniMaxH3Reference,
+            MiniMaxH3VideoReference,
+        )
+        from .reference_loading import (
+            MiniMaxH3Ref2VALoadReferencesStep,
+            decode_reference_audio,
+            decode_reference_video,
+        )
 else:
     import sys
 
diff --git a/src/diffusers/modular_pipelines/minimax_h3/before_denoise.py b/src/diffusers/modular_pipelines/minimax_h3/before_denoise.py
index cecb04598e37..95bd786cca97 100644
--- a/src/diffusers/modular_pipelines/minimax_h3/before_denoise.py
+++ b/src/diffusers/modular_pipelines/minimax_h3/before_denoise.py
@@ -21,12 +21,6 @@
 from ..modular_pipeline_utils import ComponentSpec, InputParam, OutputParam
 from .modular_pipeline import MiniMaxH3ModularPipeline, MiniMaxH3Ref2VAModularPipeline
 from .packing import (
-    MINIMAX_H3_AUDIO_CHANNELS,
-    MINIMAX_H3_CANVAS_MULTIPLE,
-    MINIMAX_H3_FPS,
-    MINIMAX_H3_KEYFRAME_NOISE_AUG,
-    MINIMAX_H3_MAX_DURATION,
-    MINIMAX_H3_MIN_DURATION,
     align_num_frames,
     audio_latent_num_frames,
     build_packed_sequence,
@@ -35,7 +29,7 @@
     resolve_canvas_size,
     video_latent_num_frames,
 )
-from .packing_ref2va import MiniMaxH3PreparedReference, build_ref2va_packed_sequence
+from .packing_ref2va import MiniMaxH3Reference, build_ref2va_packed_sequence
 
 
 logger = logging.get_logger(__name__)  # pylint: disable=invalid-name
@@ -143,10 +137,10 @@ def __call__(self, components: MiniMaxH3ModularPipeline, state: PipelineState) -
 
         # Without a keyframe to take the aspect ratio from, MiniMax-H3 generates on its own 16:9 canvas.
         if block_state.height is None:
-            block_state.height, block_state.width = resolve_canvas_size(16, 9)
-        if block_state.height % MINIMAX_H3_CANVAS_MULTIPLE or block_state.width % MINIMAX_H3_CANVAS_MULTIPLE:
+            block_state.height, block_state.width = resolve_canvas_size(16, 9, components.canvas_multiple)
+        if block_state.height % components.canvas_multiple or block_state.width % components.canvas_multiple:
             raise ValueError(
-                f"`height` and `width` must be multiples of {MINIMAX_H3_CANVAS_MULTIPLE}, got "
+                f"`height` and `width` must be multiples of {components.canvas_multiple}, got "
                 f"{block_state.height}x{block_state.width}."
             )
 
@@ -161,13 +155,13 @@ def __call__(self, components: MiniMaxH3ModularPipeline, state: PipelineState) -
             block_state.num_frames = aligned_num_frames
         # The duration the request generates is the one of the *aligned* frame count, so that is what the ceiling has
         # to hold for: 346 frames would otherwise pass the check and then be rounded up to 362, i.e. 15.083 seconds.
-        duration = block_state.num_frames / MINIMAX_H3_FPS
-        if not MINIMAX_H3_MIN_DURATION <= duration <= MINIMAX_H3_MAX_DURATION:
+        duration = block_state.num_frames / components.fps
+        if not components.min_duration <= duration <= components.max_duration:
             raise ValueError(
-                f"MiniMax-H3 generates between {MINIMAX_H3_MIN_DURATION} and {MINIMAX_H3_MAX_DURATION} seconds at "
-                f"{MINIMAX_H3_FPS} fps, so `num_frames`, rounded up to the next `17 * n + 5` the video VAE can "
-                f"encode, must be between {int(MINIMAX_H3_MIN_DURATION * MINIMAX_H3_FPS)} and "
-                f"{int(MINIMAX_H3_MAX_DURATION * MINIMAX_H3_FPS)}, got {block_state.num_frames}."
+                f"MiniMax-H3 generates between {components.min_duration} and {components.max_duration} seconds "
+                f"at {components.fps} fps, so `num_frames`, rounded up to the next `17 * n + 5` the video VAE "
+                f"can encode, must be between {int(components.min_duration * components.fps)} and "
+                f"{int(components.max_duration * components.fps)}, got {block_state.num_frames}."
             )
 
         ratio = components.vae_spatial_compression_ratio
@@ -227,9 +221,24 @@ def inputs(self) -> list[InputParam]:
             ),
             InputParam(
                 name="prepared_references",
-                type_hint=list[MiniMaxH3PreparedReference],
+                type_hint=list[MiniMaxH3Reference],
                 required=True,
-                description="The prepared references, in packed order, with their latent geometry filled in.",
+                description="The references normalized by the setup step, in packed order.",
+            ),
+            InputParam(
+                name="condition_latents",
+                type_hint=list[torch.Tensor],
+                required=True,
+                description=(
+                    "The encoded video conditioning latents, one per image and video reference in packed order. "
+                    "Their shape is where every reference block's geometry comes from."
+                ),
+            ),
+            InputParam(
+                name="audio_condition_latents",
+                type_hint=list[torch.Tensor],
+                required=True,
+                description="The encoded audio conditioning rows, one per audio-bearing reference in packed order.",
             ),
             InputParam.template("height", required=True, description="Height of the generated video in pixels."),
             InputParam.template("width", required=True, description="Width of the generated video in pixels."),
@@ -321,6 +330,8 @@ def __call__(self, components: MiniMaxH3Ref2VAModularPipeline, state: PipelineSt
         ) = build_ref2va_packed_sequence(
             block_state.text_token_tags,
             block_state.prepared_references,
+            block_state.condition_latents,
+            block_state.audio_condition_latents,
             block_state.num_latent_frames,
             block_state.latent_height,
             block_state.latent_width,
@@ -402,8 +413,11 @@ def inputs(self) -> list[InputParam]:
             ),
             InputParam(
                 name="audio_condition_latents",
-                type_hint=torch.Tensor,
-                description="The audio conditioning rows to prepend, or None for a request that has none.",
+                type_hint=list[torch.Tensor],
+                description=(
+                    "The audio conditioning rows to prepend, one tensor per audio-bearing reference in packed "
+                    "order. Empty for a request that has none, which is every `t2va` and `fl2va` one."
+                ),
             ),
         ]
 
@@ -433,7 +447,7 @@ def __call__(self, components: MiniMaxH3ModularPipeline, state: PipelineState) -
         # noise directly in row layout. Passing `latents` or `audio_latents` skips its draw and shifts the ones after
         # it.
         condition_rows = None
-        if block_state.condition_latents is not None:
+        if block_state.condition_latents:
             # One draw per condition, in packed order. Each is packed on its own because `ref2va` references are
             # encoded at their own resolutions, so their latents do not share a shape.
             packed = []
@@ -443,7 +457,7 @@ def __call__(self, components: MiniMaxH3ModularPipeline, state: PipelineState) -
                 )
                 # The anchors are not fully clean: the released model noises them to `t = 0.999` and holds them there
                 # for every step. Mixing before the patchify is the same arithmetic, since patchify only permutes.
-                noised = components.scheduler.scale_noise(condition.to(device), MINIMAX_H3_KEYFRAME_NOISE_AUG, noise)
+                noised = components.scheduler.scale_noise(condition.to(device), components.keyframe_noise_aug, noise)
                 packed.append(patchify_video_latents(noised, patch_size))
             condition_rows = torch.cat(packed)
             # In a hand-assembled chain the canvas reaching the layout is user input, so it can disagree with the
@@ -474,7 +488,7 @@ def __call__(self, components: MiniMaxH3ModularPipeline, state: PipelineState) -
 
         if block_state.audio_latents is None:
             audio_rows = randn_tensor(
-                (block_state.num_audio_latents * MINIMAX_H3_AUDIO_CHANNELS, components.audio_latent_channels),
+                (block_state.num_audio_latents * components.audio_channels, components.audio_latent_channels),
                 generator=block_state.generator,
                 device=device,
                 dtype=torch.float32,
@@ -488,8 +502,10 @@ def __call__(self, components: MiniMaxH3ModularPipeline, state: PipelineState) -
 
         if condition_rows is not None:
             video_rows = torch.cat([condition_rows, video_rows])
-        if block_state.audio_condition_latents is not None:
-            audio_rows = torch.cat([block_state.audio_condition_latents.to(device), audio_rows])
+        if block_state.audio_condition_latents:
+            audio_rows = torch.cat(
+                [rows.to(device) for rows in block_state.audio_condition_latents] + [audio_rows]
+            )
         block_state.latents, block_state.audio_latents = video_rows, audio_rows
 
         self.set_block_state(state, block_state)
@@ -587,7 +603,7 @@ def __call__(self, components: MiniMaxH3ModularPipeline, state: PipelineState) -
                     block_state.text_indices.numel(),
                     float(timestep),
                     float(audio_timestep),
-                    max(float(timestep), MINIMAX_H3_KEYFRAME_NOISE_AUG),
+                    max(float(timestep), components.keyframe_noise_aug),
                     1.0,
                 )
             )
diff --git a/src/diffusers/modular_pipelines/minimax_h3/before_encoder.py b/src/diffusers/modular_pipelines/minimax_h3/before_encoder.py
index 86c045be683e..41eee332faf4 100644
--- a/src/diffusers/modular_pipelines/minimax_h3/before_encoder.py
+++ b/src/diffusers/modular_pipelines/minimax_h3/before_encoder.py
@@ -23,24 +23,17 @@
 from ..modular_pipeline_utils import ComponentSpec, InputParam, OutputParam
 from .modular_pipeline import MiniMaxH3ModularPipeline, MiniMaxH3Ref2VAModularPipeline
 from .packing import (
-    MINIMAX_H3_CANVAS_MULTIPLE,
-    MINIMAX_H3_FPS,
-    MINIMAX_H3_MAX_DURATION,
-    MINIMAX_H3_MIN_DURATION,
     align_num_frames,
     resolve_canvas_size,
 )
 from .packing_ref2va import (
-    MINIMAX_H3_MAX_REFERENCE_AUDIOS,
-    MINIMAX_H3_MAX_REFERENCE_IMAGES,
-    MINIMAX_H3_MAX_REFERENCE_VIDEOS,
-    MINIMAX_H3_MAX_REFERENCES,
-    MiniMaxH3PreparedReference,
+    MiniMaxH3AudioReference,
+    MiniMaxH3ImageReference,
     MiniMaxH3Reference,
+    MiniMaxH3VideoReference,
     prepare_reference_frames,
     prepare_reference_image,
     prepare_reference_waveform,
-    reference_kind,
     reference_media_to_uint8,
     resample_reference_frames,
     resolve_reference_image_size,
@@ -126,7 +119,9 @@ def __call__(self, components: MiniMaxH3ModularPipeline, state: PipelineState) -
             if keyframe is not None
         )
         if block_state.height is None:
-            block_state.height, block_state.width = resolve_canvas_size(*keyframes[0].size)
+            block_state.height, block_state.width = resolve_canvas_size(
+                *keyframes[0].size, components.canvas_multiple
+            )
 
         prepared = []
         for index, keyframe in enumerate(keyframes):
@@ -162,6 +157,27 @@ def __call__(self, components: MiniMaxH3ModularPipeline, state: PipelineState) -
 class MiniMaxH3Ref2VASetupStep(ModularPipelineBlocks):
     model_name = "minimax-h3-ref2va"
 
+    def __init__(
+        self, max_images: int = 9, max_videos: int = 3, max_audios: int = 3, max_references: int = 12
+    ):
+        r"""
+        Resolve a `ref2va` request's plan.
+
+        Args:
+            max_images (`int`, defaults to 9): Image references a request may carry.
+            max_videos (`int`, defaults to 3): Video references a request may carry.
+            max_audios (`int`, defaults to 3): Audio references a request may carry.
+            max_references (`int`, defaults to 12): References of any modality a request may carry in total.
+
+        The four limits are what MiniMax-H3 documents for the released checkpoint; they bound nothing but this
+        block's own validation, so a fine-tune that packs more can raise them.
+        """
+        self.max_images = max_images
+        self.max_videos = max_videos
+        self.max_audios = max_audios
+        self.max_references = max_references
+        super().__init__()
+
     @property
     def description(self) -> str:
         return (
@@ -170,15 +186,13 @@ def description(self) -> str:
             "imply when it was left open, and the latent geometry every later block keys off."
         )
 
-    @staticmethod
-    def _check_inputs(components, block_state) -> None:
+    def _check_inputs(self, components, block_state) -> None:
         if (block_state.height is None) != (block_state.width is None):
             raise ValueError("`height` and `width` have to be passed together, or neither of them.")
-        if block_state.height is not None and (
-            block_state.height % MINIMAX_H3_CANVAS_MULTIPLE or block_state.width % MINIMAX_H3_CANVAS_MULTIPLE
-        ):
+        multiple = components.canvas_multiple
+        if block_state.height is not None and (block_state.height % multiple or block_state.width % multiple):
             raise ValueError(
-                f"`height` and `width` must be multiples of {MINIMAX_H3_CANVAS_MULTIPLE}, got "
+                f"`height` and `width` must be multiples of {multiple}, got "
                 f"{block_state.height}x{block_state.width}."
             )
         # The duration the request generates is the one of the *aligned* frame count, so that is what the ceiling has
@@ -190,13 +204,13 @@ def _check_inputs(components, block_state) -> None:
                 block_state.num_frames, components.vae_frames_per_chunk, components.vae_latents_per_chunk
             )
         )
-        duration = None if aligned_num_frames is None else aligned_num_frames / MINIMAX_H3_FPS
-        if duration is not None and not MINIMAX_H3_MIN_DURATION <= duration <= MINIMAX_H3_MAX_DURATION:
+        duration = None if aligned_num_frames is None else aligned_num_frames / components.fps
+        if duration is not None and not components.min_duration <= duration <= components.max_duration:
             raise ValueError(
-                f"MiniMax-H3 generates between {MINIMAX_H3_MIN_DURATION} and {MINIMAX_H3_MAX_DURATION} seconds at "
-                f"{MINIMAX_H3_FPS} fps, so `num_frames`, rounded up to the next `17 * n + 5` the video VAE can "
-                f"encode, must be between {int(MINIMAX_H3_MIN_DURATION * MINIMAX_H3_FPS)} and "
-                f"{int(MINIMAX_H3_MAX_DURATION * MINIMAX_H3_FPS)}, got {block_state.num_frames} (rounded up to "
+                f"MiniMax-H3 generates between {components.min_duration} and {components.max_duration} seconds at "
+                f"{components.fps} fps, so `num_frames`, rounded up to the next `17 * n + 5` the video VAE can "
+                f"encode, must be between {int(components.min_duration * components.fps)} and "
+                f"{int(components.max_duration * components.fps)}, got {block_state.num_frames} (rounded up to "
                 f"{aligned_num_frames})."
             )
 
@@ -204,17 +218,27 @@ def _check_inputs(components, block_state) -> None:
             raise ValueError(
                 "`ref2va` needs at least one reference; use `MiniMaxH3ModularPipeline` for text-only requests."
             )
-        kinds = [reference_kind(index, entry) for index, entry in enumerate(block_state.references)]
+        for index, entry in enumerate(block_state.references):
+            if not isinstance(entry, MiniMaxH3Reference):
+                raise ValueError(
+                    f"`references[{index}]` must be a [`MiniMaxH3ImageReference`], [`MiniMaxH3VideoReference`] or "
+                    f"[`MiniMaxH3AudioReference`], got {type(entry)}. MiniMax-H3 blocks never open media files, so a "
+                    "request that holds paths decodes them first — with "
+                    "[`~modular_pipelines.minimax_h3.decode_reference_video`] and "
+                    "[`~modular_pipelines.minimax_h3.decode_reference_audio`], or by putting a "
+                    "[`MiniMaxH3Ref2VALoadReferencesStep`] in front of these blocks."
+                )
+        kinds = [entry.kind for entry in block_state.references]
         for kind, limit in (
-            ("image", MINIMAX_H3_MAX_REFERENCE_IMAGES),
-            ("video", MINIMAX_H3_MAX_REFERENCE_VIDEOS),
-            ("audio", MINIMAX_H3_MAX_REFERENCE_AUDIOS),
+            ("image", self.max_images),
+            ("video", self.max_videos),
+            ("audio", self.max_audios),
         ):
             if kinds.count(kind) > limit:
                 raise ValueError(f"MiniMax-H3 accepts at most {limit} {kind} references, got {kinds.count(kind)}.")
-        if len(kinds) > MINIMAX_H3_MAX_REFERENCES:
+        if len(kinds) > self.max_references:
             raise ValueError(
-                f"MiniMax-H3 accepts at most {MINIMAX_H3_MAX_REFERENCES} references in total, got {len(kinds)}."
+                f"MiniMax-H3 accepts at most {self.max_references} references in total, got {len(kinds)}."
             )
         if set(kinds) == {"audio"}:
             raise ValueError(
@@ -232,11 +256,14 @@ def inputs(self) -> list[InputParam]:
                 description=(
                     "The references to condition on, **in the order the model should read them**: the order labels "
                     "them in the prompt presentation and lays them out on the shared rotary clock, so a different "
-                    "order is a different request. Every [`MiniMaxH3Reference`] carries exactly one medium, a path or "
-                    "in-memory media — `image` (at most 9), `video` at its own `fps` (at most 3, whose `audio` "
-                    "soundtrack is conditioned on as well), or `audio` at its own `sample_rate` (at most 3) — for at "
-                    "most 12 references in total, and audio references cannot be the only ones. A path is decoded "
-                    "when the reference is built, so these blocks only ever see pixels and samples."
+                    "order is a different request. One dataclass per modality, all holding in-memory media — a "
+                    "[`MiniMaxH3ImageReference`] (at most 9), a [`MiniMaxH3VideoReference`] at its own `fps` (at most "
+                    "3, whose `audio` soundtrack is conditioned on as well), or a [`MiniMaxH3AudioReference`] at its "
+                    "own `sample_rate` (at most 3) — for at most 12 references in total, and audio references cannot "
+                    "be the only ones. These blocks never open a media file: decode with "
+                    "[`~modular_pipelines.minimax_h3.decode_reference_video`] and "
+                    "[`~modular_pipelines.minimax_h3.decode_reference_audio`], which bring the rates along, or put a "
+                    "[`MiniMaxH3Ref2VALoadReferencesStep`] in front of these blocks."
                 ),
             ),
             InputParam.template("height", description="Height of the generated video in pixels, a multiple of 32."),
@@ -260,15 +287,21 @@ def intermediate_outputs(self) -> list[OutputParam]:
             OutputParam("num_frames", type_hint=int, description="Resolved number of frames, of the form 17 * n + 5."),
             OutputParam(
                 "prepared_references",
-                type_hint=list[MiniMaxH3PreparedReference],
-                description="The references prepared at their own resolutions, in packed order.",
+                type_hint=list[MiniMaxH3Reference],
+                description=(
+                    "The references normalized onto MiniMax-H3's own rates and resolutions, in packed order: the "
+                    "same public reference types the request passed in, with an image resized to its own 2048 pixel "
+                    "short edge, a video resampled onto 24 fps and onto the canvas its own aspect ratio resolves "
+                    "to, and a soundtrack put on the audio VAE's sample rate and truncated to the generated "
+                    "duration."
+                ),
             ),
         ]
 
     @staticmethod
     def prepare_references(
         components, references: list[MiniMaxH3Reference], num_frames: int | None
-    ) -> tuple[list[MiniMaxH3PreparedReference], int]:
+    ) -> tuple[list[MiniMaxH3Reference], int]:
         r"""
         Resolve the references and, if it was left open, the duration they imply.
 
@@ -278,7 +311,9 @@ def prepare_references(
         the generated duration. None of this touches the target canvas.
 
         A reference that left its `fps` or its `sample_rate` out is taken to already be at MiniMax-H3's own rate, and
-        its frames or its samples then flow through untouched.
+        its frames or its samples then flow through untouched. Decoding a file with
+        [`~modular_pipelines.minimax_h3.decode_reference_video`] or
+        [`~modular_pipelines.minimax_h3.decode_reference_audio`] fills both in from the container.
 
         A video reference goes through the two passes the reference implementation's `ffmpeg` decode applied, in the
         same order: the constant frame rate resample of `resample_reference_frames` and the LANCZOS rescale of
@@ -292,63 +327,74 @@ def prepare_references(
                 The requested frame count, or `None` to derive it from the single audio-bearing reference.
 
         Returns:
-            `tuple[list[MiniMaxH3PreparedReference], int]`: the prepared references, in packed order, and the frame
-            count.
+            `tuple[list[MiniMaxH3Reference], int]`: the references normalized onto MiniMax-H3's own rates and
+            resolutions, in packed order and of the same public types they came in as, and the frame count.
         """
-        resolved = [
-            MiniMaxH3PreparedReference(kind=reference_kind(index, entry), has_audio=entry.has_audio)
-            for index, entry in enumerate(references)
-        ]
-
         # The duration may be left open, but then exactly one reference may carry audio, or the request is ambiguous.
         if num_frames is None:
-            audio_bearing = [index for index, reference in enumerate(resolved) if reference.has_audio]
+            audio_bearing = [index for index, reference in enumerate(references) if reference.has_audio]
             if len(audio_bearing) != 1:
                 raise ValueError(
                     "`num_frames` may only be left to the references when exactly one of them carries audio, got "
                     f"{len(audio_bearing)}."
                 )
             index = audio_bearing[0]
-            sample_rate = references[index].sample_rate or components.audio_sampling_rate
+            sample_rate = references[index].sample_rate
+            if sample_rate is None:
+                sample_rate = components.audio_sampling_rate
             duration = references[index].audio.shape[-1] / sample_rate
-            if not MINIMAX_H3_MIN_DURATION <= duration <= MINIMAX_H3_MAX_DURATION:
+            if not components.min_duration <= duration <= components.max_duration:
                 raise ValueError(
                     f"`references[{index}]` is {duration:g} seconds long, outside the "
-                    f"{MINIMAX_H3_MIN_DURATION} to {MINIMAX_H3_MAX_DURATION} seconds MiniMax-H3 generates."
+                    f"{components.min_duration} to {components.max_duration} seconds MiniMax-H3 generates."
                 )
             num_frames = align_num_frames(
-                round(duration * MINIMAX_H3_FPS), components.vae_frames_per_chunk, components.vae_latents_per_chunk
+                round(duration * components.fps), components.vae_frames_per_chunk, components.vae_latents_per_chunk
             )
             # The duration the request generates is the one of the *aligned* frame count, so that is what the
             # ceiling has to hold for: a 14.99 second soundtrack rounds up to 362 frames, i.e. 15.083 seconds.
-            if num_frames / MINIMAX_H3_FPS > MINIMAX_H3_MAX_DURATION:
+            if num_frames / components.fps > components.max_duration:
                 raise ValueError(
                     f"`references[{index}]` is {duration:g} seconds long, which rounds up to {num_frames} frames "
-                    f"(`17 * n + 5`), i.e. {num_frames / MINIMAX_H3_FPS:g} seconds — past the "
-                    f"{MINIMAX_H3_MAX_DURATION} seconds MiniMax-H3 generates. Pass `num_frames` to generate a "
+                    f"(`17 * n + 5`), i.e. {num_frames / components.fps:g} seconds — past the "
+                    f"{components.max_duration} seconds MiniMax-H3 generates. Pass `num_frames` to generate a "
                     "shorter video from this soundtrack."
                 )
         num_frames = align_num_frames(num_frames, components.vae_frames_per_chunk, components.vae_latents_per_chunk)
 
-        for reference, entry in zip(resolved, references):
-            if reference.kind == "image":
-                image = entry.image
-                if not isinstance(image, Image.Image):
-                    image = Image.fromarray(reference_media_to_uint8(image))
-                image = ImageOps.exif_transpose(image).convert("RGB")
-                height, width = resolve_reference_image_size(*image.size)
-                reference.image = prepare_reference_image(image, height, width)
-            elif reference.kind == "video":
-                frames = resample_reference_frames(reference_media_to_uint8(entry.video), float(entry.fps))
-                reference.frames = prepare_reference_frames(frames, num_frames)
-            if reference.has_audio:
-                reference.waveform = prepare_reference_waveform(
+        prepared = []
+        for entry in references:
+            waveform = None
+            if entry.has_audio:
+                sample_rate = entry.sample_rate
+                if sample_rate is None:
+                    sample_rate = components.audio_sampling_rate
+                waveform = prepare_reference_waveform(
                     entry.audio,
-                    entry.sample_rate or components.audio_sampling_rate,
+                    sample_rate,
                     components.audio_sampling_rate,
-                    max_duration=num_frames / MINIMAX_H3_FPS,
+                    max_duration=num_frames / components.fps,
+                )
+
+            if entry.kind == "image":
+                image = ImageOps.exif_transpose(entry.image).convert("RGB")
+                height, width = resolve_reference_image_size(*image.size, components.canvas_multiple)
+                prepared.append(MiniMaxH3ImageReference(image=prepare_reference_image(image, height, width)))
+            elif entry.kind == "video":
+                frames = resample_reference_frames(reference_media_to_uint8(entry.frames), float(entry.fps))
+                prepared.append(
+                    MiniMaxH3VideoReference(
+                        frames=prepare_reference_frames(frames, num_frames, components.canvas_multiple),
+                        fps=float(components.fps),
+                        audio=waveform,
+                        sample_rate=None if waveform is None else components.audio_sampling_rate,
+                    )
+                )
+            else:
+                prepared.append(
+                    MiniMaxH3AudioReference(audio=waveform, sample_rate=components.audio_sampling_rate)
                 )
-        return resolved, num_frames
+        return prepared, num_frames
 
     @torch.no_grad()
     def __call__(self, components: MiniMaxH3Ref2VAModularPipeline, state: PipelineState) -> PipelineState:
@@ -356,7 +402,7 @@ def __call__(self, components: MiniMaxH3Ref2VAModularPipeline, state: PipelineSt
         self._check_inputs(components, block_state)
 
         if block_state.height is None:
-            block_state.height, block_state.width = resolve_canvas_size(16, 9)
+            block_state.height, block_state.width = resolve_canvas_size(16, 9, components.canvas_multiple)
 
         requested_num_frames = block_state.num_frames
         block_state.prepared_references, block_state.num_frames = self.prepare_references(
diff --git a/src/diffusers/modular_pipelines/minimax_h3/decoders.py b/src/diffusers/modular_pipelines/minimax_h3/decoders.py
index 2eec15d15638..6620d8a36996 100644
--- a/src/diffusers/modular_pipelines/minimax_h3/decoders.py
+++ b/src/diffusers/modular_pipelines/minimax_h3/decoders.py
@@ -21,7 +21,6 @@
 from ..modular_pipeline import ModularPipelineBlocks, PipelineState
 from ..modular_pipeline_utils import ComponentSpec, InputParam, OutputParam
 from .modular_pipeline import MiniMaxH3ModularPipeline
-from .packing import MINIMAX_H3_AUDIO_CHANNELS, MINIMAX_H3_PIXEL_MEAN, MINIMAX_H3_PIXEL_STD
 
 
 logger = logging.get_logger(__name__)  # pylint: disable=invalid-name
@@ -121,7 +120,7 @@ def __call__(self, components: MiniMaxH3ModularPipeline, state: PipelineState) -
 
         # Audio rows are channel-major, and the mono audio VAE takes the two stereo channels as two batch items.
         audio_rows = block_state.audio_latents[block_state.num_condition_audio_rows :]
-        audio_rows = audio_rows.reshape(MINIMAX_H3_AUDIO_CHANNELS, block_state.num_audio_latents, audio_rows.shape[-1])
+        audio_rows = audio_rows.reshape(components.audio_channels, block_state.num_audio_latents, audio_rows.shape[-1])
         block_state.audio_latents = audio_rows.permute(0, 2, 1).contiguous()
 
         self.set_block_state(state, block_state)
@@ -181,8 +180,8 @@ def __call__(self, components: MiniMaxH3ModularPipeline, state: PipelineState) -
 
         with torch.autocast(device_type=device.type, dtype=torch.float16, enabled=device.type == "cuda"):
             video = components.vae.decode(latents, return_dict=False)[0]
-        pixel_mean = torch.tensor(MINIMAX_H3_PIXEL_MEAN, device=device).view(1, -1, 1, 1, 1)
-        pixel_std = torch.tensor(MINIMAX_H3_PIXEL_STD, device=device).view(1, -1, 1, 1, 1)
+        pixel_mean = torch.tensor(components.pixel_mean, device=device).view(1, -1, 1, 1, 1)
+        pixel_std = torch.tensor(components.pixel_std, device=device).view(1, -1, 1, 1, 1)
         video = (video.float() * pixel_std + pixel_mean).clamp(0, 1)
         block_state.videos = components.video_processor.postprocess_video(video, output_type=block_state.output_type)
 
diff --git a/src/diffusers/modular_pipelines/minimax_h3/encoders.py b/src/diffusers/modular_pipelines/minimax_h3/encoders.py
index e70a40fde61b..a6ae5c7f9a07 100644
--- a/src/diffusers/modular_pipelines/minimax_h3/encoders.py
+++ b/src/diffusers/modular_pipelines/minimax_h3/encoders.py
@@ -21,16 +21,8 @@
 from ..modular_pipeline import ModularPipelineBlocks, PipelineState
 from ..modular_pipeline_utils import ComponentSpec, InputParam, OutputParam
 from .modular_pipeline import MiniMaxH3ModularPipeline, MiniMaxH3Ref2VAModularPipeline
-from .packing import (
-    MINIMAX_H3_KEYFRAME_ENCODE_SEED,
-    MINIMAX_H3_PIXEL_MEAN,
-    MINIMAX_H3_PIXEL_STD,
-    MINIMAX_H3_TEXT_ENCODER_LAYER,
-    MINIMAX_H3_TEXT_TAG,
-    MINIMAX_H3_VIDEO_TAG,
-)
 from .packing_ref2va import (
-    MiniMaxH3PreparedReference,
+    MiniMaxH3Reference,
     build_ref2va_presentation,
     sample_reference_video_frames,
     trim_reference_num_frames,
@@ -96,10 +88,12 @@ def encode_prompt(
         processor,
         prompt: str,
         images: list | None = None,
+        *,
+        text_encoder_layer: int,# can you set the default?
+        text_tag: int,# can you set the default?
+        video_tag: int, # can you set the default?
         device: torch.device | None = None,
         dtype: torch.dtype | None = None,
-        text_tag: int = MINIMAX_H3_TEXT_TAG,
-        video_tag: int = MINIMAX_H3_VIDEO_TAG,
     ) -> tuple[torch.Tensor, torch.Tensor]:
         r"""
         Build MiniMax-H3's presentation of a request and encode it.
@@ -122,12 +116,12 @@ def encode_prompt(
         """
 
         num_layers = text_encoder.config.text_config.num_hidden_layers
-        if num_layers <= MINIMAX_H3_TEXT_ENCODER_LAYER:
+        if num_layers <= text_encoder_layer:
             raise ValueError(
-                f"MiniMax-H3 conditions on `hidden_states[{MINIMAX_H3_TEXT_ENCODER_LAYER}]` of its Qwen3-VL "
-                f"conditioner, which needs more than {MINIMAX_H3_TEXT_ENCODER_LAYER} decoder layers, but "
+                f"MiniMax-H3 conditions on `hidden_states[{text_encoder_layer}]` of its Qwen3-VL "
+                f"conditioner, which needs more than {text_encoder_layer} decoder layers, but "
                 f"`text_encoder` has {num_layers}. The last hidden state of a stack truncated to exactly "
-                f"{MINIMAX_H3_TEXT_ENCODER_LAYER} layers is post-norm and is not the conditioning MiniMax-H3 expects."
+                f"{text_encoder_layer} layers is post-norm and is not the conditioning MiniMax-H3 expects."
             )
 
         pixel_values, image_grid_thw = None, None
@@ -177,7 +171,7 @@ def encode_prompt(
             use_cache=False,
             output_hidden_states=True,
         )
-        prompt_embeds = outputs.hidden_states[MINIMAX_H3_TEXT_ENCODER_LAYER].to(device=device, dtype=dtype)
+        prompt_embeds = outputs.hidden_states[text_encoder_layer].to(device=device, dtype=dtype)
         return prompt_embeds, torch.tensor(token_tags, dtype=torch.long)
 
     @torch.no_grad()
@@ -197,6 +191,9 @@ def __call__(self, components: MiniMaxH3ModularPipeline, state: PipelineState) -
             components.processor,
             block_state.prompt,
             block_state.keyframes,
+            text_encoder_layer=components.text_encoder_layer,
+            text_tag=components.text_tag,
+            video_tag=components.video_tag,
             device=components._execution_device,
             dtype=components.text_encoder.dtype,
         )
@@ -245,7 +242,9 @@ def intermediate_outputs(self) -> list[OutputParam]:
         ]
 
     @staticmethod
-    def encode_keyframes(vae, images: list, device: torch.device) -> list[torch.Tensor]:
+    def encode_keyframes(
+        vae, images: list, pixel_mean: tuple, pixel_std: tuple, encode_seed: int, device: torch.device
+    ) -> list[torch.Tensor]:
         r"""
         Encode the `fl2va` keyframes into normalized conditioning latents.
 
@@ -258,6 +257,9 @@ def encode_keyframes(vae, images: list, device: torch.device) -> list[torch.Tens
             vae (`AutoencoderKLMiniMaxH3`): The video VAE.
             images (`list[PIL.Image.Image]`):
                 The keyframes, already prepared onto the target canvas, in packed order.
+            pixel_mean (`tuple[float, float, float]`), pixel_std (`tuple[float, float, float]`):
+                The video VAE's pixel convention, i.e. `components.pixel_mean` / `components.pixel_std`.
+            encode_seed (`int`): Seed the posterior is sampled under, i.e. `components.keyframe_encode_seed`.
             device (`torch.device`): The device to run the VAE on.
 
         Returns:
@@ -267,15 +269,15 @@ def encode_keyframes(vae, images: list, device: torch.device) -> list[torch.Tens
         """
         latents_mean = torch.tensor(vae.config.latents_mean).view(1, -1, 1, 1, 1)
         latents_std = torch.tensor(vae.config.latents_std).view(1, -1, 1, 1, 1)
-        pixel_mean = torch.tensor(MINIMAX_H3_PIXEL_MEAN, device=device).view(1, -1, 1, 1, 1)
-        pixel_std = torch.tensor(MINIMAX_H3_PIXEL_STD, device=device).view(1, -1, 1, 1, 1)
+        pixel_mean = torch.tensor(pixel_mean, device=device).view(1, -1, 1, 1, 1)
+        pixel_std = torch.tensor(pixel_std, device=device).view(1, -1, 1, 1, 1)
 
         keyframe_latents = []
         for image in images:
             pixels = torch.from_numpy(np.array(image)).to(device).permute(2, 0, 1)[None, :, None]
             pixels = (pixels.to(torch.float32).div(255.0) - pixel_mean) / pixel_std
             posterior = vae.encode(pixels, return_dict=False)[0]
-            latents = posterior.sample(generator=torch.Generator().manual_seed(MINIMAX_H3_KEYFRAME_ENCODE_SEED))
+            latents = posterior.sample(generator=torch.Generator().manual_seed(encode_seed))
             # The sampled latent is rounded to float16 before it is normalized: ~11 bits of every conditioning
             # latent, so the released model's conditioning cannot be reproduced without it.
             latents = latents.to(torch.float16).float().cpu()
@@ -287,7 +289,14 @@ def __call__(self, components: MiniMaxH3ModularPipeline, state: PipelineState) -
         block_state = self.get_block_state(state)
         device = components._execution_device
 
-        block_state.condition_latents = self.encode_keyframes(components.vae, block_state.keyframes, device)
+        block_state.condition_latents = self.encode_keyframes(
+            components.vae,
+            block_state.keyframes,
+            components.pixel_mean,
+            components.pixel_std,
+            components.keyframe_encode_seed,
+            device,
+        )
 
         self.set_block_state(state, block_state)
         return components, state
@@ -319,7 +328,7 @@ def inputs(self) -> list[InputParam]:
             InputParam.template("prompt", description="The prompt to guide generation, a single string."),
             InputParam(
                 name="prepared_references",
-                type_hint=list[MiniMaxH3PreparedReference],
+                type_hint=list[MiniMaxH3Reference],
                 required=True,
                 description="The prepared references, in packed order.",
             ),
@@ -350,7 +359,11 @@ def encode_prompt(
         tokenizer,
         processor,
         prompt: str,
-        references: list[MiniMaxH3PreparedReference],
+        references: list[MiniMaxH3Reference],
+        *,
+        text_encoder_layer: int, # can you add default
+        text_tag: int, # can you add default
+        video_tag: int, # can you add default
         device: torch.device | None = None,
         dtype: torch.dtype | None = None,
     ) -> tuple[torch.Tensor, torch.Tensor]:
@@ -366,7 +379,7 @@ def encode_prompt(
 
         Args:
             prompt (`str`): The prompt to encode.
-            references (`list[MiniMaxH3PreparedReference]`):
+            references (`list[MiniMaxH3Reference]`):
                 The prepared references, in packed order, as returned by
                 [`~MiniMaxH3Ref2VASetupStep.prepare_references`].
             device (`torch.device`, *optional*): The device to run the conditioner on.
@@ -378,12 +391,12 @@ def encode_prompt(
         """
 
         num_layers = text_encoder.config.text_config.num_hidden_layers
-        if num_layers <= MINIMAX_H3_TEXT_ENCODER_LAYER:
+        if num_layers <= text_encoder_layer:
             raise ValueError(
-                f"MiniMax-H3 conditions on `hidden_states[{MINIMAX_H3_TEXT_ENCODER_LAYER}]` of its Qwen3-VL "
-                f"conditioner, which needs more than {MINIMAX_H3_TEXT_ENCODER_LAYER} decoder layers, but "
+                f"MiniMax-H3 conditions on `hidden_states[{text_encoder_layer}]` of its Qwen3-VL "
+                f"conditioner, which needs more than {text_encoder_layer} decoder layers, but "
                 f"`text_encoder` has {num_layers}. The last hidden state of a stack truncated to exactly "
-                f"{MINIMAX_H3_TEXT_ENCODER_LAYER} layers is post-norm and is not the conditioning MiniMax-H3 expects."
+                f"{text_encoder_layer} layers is post-norm and is not the conditioning MiniMax-H3 expects."
             )
 
         merge_size = processor.image_processor.merge_size**2
@@ -394,26 +407,26 @@ def encode_prompt(
             pixel_values, image_grid_thw = vision["pixel_values"], vision["image_grid_thw"]
             image_token_counts = [int(grid.prod()) // merge_size for grid in image_grid_thw]
 
-        pixel_values_videos, video_grid_thw, video_block_token_counts = None, None, []
+        pixel_values_videos, video_grid_thw = None, None
+        video_block_token_counts, video_block_timestamps = [], []
         videos = [reference for reference in references if reference.kind == "video"]
         if videos:
             sampled = [sample_reference_video_frames(reference.frames) for reference in videos]
-            for reference, (_, block_timestamps) in zip(videos, sampled):
-                reference.block_timestamps = block_timestamps
+            video_block_timestamps = [timestamps for _, timestamps in sampled]
             vision = processor.video_processor(
                 videos=[np.stack(frames) for frames, _ in sampled], do_sample_frames=False, return_tensors="pt"
             )
             pixel_values_videos, video_grid_thw = vision["pixel_values_videos"], vision["video_grid_thw"]
             video_block_token_counts = [int(grid[1]) * int(grid[2]) // merge_size for grid in video_grid_thw]
-            for reference, grid in zip(videos, video_grid_thw):
-                if int(grid[0]) != len(reference.block_timestamps):
+            for timestamps, grid in zip(video_block_timestamps, video_grid_thw):
+                if int(grid[0]) != len(timestamps):
                     raise ValueError(
                         f"The processor merged a reference video into {int(grid[0])} vision blocks, but MiniMax-H3 "
-                        f"labels {len(reference.block_timestamps)} of them."
+                        f"labels {len(timestamps)} of them."
                     )
 
         token_ids, token_tags = build_ref2va_presentation(
-            tokenizer, prompt, references, image_token_counts, video_block_token_counts
+            tokenizer, prompt, references, image_token_counts, video_block_token_counts, video_block_timestamps
         )
         input_ids = torch.tensor([token_ids], dtype=torch.long, device=device)
         # Qwen3-VL lays its 3D rotary positions out per modality run, which it reads off the token type ids the
@@ -446,7 +459,7 @@ def encode_prompt(
             use_cache=False,
             output_hidden_states=True,
         )
-        prompt_embeds = outputs.hidden_states[MINIMAX_H3_TEXT_ENCODER_LAYER].to(device=device, dtype=dtype)
+        prompt_embeds = outputs.hidden_states[text_encoder_layer].to(device=device, dtype=dtype)
         return prompt_embeds, torch.tensor(token_tags, dtype=torch.long)
 
     @torch.no_grad()
@@ -466,6 +479,9 @@ def __call__(self, components: MiniMaxH3Ref2VAModularPipeline, state: PipelineSt
             components.processor,
             block_state.prompt,
             block_state.prepared_references,
+            text_encoder_layer=components.text_encoder_layer,
+            text_tag=components.text_tag,
+            video_tag=components.video_tag,
             device=components._execution_device,
             dtype=components.text_encoder.dtype,
         )
@@ -499,9 +515,9 @@ def inputs(self) -> list[InputParam]:
         return [
             InputParam(
                 name="prepared_references",
-                type_hint=list[MiniMaxH3PreparedReference],
+                type_hint=list[MiniMaxH3Reference],
                 required=True,
-                description="The prepared references, in packed order. Their latent geometry is filled in here.",
+                description="The references normalized by the setup step, in packed order.",
             ),
         ]
 
@@ -519,20 +535,22 @@ def intermediate_outputs(self) -> list[OutputParam]:
             ),
             OutputParam(
                 "audio_condition_latents",
-                type_hint=torch.Tensor,
+                type_hint=list[torch.Tensor],
                 description=(
-                    "The clean audio conditioning rows of the reference soundtracks, in packed order, or None when "
-                    "the references carry none."
+                    "The clean audio conditioning rows of the reference soundtracks, one `(num_audio_latents * 2, "
+                    "audio_latent_channels)` tensor per audio-bearing reference in packed order. One entry per "
+                    "reference rather than one concatenated block, because the packed layout is built from the row "
+                    "count of each."
                 ),
             ),
         ]
 
     @staticmethod
     def encode_references(
-        components, references: list[MiniMaxH3PreparedReference], device: torch.device | None = None
-    ) -> tuple[torch.Tensor | None, torch.Tensor | None]:
+        components, references: list[MiniMaxH3Reference], device: torch.device | None = None
+    ) -> tuple[list[torch.Tensor], list[torch.Tensor]]:
         r"""
-        Encode the references into packed conditioning rows, and resolve their latent geometry.
+        Encode the references into conditioning latents.
 
         Image and video references go through the video VAE with the same recipe the `fl2va` keyframes use: the
         posterior is *sampled* under a generator seeded with 42 independently of the request seed, and the sampled
@@ -540,20 +558,23 @@ def encode_references(
         encoder alone, while a video reference goes through the 17-frames-per-5-latents temporal chunking. Reference
         soundtracks instead take the posterior *mean*, and are never sampled.
 
+        The latent geometry every later block keys off is the shape of what this returns, so nothing has to be
+        written back onto the references.
+
         Args:
-            references (`list[MiniMaxH3PreparedReference]`):
-                The prepared references, in packed order. Their latent geometry is filled in here.
+            references (`list[MiniMaxH3Reference]`):
+                The references normalized by the setup step, in packed order.
             device (`torch.device`, *optional*): The device to run the VAEs on.
 
         Returns:
-            `tuple[torch.Tensor, torch.Tensor]`: the `(num_condition_video_rows, latent_channels * prod(patch_size))`
-            video rows and the `(num_condition_audio_rows, audio_latent_channels)` audio rows, both float32 on CPU and
-            both `None` when the references carry no such rows.
+            `tuple[list[torch.Tensor], list[torch.Tensor]]`: one `(1, latent_channels, num_latent_frames,
+            latent_height, latent_width)` tensor per image and video reference, and one `(num_audio_latents * 2,
+            audio_latent_channels)` tensor per audio-bearing reference, both in packed order and float32 on CPU.
         """
         latents_mean = torch.tensor(components.vae.config.latents_mean).view(1, -1, 1, 1, 1)
         latents_std = torch.tensor(components.vae.config.latents_std).view(1, -1, 1, 1, 1)
-        pixel_mean = torch.tensor(MINIMAX_H3_PIXEL_MEAN, device=device).view(1, -1, 1, 1, 1)
-        pixel_std = torch.tensor(MINIMAX_H3_PIXEL_STD, device=device).view(1, -1, 1, 1, 1)
+        pixel_mean = torch.tensor(components.pixel_mean, device=device).view(1, -1, 1, 1, 1)
+        pixel_std = torch.tensor(components.pixel_std, device=device).view(1, -1, 1, 1, 1)
         audio_latents_mean = torch.tensor(components.audio_vae.config.latents_mean).view(1, 1, -1)
         audio_latents_std = torch.tensor(components.audio_vae.config.latents_std).view(1, 1, -1)
 
@@ -575,23 +596,22 @@ def encode_references(
                 # A single frame is encoded by the (tiled) spatial encoder alone; a video goes through the temporal
                 # chunking, which is what turns `17 * n + 5` frames into `5 * n + 2` latent frames.
                 posterior = components.vae.encode(pixels, return_dict=False)[0]
-                latents = posterior.sample(generator=torch.Generator().manual_seed(MINIMAX_H3_KEYFRAME_ENCODE_SEED))
+                latents = posterior.sample(
+                    generator=torch.Generator().manual_seed(components.keyframe_encode_seed)
+                )
                 # The sampled latent is rounded to float16 before it is normalized: ~11 bits of every conditioning
                 # latent, so the released model's conditioning cannot be reproduced without it.
                 latents = latents.to(torch.float16).float().cpu()
-                reference.num_latent_frames = latents.shape[2]
-                reference.latent_height, reference.latent_width = latents.shape[3], latents.shape[4]
                 video_latents.append((latents - latents_mean) / latents_std)
 
             if reference.has_audio:
-                posterior = components.audio_vae.encode(reference.waveform.to(device)[:, None], return_dict=False)[0]
+                posterior = components.audio_vae.encode(reference.audio.to(device)[:, None], return_dict=False)[0]
                 # Channel-major rows: the two stereo channels are two batch items of the mono audio VAE.
                 latents = posterior.mode().float().cpu().transpose(1, 2)
-                reference.num_audio_latents = latents.shape[1]
                 normalized = (latents - audio_latents_mean) / audio_latents_std
                 audio_rows.append(normalized.reshape(-1, components.audio_latent_channels))
 
-        return video_latents or None, torch.cat(audio_rows) if audio_rows else None
+        return video_latents, audio_rows
 
     @torch.no_grad()
     def __call__(self, components: MiniMaxH3Ref2VAModularPipeline, state: PipelineState) -> PipelineState:
diff --git a/src/diffusers/modular_pipelines/minimax_h3/modular_pipeline.py b/src/diffusers/modular_pipelines/minimax_h3/modular_pipeline.py
index 125b002d1305..f4084d03b0e7 100644
--- a/src/diffusers/modular_pipelines/minimax_h3/modular_pipeline.py
+++ b/src/diffusers/modular_pipelines/minimax_h3/modular_pipeline.py
@@ -14,6 +14,12 @@
 
 from ...utils import logging
 from ..modular_pipeline import ModularPipeline
+from .packing import (
+    MINIMAX_H3_AUDIO_CHANNELS,
+    MINIMAX_H3_FPS,
+    MINIMAX_H3_TEXT_TAG,
+    MINIMAX_H3_VIDEO_TAG,
+)
 
 
 logger = logging.get_logger(__name__)  # pylint: disable=invalid-name
@@ -92,6 +98,82 @@ def patch_size(self):
             return tuple(self.transformer.config.patch_size)
         return (1, 2, 2)
 
+    @property
+    def canvas_multiple(self):
+        r"""What the generated height and width have to be a multiple of, 32 for the released checkpoint."""
+        # A canvas has to survive the VAE's spatial compression and still be a whole number of patch rows wide, so
+        # the multiple is the product of the two.
+        return self.vae_spatial_compression_ratio * self.patch_size[2]
+
+    @property
+    def fps(self):
+        r"""MiniMax-H3's own frame rate. Everything it generates and conditions on is resampled onto it."""
+        return MINIMAX_H3_FPS
+
+    @property
+    def min_duration(self):
+        r"""Shortest video MiniMax-H3 generates, in seconds."""
+        return 5.0
+
+    @property
+    def max_duration(self):
+        r"""Longest video MiniMax-H3 generates, in seconds."""
+        return 15.0
+
+    @property
+    def audio_channels(self):
+        r"""Channels of the generated soundtrack: MiniMax-H3 is stereo, packed channel-major."""
+        return MINIMAX_H3_AUDIO_CHANNELS
+
+    @property
+    def text_encoder_layer(self):
+        r"""
+        Which Qwen3-VL hidden state conditions the transformer.
+
+        MiniMax-H3 reads `hidden_states[50]`, not the final one: the last layer is post-norm and is not the
+        conditioning the released weights were trained against.
+        """
+        return 50
+
+    @property
+    def pixel_mean(self):
+        r"""Per-channel mean the video VAE's input is normalized by, ImageNet's."""
+        return (0.485, 0.456, 0.406)
+
+    @property
+    def pixel_std(self):
+        r"""Per-channel standard deviation the video VAE's input is normalized by, ImageNet's."""
+        return (0.229, 0.224, 0.225)
+
+    @property
+    def keyframe_encode_seed(self):
+        r"""
+        Seed the conditioning posterior is sampled under, independently of the request's own generator.
+
+        Fixed at 42 in the reference implementation, so the same keyframe always encodes to the same anchor.
+        """
+        return 42
+
+    @property
+    def keyframe_noise_aug(self):
+        r"""
+        The `t` a visual conditioning anchor is held at: 0.999, just short of clean.
+
+        The released model was trained with its anchors very slightly noised, so conditioning on exactly `t = 1.0`
+        is off-distribution.
+        """
+        return 0.999
+
+    @property
+    def text_tag(self):
+        r"""The modality tag of a text row of the packed sequence."""
+        return MINIMAX_H3_TEXT_TAG
+
+    @property
+    def video_tag(self):
+        r"""The modality tag of a video row of the packed sequence, which a vision block's rows also carry."""
+        return MINIMAX_H3_VIDEO_TAG
+
 
 class MiniMaxH3Ref2VAModularPipeline(MiniMaxH3ModularPipeline):
     """
diff --git a/src/diffusers/modular_pipelines/minimax_h3/packing.py b/src/diffusers/modular_pipelines/minimax_h3/packing.py
index a76badbc9960..681bc73caab5 100644
--- a/src/diffusers/modular_pipelines/minimax_h3/packing.py
+++ b/src/diffusers/modular_pipelines/minimax_h3/packing.py
@@ -46,36 +46,19 @@
 MINIMAX_H3_AUDIO_TAG = 2
 
 # MiniMax-H3 generates at a fixed 24 fps and was released for a 768 pixel short edge only, with a soft area cap of
-# 768x1344 and both axes rounded to a multiple of 32.
+# 768x1344. The multiple both axes round to is not here: it follows from the VAE and the transformer, so it is
+# `MiniMaxH3ModularPipeline.canvas_multiple` and reaches these helpers as an argument.
 MINIMAX_H3_FPS = 24
 MINIMAX_H3_SHORT_EDGE = 768
 MINIMAX_H3_MAX_PIXELS = 768 * 1344
-MINIMAX_H3_CANVAS_MULTIPLE = 32
 MINIMAX_H3_MIN_ASPECT_RATIO = 1 / 4
 MINIMAX_H3_MAX_ASPECT_RATIO = 4
-MINIMAX_H3_MIN_DURATION = 5.0
-MINIMAX_H3_MAX_DURATION = 15.0
-
-# The pixel convention of the video VAE: ImageNet-normalized RGB over a `[0, 1]` base range.
-MINIMAX_H3_PIXEL_MEAN = (0.485, 0.456, 0.406)
-MINIMAX_H3_PIXEL_STD = (0.229, 0.224, 0.225)
-
-# MiniMax-H3 conditions on the *unnormalized* hidden state its Qwen3-VL conditioner produces after the 50th of its 64
-# decoder layers, i.e. `hidden_states[50]` (`hidden_states[0]` being the embedding output).
-MINIMAX_H3_TEXT_ENCODER_LAYER = 50
 
 # The audio VAE hops 800 samples at 32 kHz, i.e. 40 latents per second. Stereo is carried as two channel-major
 # blocks of audio rows (and as two batch items at the audio VAE boundary, which is mono).
 MINIMAX_H3_AUDIO_LATENTS_PER_SECOND = 40
 MINIMAX_H3_AUDIO_CHANNELS = 2
 
-# Conditioning rows are not fully clean: the released model noises keyframe latents to `t = 0.999` and runs them at
-# that timestep for every denoising step.
-MINIMAX_H3_KEYFRAME_NOISE_AUG = 0.999
-
-# The seeded posterior sample of the keyframe VAE encode. Fixed at 42 independently of the request seed.
-MINIMAX_H3_KEYFRAME_ENCODE_SEED = 42
-
 # Rotary-time constants. One latent frame spans `5/3 * frames_per_latent` rotary units, where the pattern
 # `(1, 4, 4, 4, 4)` mirrors the VAE's 17-pixel-frames-to-5-latent-frames grouping; the spatial axes are normalized
 # by the square root of the latent area and scaled by 32.
@@ -84,17 +67,19 @@
 _ROPE_SPATIAL_SCALE = 32
 
 
-def resolve_canvas_size(aspect_width: float, aspect_height: float) -> tuple[int, int]:
+def resolve_canvas_size(aspect_width: float, aspect_height: float, canvas_multiple: int) -> tuple[int, int]:
     r"""
     Resolve a display aspect ratio into a MiniMax-H3 canvas.
 
     The short edge starts at 768, the area is capped at `768 * 1344` and both axes are then rounded to the nearest
-    multiple of 32 — so the final area may end up slightly above the pre-rounding budget. Only the ratio of the two
+    `canvas_multiple` — so the final area may end up slightly above the pre-rounding budget. Only the ratio of the two
     arguments matters; pass either the aspect ratio (`16, 9`) or the source dimensions of a keyframe.
 
     Args:
         aspect_width (`float`): Width of the target ratio.
         aspect_height (`float`): Height of the target ratio.
+        canvas_multiple (`int`):
+            What both axes round to, i.e. `components.canvas_multiple` — 32 for the released checkpoint.
 
     Returns:
         `tuple[int, int]`: the `(height, width)` of the canvas.
@@ -118,7 +103,7 @@ def resolve_canvas_size(aspect_width: float, aspect_height: float) -> tuple[int,
         scale = (MINIMAX_H3_MAX_PIXELS / area) ** 0.5
         width, height = width * scale, height * scale
 
-    multiple = MINIMAX_H3_CANVAS_MULTIPLE
+    multiple = canvas_multiple
     return max(multiple, round(height / multiple) * multiple), max(multiple, round(width / multiple) * multiple)
 
 
diff --git a/src/diffusers/modular_pipelines/minimax_h3/packing_ref2va.py b/src/diffusers/modular_pipelines/minimax_h3/packing_ref2va.py
index f68fd0217028..8f0646a4588e 100644
--- a/src/diffusers/modular_pipelines/minimax_h3/packing_ref2va.py
+++ b/src/diffusers/modular_pipelines/minimax_h3/packing_ref2va.py
@@ -32,32 +32,24 @@
 resolution (2048 pixel short edge for images, MiniMax-H3's 768 pixel canvas for videos) and carries its own
 aspect-normalized spatial grid.
 
-References reach the blocks as in-memory media: a video is decoded frames plus the `fps` they carry, and a soundtrack
-a waveform plus its sample rate. A [`MiniMaxH3Reference`] takes a path or a URL too, but it decodes it when it is
-built, so that no block of this model ever opens a media file.
+References reach the blocks as in-memory media, one dataclass per modality: a [`MiniMaxH3VideoReference`] is decoded
+frames plus the `fps` they carry, a [`MiniMaxH3AudioReference`] a waveform plus its sample rate, and a
+[`MiniMaxH3ImageReference`] a single image. No block of this model opens a media file; decoding a path is the caller's
+job, and [`~modular_pipelines.minimax_h3.reference_loading`] is the convenience for doing it.
 """
 
-import contextlib
 import math
-import os
-import tempfile
-from dataclasses import dataclass, field
-from typing import Any
-from urllib.parse import unquote, urlparse
+from dataclasses import dataclass
 
 import numpy as np
-import requests
 import torch
 from PIL import Image
 
-from ...utils import is_av_available, load_image
-from ...utils.constants import DIFFUSERS_REQUEST_TIMEOUT
 from .packing import (
     _ROPE_FRAME_RESCALE,
     _ROPE_FRAMES_PER_LATENT,
     MINIMAX_H3_AUDIO_CHANNELS,
     MINIMAX_H3_AUDIO_TAG,
-    MINIMAX_H3_CANVAS_MULTIPLE,
     MINIMAX_H3_FPS,
     MINIMAX_H3_TEXT_TAG,
     MINIMAX_H3_VIDEO_TAG,
@@ -83,302 +75,121 @@
 MINIMAX_H3_MAX_REFERENCES = 12
 
 
-@contextlib.contextmanager
-def _local_media_file(media):
-    r"""The reference media as a local file: a URL is downloaded to a temporary file, removed on the way out."""
-    path = str(media)
-    if not path.startswith(("http://", "https://")):
-        if not os.path.isfile(path):
-            raise ValueError(
-                f"Incorrect path or URL. URLs must start with `http://` or `https://`, and {path} is not a valid path."
-            )
-        yield path
-        return
-
-    response = requests.get(path, stream=True, timeout=DIFFUSERS_REQUEST_TIMEOUT)
-    if response.status_code != 200:
-        raise ValueError(f"Failed to download {path}. Status code: {response.status_code}")
-    suffix = os.path.splitext(os.path.basename(unquote(urlparse(path).path)))[1]
-    download = tempfile.NamedTemporaryFile(suffix=suffix, delete=False)
-    try:
-        with download as file:
-            for chunk in response.iter_content(chunk_size=8192):
-                file.write(chunk)
-        yield download.name
-    finally:
-        os.remove(download.name)
-
-
-def _import_av():
-    r"""PyAV, the soft dependency a reference decodes a media file with."""
-    if not is_av_available():
-        raise ImportError(
-            "Decoding a MiniMax-H3 reference from a file needs PyAV. You can install it with `pip install av`, or "
-            "pass the decoded media itself: frames and the `fps` they carry for a video, a `(channels, num_samples)` "
-            "waveform and its `sample_rate` for audio."
-        )
-
-    import av
-
-    return av
-
-
-def _decode_reference_soundtrack(av, container, stream) -> tuple[torch.Tensor, int]:
+@dataclass
+class MiniMaxH3Reference:
     r"""
-    An audio stream's samples as a `(channels, num_samples)` float32 waveform, at the rate the container carries them.
-
-    Args:
-        av (`module`): PyAV.
-        container (`av.container.InputContainer`): The open container.
-        stream (`av.audio.stream.AudioStream`): The stream to decode.
+    Base class of the three references a [`MiniMaxH3Ref2VABlocks`] request conditions on:
+    [`MiniMaxH3ImageReference`], [`MiniMaxH3VideoReference`] and [`MiniMaxH3AudioReference`].
 
-    Returns:
-        `tuple[torch.Tensor, int]`: the waveform and its sample rate.
-    """
-    sample_rate = int(stream.codec_context.sample_rate)
-    # Planar float is a format conversion only: the sample rate and the channel layout stay the container's own, and a
-    # mono soundtrack is upmixed later, by `prepare_reference_waveform`.
-    resampler = av.audio.resampler.AudioResampler(format="fltp", layout=stream.layout, rate=sample_rate)
-    chunks = []
-    for frame in container.decode(stream):
-        chunks += [torch.from_numpy(resampled.to_ndarray()) for resampled in resampler.resample(frame)]
-    # Whatever the resampler is still holding.
-    chunks += [torch.from_numpy(resampled.to_ndarray()) for resampled in resampler.resample(None)]
-    return torch.cat(chunks, dim=-1).to(torch.float32), sample_rate
-
-
-def decode_reference_video(media) -> tuple[np.ndarray, float, tuple[torch.Tensor, int] | None]:
-    r"""
-    Decode a reference video file into `uint8` RGB frames, at the resolution and the frame rate it carries.
+    References are passed to the blocks as a list, **in the order the model should read them**: the order labels them
+    in the prompt presentation and lays them out on the shared rotary clock, so a different order is a different
+    request.
 
-    Args:
-        media (`str` or `os.PathLike`): Path or URL of the video.
+    Every reference holds in-memory media, and the rate that media carries where there is one — MiniMax-H3 resamples a
+    reference onto its own 24 fps and onto the audio VAE's sample rate, so a rate lost on the way in is a request
+    conditioned at the wrong speed. Decoding a file is the caller's job:
+    [`~modular_pipelines.minimax_h3.decode_reference_video`] and
+    [`~modular_pipelines.minimax_h3.decode_reference_audio`] do it along with the rates, and
+    [`MiniMaxH3Ref2VALoadReferencesStep`] wraps them in a block.
 
-    Returns:
-        `tuple[np.ndarray, float, tuple[torch.Tensor, int]]`: the `(num_frames, height, width, 3)` frames, the frame
-        rate the container reports, and its soundtrack with that soundtrack's own sample rate, `None` when the
-        container carries no audio stream.
-    """
-    av = _import_av()
-    with _local_media_file(media) as path, av.open(path) as container:
-        stream = container.streams.video[0]
-        frames, rotation = [], 0.0
-        for frame in container.decode(stream):
-            # The display matrix rotation belongs to the stream, and PyAV surfaces it on every frame of it.
-            rotation = frame.rotation
-            frames.append(frame.to_ndarray(format="rgb24"))
-        frame_rate = float(stream.average_rate or stream.guessed_rate)
-        soundtrack = None
-        if container.streams.audio:
-            # Decoding the frames drained the container, so the soundtrack is read in a second pass over it.
-            container.seek(0)
-            soundtrack = _decode_reference_soundtrack(av, container, container.streams.audio[0])
-
-    if not frames:
-        raise ValueError(f"No video frames to decode in {media}.")
-    frames = np.stack(frames)
-    # `ffmpeg` displays a frame upright by undoing the counterclockwise rotation the display matrix carries, which is
-    # what this reproduces, snapped to the nearest quarter turn. A non-square pixel aspect ratio is left alone: the
-    # reference implementation resolved a reference's canvas from its *display* geometry, so a stream that carries a
-    # sample aspect ratio is conditioned on at the wrong shape, and correcting it is untested guesswork here.
-    turns = round(rotation / 90.0) % 4
-    if turns:
-        frames = np.ascontiguousarray(np.rot90(frames, k=-turns, axes=(1, 2)))
-    return frames, frame_rate, soundtrack
-
-
-def decode_reference_audio(media) -> tuple[torch.Tensor, int]:
-    r"""
-    Decode a reference audio file into a waveform, at the sample rate it carries.
+    ```py
+    >>> import numpy as np
+    >>> from diffusers.utils import load_image
+    >>> from diffusers.modular_pipelines.minimax_h3 import (
+    ...     MiniMaxH3AudioReference,
+    ...     MiniMaxH3ImageReference,
+    ...     MiniMaxH3VideoReference,
+    ...     decode_reference_audio,
+    ...     decode_reference_video,
+    ... )
 
-    Args:
-        media (`str` or `os.PathLike`): Path or URL of the audio, or of a video whose soundtrack is taken.
+    >>> references = [
+    ...     MiniMaxH3ImageReference(image=load_image("subject.png")),
+    ...     decode_reference_video("motion_ref.mp4"),  # frames, their `fps`, and the soundtrack
+    ...     decode_reference_audio("voice.wav"),  # waveform and its `sample_rate`
+    ... ]
 
-    Returns:
-        `tuple[torch.Tensor, int]`: the `(channels, num_samples)` float32 waveform and its sample rate.
+    >>> # Media a request produced itself declares the rate it was produced at.
+    >>> frames = np.zeros((30, 480, 854, 3), dtype="uint8")
+    >>> reference = MiniMaxH3VideoReference(frames=frames, fps=30.0)
+    ```
     """
-    av = _import_av()
-    with _local_media_file(media) as path, av.open(path) as container:
-        if not container.streams.audio:
-            raise ValueError(f"No audio stream to decode in {media}.")
-        return _decode_reference_soundtrack(av, container, container.streams.audio[0])
 
 
 @dataclass
-class MiniMaxH3Reference:
+class MiniMaxH3ImageReference(MiniMaxH3Reference):
     r"""
-    One omni-reference of a [`MiniMaxH3Ref2VABlocks`] request: an image, a video, or an audio clip.
+    A subject, style or scene reference: at most 9 per request.
 
-    A reference carries exactly one medium — plus, for a video, the `audio` of its own soundtrack, which is then
-    conditioned on as that reference's own. References are passed to the blocks as a list, **in the order the model
-    should read them**: the order labels them in the prompt presentation and lays them out on the shared rotary clock,
-    so a different order is a different request.
-
-    Every medium may be a path or a URL as well as in-memory media. A path is decoded here, when the reference is
-    built, and with it the rates that come with it: no MiniMax-H3 block opens a media file. Decoding a video or an
-    audio file needs [PyAV](https://github.com/PyAV-Org/PyAV).
+    Attributes:
+        image (`PIL.Image.Image`):
+            The reference image. It never binds the generated geometry — it is encoded at a 2048 pixel short edge of
+            its own aspect ratio, whatever canvas the request generates at.
+    """
 
-    ```py
-    >>> from diffusers.modular_pipelines.minimax_h3 import MiniMaxH3Reference
+    image: Image.Image
 
-    >>> # A file or a URL is decoded on the spot, at the rate the container reports.
-    >>> references = [
-    ...     MiniMaxH3Reference(video="motion_ref.mp4"),
-    ...     MiniMaxH3Reference(image="subject.png"),
-    ...     MiniMaxH3Reference(audio="voice.wav"),
-    ... ]
+    kind = "image"
+    has_audio = False
 
-    >>> # In-memory media instead carries the rates it was produced at, MiniMax-H3's own by default.
-    >>> import numpy as np
 
-    >>> frames = np.zeros((30, 480, 854, 3), dtype="uint8")
-    >>> reference = MiniMaxH3Reference(video=frames, fps=30.0)
-    ```
+@dataclass
+class MiniMaxH3VideoReference(MiniMaxH3Reference):
+    r"""
+    A motion and camera reference: at most 3 per request, conditioned on together with its own soundtrack.
 
     Attributes:
-        image (`str`, `os.PathLike`, `PIL.Image.Image`, `np.ndarray` or `torch.Tensor`, *optional*):
-            A subject, style or scene reference: at most 9 per request. A path or a URL, which is read with
-            [`~utils.load_image`], a `(height, width, 3)` array or a `(3, height, width)` tensor, `uint8` or floating
-            point over `[0, 1]`. Mutually exclusive with `video`.
-        video (`str`, `os.PathLike`, `list[PIL.Image.Image]`, `np.ndarray` or `torch.Tensor`, *optional*):
-            A motion and camera reference: at most 3 per request. A path or a URL, which PyAV decodes into frames, a
-            list of images, a `(num_frames, height, width, 3)` array or a `(num_frames, 3, height, width)` tensor.
-            Mutually exclusive with `image`. A decoded file brings its soundtrack along, as this reference's own, so
-            conditioning on a file's motion alone means decoding its frames first, with [`~utils.load_video`].
-        fps (`float`, *optional*):
-            The frame rate `video` carries its frames at, which is what places its vision blocks on the conditioner's
-            2 fps grid. Left out, it is the rate the container reports for a decoded file and MiniMax-H3's own 24 fps
-            for in-memory frames, and `fps` holds that resolved rate once the reference is built. Passing it wins over
-            both, which is only needed when a container's metadata is wrong. MiniMax-H3's clock is 24 fps, so any other
-            rate is resampled onto it by dropping and duplicating whole frames.
-        audio (`str`, `os.PathLike` or `torch.Tensor` of shape `(channels, num_samples)`, *optional*):
-            A voice or music reference, mono or stereo: at most 3 per request, and never on its own — an audio
-            reference has to be paired with at least one image or video reference. A path or a URL, which PyAV decodes
-            into a waveform, or the waveform itself. Passed next to `video`, it is that video's soundtrack instead of a
-            reference of its own. An audio reference never reaches the conditioner and is encoded by the audio VAE
-            alone.
+        frames (`list[PIL.Image.Image]`, `np.ndarray` or `torch.Tensor`):
+            The reference frames: a list of images, a `(num_frames, height, width, 3)` array or a `(num_frames, 3,
+            height, width)` tensor, `uint8` or floating point over `[0, 1]`.
+        fps (`float`, *optional*, defaults to 24.0):
+            The frame rate `frames` carries, which is what places the reference's vision blocks on the conditioner's 2
+            fps grid. MiniMax-H3's own clock is 24 fps, so any other rate is resampled onto it by dropping and
+            duplicating whole frames — which makes this the field to get right when the frames came from a file.
+        audio (`torch.Tensor` of shape `(channels, num_samples)`, *optional*):
+            This video's soundtrack, mono or stereo, conditioned on as the reference's own rather than as a reference
+            of its own. Left out, the reference conditions on motion alone.
         sample_rate (`int`, *optional*):
-            The rate `audio` carries its samples at. Left out, it is the rate the container reports for a decoded file,
-            and for an in-memory waveform the audio VAE's own, which leaves the samples untouched. Passing it wins over
-            both, which is only needed when a container's metadata is wrong. Any other rate is resampled onto the audio
-            VAE's own.
+            The rate `audio` carries its samples at. Left out, it is the audio VAE's own, which leaves the samples
+            untouched; any other rate is resampled onto it.
     """
 
-    image: str | os.PathLike | Image.Image | np.ndarray | torch.Tensor | None = None
-    video: str | os.PathLike | list[Image.Image] | np.ndarray | torch.Tensor | None = None
+    frames: list[Image.Image] | np.ndarray | torch.Tensor
     fps: float | None = None
-    audio: str | os.PathLike | torch.Tensor | None = None
+    audio: torch.Tensor | None = None
     sample_rate: int | None = None
 
-    def __post_init__(self):
-        # A video reference conditions on its soundtrack too, so `audio` is a second medium of a video reference.
-        media = [name for name in ("image", "video", "audio") if getattr(self, name) is not None]
-        if media not in (["image"], ["video"], ["audio"], ["video", "audio"]):
-            raise ValueError(
-                "A `MiniMaxH3Reference` must carry exactly one of `image`, `video` or `audio` — plus, for a video, "
-                f"the `audio` of its soundtrack — got {media if media else 'none of them'}."
-            )
+    kind = "video"
 
-        # A path is decoded on the spot, so that the blocks only ever see in-memory media. A rate the request
-        # passed explicitly wins over the one the container reports, for a container whose metadata is wrong.
-        if isinstance(self.image, (str, os.PathLike)):
-            self.image = load_image(str(self.image))
-        if isinstance(self.video, (str, os.PathLike)):
-            frames, frame_rate, soundtrack = decode_reference_video(self.video)
-            self.video = frames
-            self.fps = frame_rate if self.fps is None else self.fps
-            if soundtrack is not None and self.audio is None:
-                self.audio, soundtrack_sample_rate = soundtrack
-                self.sample_rate = soundtrack_sample_rate if self.sample_rate is None else self.sample_rate
-        if isinstance(self.audio, (str, os.PathLike)):
-            self.audio, sample_rate = decode_reference_audio(self.audio)
-            self.sample_rate = sample_rate if self.sample_rate is None else self.sample_rate
+    def __post_init__(self):
         if self.fps is None:
             self.fps = float(MINIMAX_H3_FPS)
 
-    @property
-    def kind(self) -> str:
-        r"""The modality this reference is packed as: `"image"`, `"video"` or `"audio"`."""
-        if self.image is not None:
-            return "image"
-        return "video" if self.video is not None else "audio"
-
     @property
     def has_audio(self) -> bool:
-        r"""Whether this reference contributes audio rows, i.e. whether it carries a waveform."""
+        r"""Whether this reference contributes audio rows, i.e. whether it carries a soundtrack."""
         return self.audio is not None
 
 
-def reference_kind(index: int, entry: Any) -> str:
-    r"""
-    The modality of one `references` entry, which the [`MiniMaxH3Reference`] validated at construction.
-    """
-    if not isinstance(entry, MiniMaxH3Reference):
-        raise ValueError(
-            f"`references[{index}]` must be a [`MiniMaxH3Reference`], got {type(entry)}. A request is built from "
-            "the dataclass: `MiniMaxH3Reference(image=...)`, `MiniMaxH3Reference(video=...)` or "
-            "`MiniMaxH3Reference(audio=...)`."
-        )
-    # A reference decodes a path when it is built, so the blocks only ever see in-memory media.
-    for name in ("image", "video", "audio"):
-        if isinstance(getattr(entry, name), (str, os.PathLike)):
-            raise ValueError(
-                f"`references[{index}].{name}` is a path. MiniMax-H3 blocks never open media files: rebuild "
-                "the reference, which decodes a path as it is built."
-            )
-    return entry.kind
-
-
 @dataclass
-class MiniMaxH3PreparedReference:
+class MiniMaxH3AudioReference(MiniMaxH3Reference):
     r"""
-    One `ref2va` reference prepared for packing, in packed order.
-
-    A [`MiniMaxH3Reference`] is resolved in three passes: the blocks read the modality off the request (`kind`,
-    `has_audio`), prepares the pixels or samples (`image`, `frames`, `waveform`), and finally encodes them, which is
-    what fixes the latent geometry (`num_latent_frames`, `latent_height`, `latent_width`, `num_audio_latents`) the
-    packed layout is built from.
+    A voice or music reference: at most 3 per request, and never on its own — an audio reference has to be paired with
+    at least one image or video reference. It never reaches the conditioner and is encoded by the audio VAE alone.
 
     Attributes:
-        kind (`str`):
-            `"image"`, `"video"` or `"audio"`.
-        has_audio (`bool`):
-            Whether this reference contributes audio rows. Always `True` for `"audio"`, and `True` for a `"video"` the
-            request passed a soundtrack with.
-        image (`PIL.Image.Image`):
-            The prepared reference image.
-        frames (`np.ndarray` of shape `(num_frames, height, width, 3)`):
-            The prepared reference video, `uint8` RGB at 24 fps.
-        waveform (`torch.Tensor` of shape `(2, num_samples)`):
-            The prepared soundtrack, stereo at the audio VAE's sample rate.
-        block_timestamps (`list[float]`):
-            The timestamp of every vision block the conditioner sees for a video reference.
-        num_latent_frames (`int`), latent_height (`int`), latent_width (`int`):
-            Latent geometry of the visual rows.
-        num_audio_latents (`int`):
-            Number of audio latents per channel.
+        audio (`torch.Tensor` of shape `(channels, num_samples)`):
+            The reference waveform, mono or stereo.
+        sample_rate (`int`, *optional*):
+            The rate `audio` carries its samples at. Left out, it is the audio VAE's own, which leaves the samples
+            untouched; any other rate is resampled onto it.
     """
 
-    kind: str
-    has_audio: bool = False
-    image: Any = None
-    frames: Any = None
-    waveform: torch.Tensor | None = None
-    block_timestamps: list[float] = field(default_factory=list)
-    num_latent_frames: int = 1
-    latent_height: int = 0
-    latent_width: int = 0
-    num_audio_latents: int = 0
-
-    @property
-    def num_video_rows(self) -> int:
-        r"""The number of packed video rows, for the `(1, 2, 2)` patch MiniMax-H3 packs video latents with."""
-        return self.num_latent_frames * (self.latent_height // 2) * (self.latent_width // 2)
+    audio: torch.Tensor
+    sample_rate: int | None = None
 
-    @property
-    def num_audio_rows(self) -> int:
-        r"""The number of packed audio rows: one per latent and per stereo channel."""
-        return self.num_audio_latents * MINIMAX_H3_AUDIO_CHANNELS
+    kind = "audio"
+    has_audio = True
 
 
 def _temporal_position_span(num_latent_frames: int) -> float:
@@ -431,7 +242,9 @@ def _fill_audio_positions(
 
 def build_ref2va_packed_sequence(
     text_token_tags: torch.Tensor,
-    references: list[MiniMaxH3PreparedReference],
+    references: list[MiniMaxH3Reference],
+    condition_latents: list[torch.Tensor],
+    audio_condition_latents: list[torch.Tensor],
     num_latent_frames: int,
     latent_height: int,
     latent_width: int,
@@ -445,8 +258,13 @@ def build_ref2va_packed_sequence(
         text_token_tags (`torch.Tensor` of shape `(num_text_tokens,)`):
             The modality tag of every text row. Text is tagged `1`, except for the rows of a reference's vision block,
             which MiniMax-H3 tags `0` (video).
-        references (`list[MiniMaxH3PreparedReference]`):
-            The references, in packed order, with their latent geometry already resolved.
+        references (`list[MiniMaxH3Reference]`):
+            The references, in packed order. Only their modality is read here; the geometry comes from the latents.
+        condition_latents (`list[torch.Tensor]`):
+            One `(1, channels, num_latent_frames, latent_height, latent_width)` tensor per image and video reference,
+            in packed order, as [`MiniMaxH3Ref2VAReferenceEncoderStep`] produced them.
+        audio_condition_latents (`list[torch.Tensor]`):
+            One `(num_audio_latents * 2, audio_latent_channels)` tensor per audio-bearing reference, in packed order.
         num_latent_frames (`int`): Number of target latent frames.
         latent_height (`int`): Target latent height.
         latent_width (`int`): Target latent width.
@@ -461,8 +279,17 @@ def build_ref2va_packed_sequence(
     num_text_tokens = text_token_tags.shape[0]
     num_target_video_rows = num_latent_frames * (latent_height // patch_h) * (latent_width // patch_w)
     num_target_audio_rows = num_audio_latents * MINIMAX_H3_AUDIO_CHANNELS
-    num_reference_video_rows = sum(reference.num_video_rows for reference in references if reference.kind != "audio")
-    num_reference_audio_rows = sum(reference.num_audio_rows for reference in references)
+
+    # The geometry of every reference block is the shape of what the encoder produced for it, so the two can never
+    # disagree. Both lists are in packed order but skip the references they do not apply to, so they are consumed as
+    # iterators alongside the reference list rather than indexed by it.
+    visual_geometry = iter(tuple(latents.shape[2:5]) for latents in condition_latents)
+    audio_row_counts = iter(rows.shape[0] for rows in audio_condition_latents)
+    num_reference_video_rows = sum(
+        frames * (height // patch_h) * (width // patch_w)
+        for frames, height, width in (tuple(latents.shape[2:5]) for latents in condition_latents)
+    )
+    num_reference_audio_rows = sum(rows.shape[0] for rows in audio_condition_latents)
     sequence_length = (
         num_text_tokens
         + num_reference_video_rows
@@ -482,39 +309,47 @@ def build_ref2va_packed_sequence(
     rotary_time = float(num_text_tokens)
     for reference in references:
         if reference.kind == "image":
-            rows = slice(cursor, cursor + reference.num_video_rows)
+            num_latent_frames_, reference_height, reference_width = next(visual_geometry)
+            num_video_rows = (
+                num_latent_frames_ * (reference_height // patch_h) * (reference_width // patch_w)
+            )
+            rows = slice(cursor, cursor + num_video_rows)
             cursor = rows.stop
             video_indices.append(torch.arange(rows.start, rows.stop))
-            frame_grid, _ = _frame_position_grid(reference.latent_height, reference.latent_width, patch_h, patch_w)
+            frame_grid, _ = _frame_position_grid(reference_height, reference_width, patch_h, patch_w)
             position_ids[rows, 0] = rotary_time
             position_ids[rows, 1:] = frame_grid
             # An image is a single frame and takes a single integer rotary slot, not a latent frame's 5/3 units.
             rotary_time += 1.0
         elif reference.kind == "audio":
-            rows = slice(cursor, cursor + reference.num_audio_rows)
+            num_audio_rows = next(audio_row_counts)
+            reference_audio_latents = num_audio_rows // MINIMAX_H3_AUDIO_CHANNELS
+            rows = slice(cursor, cursor + num_audio_rows)
             cursor = rows.stop
             audio_indices.append(torch.arange(rows.start, rows.stop))
-            _fill_audio_positions(position_ids, rows, reference.num_audio_latents, rotary_time, target_width_grid)
-            rotary_time += float(reference.num_audio_latents)
+            _fill_audio_positions(position_ids, rows, reference_audio_latents, rotary_time, target_width_grid)
+            rotary_time += float(reference_audio_latents)
         elif reference.kind == "video":
             # A video reference's soundtrack rows are packed immediately before its video rows and share their
             # origin, so the two are rotary-aligned exactly as the generated audio and video are.
-            audio_rows = slice(cursor, cursor + reference.num_audio_rows)
-            video_rows = slice(audio_rows.stop, audio_rows.stop + reference.num_video_rows)
+            num_audio_rows = next(audio_row_counts) if reference.has_audio else 0
+            reference_audio_latents = num_audio_rows // MINIMAX_H3_AUDIO_CHANNELS
+            num_latent_frames_, reference_height, reference_width = next(visual_geometry)
+            num_video_rows = (
+                num_latent_frames_ * (reference_height // patch_h) * (reference_width // patch_w)
+            )
+            audio_rows = slice(cursor, cursor + num_audio_rows)
+            video_rows = slice(audio_rows.stop, audio_rows.stop + num_video_rows)
             cursor = video_rows.stop
             audio_indices.append(torch.arange(audio_rows.start, audio_rows.stop))
             video_indices.append(torch.arange(video_rows.start, video_rows.stop))
 
-            frame_grid, width_grid = _frame_position_grid(
-                reference.latent_height, reference.latent_width, patch_h, patch_w
-            )
-            _fill_audio_positions(position_ids, audio_rows, reference.num_audio_latents, rotary_time, width_grid)
-            frame_time = _temporal_position_grid(reference.num_latent_frames, rotary_time)
+            frame_grid, width_grid = _frame_position_grid(reference_height, reference_width, patch_h, patch_w)
+            _fill_audio_positions(position_ids, audio_rows, reference_audio_latents, rotary_time, width_grid)
+            frame_time = _temporal_position_grid(num_latent_frames_, rotary_time)
             position_ids[video_rows, 0] = frame_time.repeat_interleave(frame_grid.shape[0])
-            position_ids[video_rows, 1:] = frame_grid.repeat(reference.num_latent_frames, 1)
-            rotary_time += max(
-                float(reference.num_audio_latents), _temporal_position_span(reference.num_latent_frames)
-            )
+            position_ids[video_rows, 1:] = frame_grid.repeat(num_latent_frames_, 1)
+            rotary_time += max(float(reference_audio_latents), _temporal_position_span(num_latent_frames_))
         else:
             raise ValueError(f"A reference must be an 'image', a 'video' or an 'audio', got {reference.kind!r}.")
 
@@ -548,14 +383,16 @@ def build_ref2va_packed_sequence(
     )
 
 
-def resolve_reference_image_size(width: int, height: int) -> tuple[int, int]:
+def resolve_reference_image_size(width: int, height: int, canvas_multiple: int) -> tuple[int, int]:
     r"""
-    Resolve the resolution a reference image is encoded at: a 2048 pixel short edge, both axes rounded to a multiple
-    of 32. Upscaling is intended, and unlike the target canvas there is no area cap.
+    Resolve the resolution a reference image is encoded at: a 2048 pixel short edge, both axes rounded to
+    `canvas_multiple`. Upscaling is intended, and unlike the target canvas there is no area cap.
 
     Args:
         width (`int`): Width of the source image.
         height (`int`): Height of the source image.
+        canvas_multiple (`int`):
+            What both axes round to, i.e. `components.canvas_multiple` — 32 for the released checkpoint.
 
     Returns:
         `tuple[int, int]`: the `(height, width)` the reference is resized to.
@@ -566,7 +403,7 @@ def resolve_reference_image_size(width: int, height: int) -> tuple[int, int]:
         raise ValueError(f"A reference image must be within 1:4 and 4:1, got {width}x{height}.")
 
     scale = MINIMAX_H3_REFERENCE_IMAGE_SHORT_EDGE / min(width, height)
-    multiple = MINIMAX_H3_CANVAS_MULTIPLE
+    multiple = canvas_multiple
     return (
         max(multiple, round(height * scale / multiple) * multiple),
         max(multiple, round(width * scale / multiple) * multiple),
@@ -648,7 +485,7 @@ def resample_reference_frames(frames: np.ndarray, fps: float) -> np.ndarray:
     return np.repeat(frames, np.diff(slots, append=math.floor(frames.shape[0] * scale + 0.5)), axis=0)
 
 
-def prepare_reference_frames(frames: np.ndarray, num_frames: int) -> np.ndarray:
+def prepare_reference_frames(frames: np.ndarray, num_frames: int, canvas_multiple: int) -> np.ndarray:
     r"""
     Put a reference video onto the canvas its own aspect ratio resolves to, and cap it at the generated frame count.
 
@@ -661,6 +498,8 @@ def prepare_reference_frames(frames: np.ndarray, num_frames: int) -> np.ndarray:
         frames (`np.ndarray` of shape `(num_frames, height, width, 3)`):
             The reference video, `uint8` RGB at 24 fps, as returned by [`resample_reference_frames`].
         num_frames (`int`): The frame count the reference is truncated to, i.e. the target's own frame count.
+        canvas_multiple (`int`):
+            What both axes of its own canvas round to, i.e. `components.canvas_multiple`.
 
     Returns:
         `np.ndarray` of shape `(num_frames, height, width, 3)`: The prepared reference.
@@ -670,7 +509,7 @@ def prepare_reference_frames(frames: np.ndarray, num_frames: int) -> np.ndarray:
             f"A reference video must be `(num_frames, height, width, 3)` RGB frames, got {tuple(frames.shape)}."
         )
     frames = frames[:num_frames]
-    height, width = resolve_canvas_size(frames.shape[2], frames.shape[1])
+    height, width = resolve_canvas_size(frames.shape[2], frames.shape[1], canvas_multiple)
     if frames.shape[1:3] == (height, width):
         return frames
     return np.stack(
@@ -753,9 +592,10 @@ def prepare_reference_waveform(
 def build_ref2va_presentation(
     tokenizer,
     prompt: str,
-    references: list[MiniMaxH3PreparedReference],
+    references: list[MiniMaxH3Reference],
     image_token_counts: list[int],
     video_block_token_counts: list[int],
+    video_block_timestamps: list[list[float]],
 ) -> tuple[list[int], list[int]]:
     r"""
     Tokenize MiniMax-H3's presentation of a `ref2va` request.
@@ -769,9 +609,10 @@ def build_ref2va_presentation(
     Args:
         tokenizer (`Qwen2TokenizerFast`): Tokenizer of the conditioner.
         prompt (`str`): The prompt, appended verbatim.
-        references (`list[MiniMaxH3PreparedReference]`): The prepared references, in packed order.
+        references (`list[MiniMaxH3Reference]`): The normalized references, in packed order.
         image_token_counts (`list[int]`): Number of vision tokens of every image reference's block.
         video_block_token_counts (`list[int]`): Number of vision tokens per block of every video reference.
+        video_block_timestamps (`list[list[float]]`): The timestamp of every vision block, per video reference.
 
     Returns:
         `tuple[list[int], list[int]]`: the token ids and their modality tags. A vision block is tagged `0` (video) and
@@ -808,7 +649,7 @@ def emit(segment: tuple[list[int], list[int]]) -> None:
         elif reference.kind == "video":
             counts["video"] += 1
             emit(text(f"<Video {counts['video']}>: "))
-            for timestamp in reference.block_timestamps:
+            for timestamp in video_block_timestamps[counts["video"] - 1]:
                 # `"{:.1f}"` rounds half to even, so the mean of a 2 fps pair renders as "<0.2 seconds>".
                 emit(text(f"<{timestamp:.1f} seconds>"))
                 emit(vision("<|video_pad|>", video_block_token_counts[counts["video"] - 1]))
diff --git a/src/diffusers/modular_pipelines/minimax_h3/reference_loading.py b/src/diffusers/modular_pipelines/minimax_h3/reference_loading.py
new file mode 100644
index 000000000000..d8adc58bf947
--- /dev/null
+++ b/src/diffusers/modular_pipelines/minimax_h3/reference_loading.py
@@ -0,0 +1,272 @@
+# Copyright 2026 The MiniMax and HuggingFace Teams. All rights reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+r"""
+Reading `ref2va` references off the filesystem.
+
+MiniMax-H3's blocks take references as in-memory media, and the three reference dataclasses take nothing else: a
+[`MiniMaxH3VideoReference`] carries decoded frames and the `fps` they were decoded at, a [`MiniMaxH3AudioReference`] a
+waveform and its sample rate. Turning a path into one of those is the caller's job, the same way it is for every other
+pipeline in the library.
+
+This module is the convenience for doing it: [`decode_reference_video`] and [`decode_reference_audio`] decode a file
+or a URL along with the rates it carries, and [`MiniMaxH3Ref2VALoadReferencesStep`] wraps them in a block that can be
+put in front of [`MiniMaxH3Ref2VABlocks`]. It is deliberately *not* one of that blockset's own steps — decoding media
+is not part of generating video, and a request that already holds its media should not pay for the machinery.
+
+The rates are the reason to prefer these over a bare `load_video`: MiniMax-H3 resamples a reference onto its own 24
+fps, so a video whose real rate is lost on the way in is conditioned on at the wrong speed, silently.
+"""
+
+import contextlib
+import os
+import tempfile
+from urllib.parse import unquote, urlparse
+
+import numpy as np
+import requests
+import torch
+
+from ...utils import is_av_available, load_image, logging
+from ...utils.constants import DIFFUSERS_REQUEST_TIMEOUT
+from ..modular_pipeline import ModularPipelineBlocks, PipelineState
+from ..modular_pipeline_utils import InputParam, OutputParam
+from .modular_pipeline import MiniMaxH3Ref2VAModularPipeline
+from .packing_ref2va import (
+    MiniMaxH3AudioReference,
+    MiniMaxH3ImageReference,
+    MiniMaxH3Reference,
+    MiniMaxH3VideoReference,
+)
+
+
+logger = logging.get_logger(__name__)  # pylint: disable=invalid-name
+
+
+@contextlib.contextmanager
+def _local_media_file(media):
+    r"""The reference media as a local file: a URL is downloaded to a temporary file, removed on the way out."""
+    path = str(media)
+    if not path.startswith(("http://", "https://")):
+        if not os.path.isfile(path):
+            raise ValueError(
+                f"Incorrect path or URL. URLs must start with `http://` or `https://`, and {path} is not a valid path."
+            )
+        yield path
+        return
+
+    response = requests.get(path, stream=True, timeout=DIFFUSERS_REQUEST_TIMEOUT)
+    if response.status_code != 200:
+        raise ValueError(f"Failed to download {path}. Status code: {response.status_code}")
+    suffix = os.path.splitext(os.path.basename(unquote(urlparse(path).path)))[1]
+    download = tempfile.NamedTemporaryFile(suffix=suffix, delete=False)
+    try:
+        with download as file:
+            for chunk in response.iter_content(chunk_size=8192):
+                file.write(chunk)
+        yield download.name
+    finally:
+        os.remove(download.name)
+
+
+def _import_av():
+    r"""PyAV, the soft dependency a media file is decoded with."""
+    if not is_av_available():
+        raise ImportError(
+            "Decoding a MiniMax-H3 reference from a file needs PyAV. You can install it with `pip install av`, or "
+            "build the reference from decoded media itself: frames and the `fps` they carry for a video, a "
+            "`(channels, num_samples)` waveform and its `sample_rate` for audio."
+        )
+
+    import av
+
+    return av
+
+
+def _decode_reference_soundtrack(av, container, stream) -> tuple[torch.Tensor, int]:
+    r"""
+    An audio stream's samples as a `(channels, num_samples)` float32 waveform, at the rate the container carries them.
+
+    Args:
+        av (`module`): PyAV.
+        container (`av.container.InputContainer`): The open container.
+        stream (`av.audio.stream.AudioStream`): The stream to decode.
+
+    Returns:
+        `tuple[torch.Tensor, int]`: the waveform and its sample rate.
+    """
+    sample_rate = int(stream.codec_context.sample_rate)
+    # Planar float is a format conversion only: the sample rate and the channel layout stay the container's own, and a
+    # mono soundtrack is upmixed later, by `prepare_reference_waveform`.
+    resampler = av.audio.resampler.AudioResampler(format="fltp", layout=stream.layout, rate=sample_rate)
+    chunks = []
+    for frame in container.decode(stream):
+        chunks += [torch.from_numpy(resampled.to_ndarray()) for resampled in resampler.resample(frame)]
+    # Whatever the resampler is still holding.
+    chunks += [torch.from_numpy(resampled.to_ndarray()) for resampled in resampler.resample(None)]
+    return torch.cat(chunks, dim=-1).to(torch.float32), sample_rate
+
+
+def decode_reference_video(media) -> MiniMaxH3VideoReference:
+    r"""
+    Decode a video file into a [`MiniMaxH3VideoReference`], at the resolution, the frame rate and the soundtrack it
+    carries.
+
+    The rates land on the reference, which is the point of decoding this way rather than with [`~utils.load_video`]:
+    MiniMax-H3 resamples a reference onto its own 24 fps, so a frame rate lost on the way in is a request conditioned
+    at the wrong speed, with nothing to raise about it. A container whose metadata is wrong is corrected by overriding
+    `fps` or `sample_rate` on the returned reference.
+
+    Needs [PyAV](https://github.com/PyAV-Org/PyAV).
+
+    Args:
+        media (`str` or `os.PathLike`): Path or URL of the video.
+
+    Returns:
+        [`MiniMaxH3VideoReference`]: the `(num_frames, height, width, 3)` `uint8` frames at the frame rate the
+        container reports, carrying its soundtrack and that soundtrack's own sample rate when it has an audio stream.
+    """
+    av = _import_av()
+    with _local_media_file(media) as path, av.open(path) as container:
+        stream = container.streams.video[0]
+        frames, rotation = [], 0.0
+        for frame in container.decode(stream):
+            # The display matrix rotation belongs to the stream, and PyAV surfaces it on every frame of it.
+            rotation = frame.rotation
+            frames.append(frame.to_ndarray(format="rgb24"))
+        frame_rate = float(stream.average_rate or stream.guessed_rate)
+        soundtrack = None
+        if container.streams.audio:
+            # Decoding the frames drained the container, so the soundtrack is read in a second pass over it.
+            container.seek(0)
+            soundtrack = _decode_reference_soundtrack(av, container, container.streams.audio[0])
+
+    if not frames:
+        raise ValueError(f"No video frames to decode in {media}.")
+    frames = np.stack(frames)
+    # `ffmpeg` displays a frame upright by undoing the counterclockwise rotation the display matrix carries, which is
+    # what this reproduces, snapped to the nearest quarter turn. A non-square pixel aspect ratio is left alone: the
+    # reference implementation resolved a reference's canvas from its *display* geometry, so a stream that carries a
+    # sample aspect ratio is conditioned on at the wrong shape, and correcting it is untested guesswork here.
+    turns = round(rotation / 90.0) % 4
+    if turns:
+        frames = np.ascontiguousarray(np.rot90(frames, k=-turns, axes=(1, 2)))
+    waveform, sample_rate = soundtrack if soundtrack is not None else (None, None)
+    return MiniMaxH3VideoReference(frames=frames, fps=frame_rate, audio=waveform, sample_rate=sample_rate)
+
+
+def decode_reference_audio(media) -> MiniMaxH3AudioReference:
+    r"""
+    Decode an audio file into a [`MiniMaxH3AudioReference`], at the sample rate it carries.
+
+    Needs [PyAV](https://github.com/PyAV-Org/PyAV).
+
+    Args:
+        media (`str` or `os.PathLike`): Path or URL of the audio, or of a video whose soundtrack is taken.
+
+    Returns:
+        [`MiniMaxH3AudioReference`]: the `(channels, num_samples)` float32 waveform at the sample rate the container
+        reports.
+    """
+    av = _import_av()
+    with _local_media_file(media) as path, av.open(path) as container:
+        if not container.streams.audio:
+            raise ValueError(f"No audio stream to decode in {media}.")
+        waveform, sample_rate = _decode_reference_soundtrack(av, container, container.streams.audio[0])
+    return MiniMaxH3AudioReference(audio=waveform, sample_rate=sample_rate)
+
+
+class MiniMaxH3Ref2VALoadReferencesStep(ModularPipelineBlocks):
+    r"""
+    Reads `ref2va` references off the filesystem, so that a request can name its media instead of decoding it.
+
+    Not one of [`MiniMaxH3Ref2VABlocks`]' own steps — put it in front of them when the request holds paths:
+
+    ```py
+    >>> from diffusers.modular_pipelines import SequentialPipelineBlocks
+    >>> from diffusers.modular_pipelines.minimax_h3 import (
+    ...     MiniMaxH3Ref2VABlocks,
+    ...     MiniMaxH3Ref2VALoadReferencesStep,
+    ... )
+
+    >>> blocks = SequentialPipelineBlocks.from_blocks_dict(
+    ...     {"load_references": MiniMaxH3Ref2VALoadReferencesStep(), "ref2va": MiniMaxH3Ref2VABlocks()}
+    ... )
+    >>> pipe = blocks.init_pipeline("MiniMaxAI/MiniMax-H3-Ref2VA-Diffusers")
+    >>> output = pipe(
+    ...     prompt="the subject walks through the frame",
+    ...     reference_media=[{"image": "subject.png"}, {"video": "motion_ref.mp4"}, {"audio": "voice.wav"}],
+    ... )
+    ```
+    """
+
+    model_name = "minimax-h3-ref2va"
+
+    @property
+    def description(self) -> str:
+        return (
+            "Decodes `ref2va` references from paths or URLs, along with the rates they carry — a video's frame rate "
+            "and its soundtrack, an audio clip's sample rate. A convenience in front of the `ref2va` blocks, which "
+            "themselves only ever see in-memory media."
+        )
+
+    @property
+    def inputs(self) -> list[InputParam]:
+        return [
+            InputParam(
+                name="reference_media",
+                type_hint=list[dict],
+                required=True,
+                description=(
+                    "The media to condition on, **in the order the model should read them**, one `{medium: path}` "
+                    "mapping each: `{'image': ...}`, `{'video': ...}` or `{'audio': ...}`, where the value is a path "
+                    "or a URL. The medium is named rather than guessed from the file. A video brings its soundtrack "
+                    "along, so conditioning on a file's motion alone means building a "
+                    "[`MiniMaxH3VideoReference`] without one."
+                ),
+            ),
+        ]
+
+    @property
+    def intermediate_outputs(self) -> list[OutputParam]:
+        return [
+            OutputParam(
+                "references",
+                type_hint=list[MiniMaxH3Reference],
+                description="The decoded references, in packed order, carrying the rates their containers report.",
+            ),
+        ]
+
+    @torch.no_grad()
+    def __call__(self, components: MiniMaxH3Ref2VAModularPipeline, state: PipelineState) -> PipelineState:
+        block_state = self.get_block_state(state)
+
+        references = []
+        for index, entry in enumerate(block_state.reference_media):
+            if not isinstance(entry, dict) or len(entry) != 1 or next(iter(entry)) not in ("image", "video", "audio"):
+                raise ValueError(
+                    f"`reference_media[{index}]` must name exactly one medium, as `{{'image': path}}`, "
+                    f"`{{'video': path}}` or `{{'audio': path}}`, got {entry}."
+                )
+            [(medium, media)] = entry.items()
+            if medium == "image":
+                references.append(MiniMaxH3ImageReference(image=load_image(str(media))))
+            elif medium == "video":
+                references.append(decode_reference_video(media))
+            else:
+                references.append(decode_reference_audio(media))
+        block_state.references = references
+
+        self.set_block_state(state, block_state)
+        return components, state
diff --git a/tests/modular_pipelines/minimax_h3/test_modular_pipeline_minimax_h3.py b/tests/modular_pipelines/minimax_h3/test_modular_pipeline_minimax_h3.py
index 9a785ff125ca..27344667e837 100644
--- a/tests/modular_pipelines/minimax_h3/test_modular_pipeline_minimax_h3.py
+++ b/tests/modular_pipelines/minimax_h3/test_modular_pipeline_minimax_h3.py
@@ -23,7 +23,17 @@
     MiniMaxH3Ref2VABlocks,
     MiniMaxH3Ref2VAModularPipeline,
 )
-from diffusers.modular_pipelines.minimax_h3 import MiniMaxH3Reference, packing, packing_ref2va
+from diffusers.modular_pipelines.minimax_h3 import (
+    MiniMaxH3AudioReference,
+    MiniMaxH3ImageReference,
+    MiniMaxH3Ref2VALoadReferencesStep,
+    MiniMaxH3VideoReference,
+    decode_reference_audio,
+    decode_reference_video,
+    packing,
+    packing_ref2va,
+    reference_loading,
+)
 from diffusers.modular_pipelines.minimax_h3.before_encoder import MiniMaxH3Ref2VASetupStep
 from diffusers.modular_pipelines.minimax_h3.encoders import MiniMaxH3Ref2VATextEncoderStep, MiniMaxH3TextEncoderStep
 
@@ -98,14 +108,14 @@ def _waveform(duration: float) -> torch.Tensor:
     return torch.rand(2, round(duration * AUDIO_SAMPLE_RATE), generator=torch.Generator("cpu").manual_seed(1)) * 2 - 1
 
 
-def _reference_video(num_frames: int, size: int) -> MiniMaxH3Reference:
+def _reference_video(num_frames: int, size: int) -> MiniMaxH3VideoReference:
     """A silent video reference at MiniMax-H3's own 24 fps."""
-    return MiniMaxH3Reference(video=_video_frames(num_frames, size), fps=float(packing.MINIMAX_H3_FPS))
+    return MiniMaxH3VideoReference(frames=_video_frames(num_frames, size), fps=float(packing.MINIMAX_H3_FPS))
 
 
-def _reference_audio(duration: float) -> MiniMaxH3Reference:
+def _reference_audio(duration: float) -> MiniMaxH3AudioReference:
     """A standalone audio reference at the tiny audio VAE's own sample rate."""
-    return MiniMaxH3Reference(audio=_waveform(duration), sample_rate=AUDIO_SAMPLE_RATE)
+    return MiniMaxH3AudioReference(audio=_waveform(duration), sample_rate=AUDIO_SAMPLE_RATE)
 
 
 # The synthesized media fixtures the file-decoding tests are built from: a tiny 8 fps clip with a stereo soundtrack.
@@ -386,7 +396,15 @@ def test_encode_prompt(self, num_keyframes):
         keyframe = Image.fromarray((np.random.default_rng(0).random((32, 32, 3)) * 255).astype("uint8"))
 
         prompt_embeds, text_token_tags = MiniMaxH3TextEncoderStep.encode_prompt(
-            pipe, "a robot dancing", [keyframe] * num_keyframes, device=torch_device
+            pipe.text_encoder,
+            pipe.tokenizer,
+            pipe.processor,
+            "a robot dancing",
+            [keyframe] * num_keyframes,
+            text_encoder_layer=pipe.text_encoder_layer,
+            text_tag=pipe.text_tag,
+            video_tag=pipe.video_tag,
+            device=torch_device,
         )
 
         assert prompt_embeds.shape[0] == 1
@@ -471,7 +489,7 @@ class TestMiniMaxH3Ref2VAModularPipelineFast(MiniMaxH3ModularTesterBase):
     def get_dummy_inputs(self, seed=0):
         return {
             "prompt": "a robot dancing",
-            "references": [MiniMaxH3Reference(image=Image.new("RGB", (48, 80)))],
+            "references": [MiniMaxH3ImageReference(image=Image.new("RGB", (48, 80)))],
             "generator": self.get_generator(seed),
             "num_inference_steps": 2,
             "height": RESOLUTION,
@@ -566,10 +584,10 @@ def test_reference_combinations(self, kinds, num_frames):
         them.
         """
         media = {
-            "image": MiniMaxH3Reference(image=Image.new("RGB", (48, 80))),
+            "image": MiniMaxH3ImageReference(image=Image.new("RGB", (48, 80))),
             # A one-second video reference, soundtrack included, and a six-second standalone soundtrack.
-            "video": MiniMaxH3Reference(
-                video=_video_frames(packing.MINIMAX_H3_FPS, 64),
+            "video": MiniMaxH3VideoReference(
+                frames=_video_frames(packing.MINIMAX_H3_FPS, 64),
                 fps=float(packing.MINIMAX_H3_FPS),
                 audio=_waveform(1.0),
                 sample_rate=AUDIO_SAMPLE_RATE,
@@ -608,11 +626,19 @@ def test_encode_prompt(self, kinds):
         the vision pad ids. A video reference contributes one timestamped block per merged frame pair.
         """
         pipe = self.get_pipeline()
-        media = {"image": MiniMaxH3Reference(image=Image.new("RGB", (48, 80))), "video": _reference_video(25, 32)}
+        media = {"image": MiniMaxH3ImageReference(image=Image.new("RGB", (48, 80))), "video": _reference_video(25, 32)}
         references, _ = MiniMaxH3Ref2VASetupStep.prepare_references(pipe, [media[kind] for kind in kinds], NUM_FRAMES)
 
         prompt_embeds, text_token_tags = MiniMaxH3Ref2VATextEncoderStep.encode_prompt(
-            pipe, "a robot dancing", references, device=torch_device
+            pipe.text_encoder,
+            pipe.tokenizer,
+            pipe.processor,
+            "a robot dancing",
+            references,
+            text_encoder_layer=pipe.text_encoder_layer,
+            text_tag=pipe.text_tag,
+            video_tag=pipe.video_tag,
+            device=torch_device,
         )
 
         assert prompt_embeds.shape[0] == 1
@@ -621,10 +647,6 @@ def test_encode_prompt(self, kinds):
         assert torch.isfinite(prompt_embeds).all()
         # `0` tags a row of a vision block and `1` a text row, and every reference here carries a vision block.
         assert set(text_token_tags.tolist()) == {0, 1}
-        # A 25 frame reference decoded at 24 fps is read at 2 fps, so it is three frames merged into two blocks.
-        for reference in references:
-            if reference.kind == "video":
-                assert reference.block_timestamps == [0.25, 1.0]
 
     @pytest.mark.parametrize("media_type", ["pil", "np", "pt"], ids=["pil", "numpy", "torch"])
     def test_reference_media_layouts(self, media_type):
@@ -645,7 +667,7 @@ def test_reference_media_layouts(self, media_type):
 
         references, _ = MiniMaxH3Ref2VASetupStep.prepare_references(
             pipe,
-            [MiniMaxH3Reference(image=image), MiniMaxH3Reference(video=frames, fps=float(packing.MINIMAX_H3_FPS))],
+            [MiniMaxH3ImageReference(image=image), MiniMaxH3VideoReference(frames=frames, fps=float(packing.MINIMAX_H3_FPS))],
             NUM_FRAMES,
         )
 
@@ -662,11 +684,11 @@ def test_reference_rates_default_to_the_model_rates(self):
         waveform = _waveform(2.0)
 
         references, _ = MiniMaxH3Ref2VASetupStep.prepare_references(
-            pipe, [MiniMaxH3Reference(video=frames), MiniMaxH3Reference(audio=waveform)], NUM_FRAMES
+            pipe, [MiniMaxH3VideoReference(frames=frames), MiniMaxH3AudioReference(audio=waveform)], NUM_FRAMES
         )
 
         assert np.shares_memory(references[0].frames, frames)
-        assert torch.equal(references[1].waveform, waveform)
+        assert torch.equal(references[1].audio, waveform)
 
     def test_reference_sample_rate_override_resamples(self):
         r"""A waveform that says it carries another rate is resampled onto the audio VAE's own."""
@@ -676,14 +698,14 @@ def test_reference_sample_rate_override_resamples(self):
         references, _ = MiniMaxH3Ref2VASetupStep.prepare_references(
             pipe,
             [
-                MiniMaxH3Reference(image=Image.new("RGB", (48, 80))),
-                MiniMaxH3Reference(audio=waveform, sample_rate=AUDIO_SAMPLE_RATE // 2),
+                MiniMaxH3ImageReference(image=Image.new("RGB", (48, 80))),
+                MiniMaxH3AudioReference(audio=waveform, sample_rate=AUDIO_SAMPLE_RATE // 2),
             ],
             NUM_FRAMES,
         )
 
         # Half the audio VAE's rate, so the same samples span twice as many of the VAE's own.
-        assert references[1].waveform.shape == (2, 2 * waveform.shape[-1])
+        assert references[1].audio.shape == (2, 2 * waveform.shape[-1])
 
     def test_num_frames_left_open_needs_exactly_one_audio_reference(self):
         r"""Leaving `num_frames` out is ambiguous unless exactly one reference carries audio."""
@@ -706,7 +728,7 @@ def test_num_frames_left_open_holds_the_ceiling_for_the_aligned_count(self):
 
         inputs = self.get_dummy_inputs()
         inputs["num_frames"] = None
-        inputs["references"] = [MiniMaxH3Reference(image=Image.new("RGB", (48, 80))), _reference_audio(14.99)]
+        inputs["references"] = [MiniMaxH3ImageReference(image=Image.new("RGB", (48, 80))), _reference_audio(14.99)]
 
         with pytest.raises(ValueError, match="rounds up to 362 frames"):
             pipe(**inputs)
@@ -716,12 +738,12 @@ def test_num_frames_left_open_holds_the_ceiling_for_the_aligned_count(self):
         [
             ([], "at least one reference"),
             ([_reference_audio(6.0)], "cannot be used"),
-            ([MiniMaxH3Reference(image=Image.new("RGB", (32, 32)))] * 10, "at most 9 image references"),
+            ([MiniMaxH3ImageReference(image=Image.new("RGB", (32, 32)))] * 10, "at most 9 image references"),
             (
-                [MiniMaxH3Reference(image=Image.new("RGB", (32, 32)))] + [_reference_video(2, 32)] * 4,
+                [MiniMaxH3ImageReference(image=Image.new("RGB", (32, 32)))] + [_reference_video(2, 32)] * 4,
                 "at most 3 video references",
             ),
-            ([{"image": Image.new("RGB", (32, 32))}], "must be a \\[`MiniMaxH3Reference`\\]"),
+            ([{"image": Image.new("RGB", (32, 32))}], "must be a \\[`MiniMaxH3ImageReference`\\]"),
         ],
         ids=["no_references", "audio_alone", "too_many_images", "too_many_videos", "dict_entry"],
     )
@@ -737,100 +759,144 @@ def test_check_inputs_references(self, references, message):
 
 class TestMiniMaxH3Reference:
     """
-    [`MiniMaxH3Reference`] resolves a request's media at construction, before any block sees it.
+    The three reference dataclasses, which hold in-memory media and the rate it carries.
 
-    None of this needs a pipeline: a reference validates its own modality, decodes a path with PyAV and carries the
-    rates that come with it, which is exactly what makes the blocks able to assume in-memory media throughout.
+    Each knows its own modality, so nothing has to derive it from which fields happen to be set, and the fields a
+    modality has no use for do not exist on it.
     """
 
-    @pytest.mark.parametrize(
-        "kwargs,message",
-        [
-            ({}, "exactly one of"),
-            ({"image": Image.new("RGB", (32, 32)), "video": _video_frames(2, 32)}, "exactly one of"),
-            ({"image": Image.new("RGB", (32, 32)), "audio": _waveform(1.0)}, "exactly one of"),
-            ({"image": "astronaut.png"}, "not a valid path"),
-            ({"video": "motion.mp4"}, "not a valid path"),
-            ({"audio": "voice.wav"}, "not a valid path"),
-        ],
-        ids=[
-            "no_medium",
-            "image_and_video",
-            "image_and_audio",
-            "missing_image_file",
-            "missing_video_file",
-            "missing_audio_file",
-        ],
-    )
-    def test_reference_construction(self, kwargs, message):
+    def test_reference_defaults(self):
+        r"""A reference knows its own modality, and defaults to MiniMax-H3's own frame rate for its frames."""
+        assert MiniMaxH3VideoReference(frames=_video_frames(2, 32)).fps == float(packing.MINIMAX_H3_FPS)
+        assert MiniMaxH3ImageReference(image=Image.new("RGB", (32, 32))).kind == "image"
+        assert not MiniMaxH3ImageReference(image=Image.new("RGB", (32, 32))).has_audio
+        assert _reference_video(2, 32).kind == "video"
+        assert not _reference_video(2, 32).has_audio
+        assert _reference_audio(6.0).kind == "audio"
+        assert _reference_audio(6.0).has_audio
+
+    def test_video_reference_has_audio_follows_its_soundtrack(self):
+        r"""A video reference contributes audio rows exactly when it was given a soundtrack of its own."""
+        frames = _video_frames(2, 32)
+
+        assert not MiniMaxH3VideoReference(frames=frames).has_audio
+        assert MiniMaxH3VideoReference(frames=frames, audio=_waveform(1.0)).has_audio
+
+    def test_a_modality_only_carries_its_own_fields(self):
         r"""
-        A reference resolves itself at construction: exactly one medium, bar a video's own soundtrack, and a path that
-        names a file it can actually open.
+        The fields that used to be dead weight are gone: an image reference has no rates, and no reference can be
+        built holding two media at once.
         """
-        with pytest.raises(ValueError, match=message):
-            MiniMaxH3Reference(**kwargs)
+        image = MiniMaxH3ImageReference(image=Image.new("RGB", (32, 32)))
+
+        assert not hasattr(image, "fps") and not hasattr(image, "sample_rate")
+        with pytest.raises(TypeError):
+            MiniMaxH3ImageReference(image=Image.new("RGB", (32, 32)), audio=_waveform(1.0))
+        with pytest.raises(TypeError):
+            MiniMaxH3AudioReference(audio=_waveform(1.0), frames=_video_frames(2, 32))
+
+
+class TestMiniMaxH3ReferenceLoading:
+    """
+    Decoding references off the filesystem, which is the caller's job rather than the blocks'.
+
+    None of this needs a checkpoint: [`decode_reference_video`] and [`decode_reference_audio`] read a container with
+    PyAV and return a reference carrying the rates it reports, and [`MiniMaxH3Ref2VALoadReferencesStep`] is the block
+    that does the same for a whole ordered request.
+    """
 
-    def test_reference_decodes_files(self, tmp_path):
+    def test_decode_video_carries_frames_rate_and_soundtrack(self, tmp_path):
         r"""
-        A reference takes a path as well as in-memory media, and decodes it as it is built: the frames and the samples
-        themselves, plus the rates the container reports, which is what the model conditions on.
+        A decoded video brings the three things the model conditions on: the frames, the rate they were shot at, and
+        the container's soundtrack as this reference's own.
         """
-        video_path, image_path, audio_path = _media_fixtures(tmp_path)
+        video_path, _, _ = _media_fixtures(tmp_path)
 
-        video = MiniMaxH3Reference(video=str(video_path))
-        image = MiniMaxH3Reference(image=str(image_path))
-        audio = MiniMaxH3Reference(audio=str(audio_path))
+        video = decode_reference_video(video_path)
 
-        assert video.kind == "video"
-        assert video.video.shape == (FIXTURE_NUM_FRAMES, 32, 64, 3) and video.video.dtype == np.uint8
+        assert isinstance(video, MiniMaxH3VideoReference) and video.kind == "video"
+        assert video.frames.shape == (FIXTURE_NUM_FRAMES, 32, 64, 3) and video.frames.dtype == np.uint8
         assert video.fps == FIXTURE_FPS
-        # The container carries a soundtrack, which a video reference conditions on as its own.
         assert video.has_audio and video.audio.shape[0] == 2 and video.sample_rate == FIXTURE_SAMPLE_RATE
-        assert image.kind == "image" and image.image.size == (64, 32)
-        assert audio.kind == "audio" and audio.audio.shape[0] == 2 and audio.sample_rate == FIXTURE_SAMPLE_RATE
-        assert audio.audio.dtype == torch.float32
 
-    def test_reference_silent_file_carries_no_soundtrack(self, tmp_path):
+    def test_decode_audio_carries_the_sample_rate(self, tmp_path):
+        r"""A decoded audio file brings the rate its samples are at, which is what they are resampled from."""
+        _, _, audio_path = _media_fixtures(tmp_path)
+
+        audio = decode_reference_audio(audio_path)
+
+        assert isinstance(audio, MiniMaxH3AudioReference) and audio.kind == "audio"
+        assert audio.audio.shape[0] == 2 and audio.audio.dtype == torch.float32
+        assert audio.sample_rate == FIXTURE_SAMPLE_RATE
+
+    def test_decoded_rates_can_be_corrected(self, tmp_path):
+        r"""A container whose metadata is wrong is corrected on the reference the decode returned."""
+        video_path, _, _ = _media_fixtures(tmp_path)
+
+        video = decode_reference_video(video_path)
+        video.fps = 12.0
+
+        assert video.fps == 12.0 and video.sample_rate == FIXTURE_SAMPLE_RATE
+
+    def test_decode_silent_video_carries_no_soundtrack(self, tmp_path):
         r"""There is nothing to adopt from a container without an audio stream."""
         silent_path = tmp_path / "silent.mp4"
         _write_video(silent_path, with_audio=False)
 
-        reference = MiniMaxH3Reference(video=str(silent_path))
+        reference = decode_reference_video(silent_path)
 
         assert not reference.has_audio and reference.sample_rate is None
         assert reference.fps == FIXTURE_FPS
 
-    def test_reference_rates_override_the_container(self, tmp_path):
-        r"""A rate the request passes wins over the one the container reports, whose metadata may be wrong."""
+    def test_decoding_needs_pyav(self, tmp_path, monkeypatch):
+        r"""Decoding a video or an audio file is a PyAV job, and says so when PyAV is not installed."""
         video_path, _, audio_path = _media_fixtures(tmp_path)
+        monkeypatch.setattr(reference_loading, "is_av_available", lambda: False)
 
-        video = MiniMaxH3Reference(video=str(video_path), fps=12.0, sample_rate=16000)
-        audio = MiniMaxH3Reference(audio=str(audio_path), sample_rate=16000)
+        with pytest.raises(ImportError, match="pip install av"):
+            decode_reference_video(video_path)
+        with pytest.raises(ImportError, match="pip install av"):
+            decode_reference_audio(audio_path)
 
-        # The container reports `FIXTURE_FPS` and `FIXTURE_SAMPLE_RATE`, and the request overrides both.
-        assert video.fps == 12.0 and video.sample_rate == 16000
-        assert audio.sample_rate == 16000
+    def test_load_references_block_decodes_a_request_in_order(self, tmp_path):
+        r"""
+        The block turns an ordered list of named media into the references the `ref2va` blocks take.
 
-    def test_reference_file_needs_pyav(self, tmp_path, monkeypatch):
-        r"""Decoding a video or an audio file is a PyAV job, and says so when PyAV is not installed."""
+        Order is preserved because it is semantic: it labels the references in the prompt presentation and lays them
+        out on the shared rotary clock.
+        """
         video_path, image_path, audio_path = _media_fixtures(tmp_path)
-        monkeypatch.setattr(packing_ref2va, "is_av_available", lambda: False)
+        pipe = MiniMaxH3Ref2VALoadReferencesStep().init_pipeline()
 
-        with pytest.raises(ImportError, match="pip install av"):
-            MiniMaxH3Reference(video=str(video_path))
-        with pytest.raises(ImportError, match="pip install av"):
-            MiniMaxH3Reference(audio=str(audio_path))
-        # An image never needs it.
-        assert MiniMaxH3Reference(image=str(image_path)).image.size == (64, 32)
+        references = pipe(
+            reference_media=[{"image": image_path}, {"video": video_path}, {"audio": audio_path}],
+            output="references",
+        )
 
-    def test_reference_defaults(self):
-        r"""A reference knows its own modality, and defaults to MiniMax-H3's own frame rate for its frames."""
-        assert MiniMaxH3Reference(video=_video_frames(2, 32)).fps == float(packing.MINIMAX_H3_FPS)
-        assert MiniMaxH3Reference(image=Image.new("RGB", (32, 32))).kind == "image"
-        assert not MiniMaxH3Reference(image=Image.new("RGB", (32, 32))).has_audio
-        assert _reference_video(2, 32).kind == "video"
-        assert _reference_audio(6.0).kind == "audio"
-        assert _reference_audio(6.0).has_audio
+        assert [reference.kind for reference in references] == ["image", "video", "audio"]
+        assert references[0].image.size == (64, 32)
+        assert references[1].fps == FIXTURE_FPS and references[1].sample_rate == FIXTURE_SAMPLE_RATE
+        assert references[2].sample_rate == FIXTURE_SAMPLE_RATE
+
+    @pytest.mark.parametrize(
+        "entry,message",
+        [
+            ({}, "must name exactly one medium"),
+            ({"image": "a.png", "video": "b.mp4"}, "must name exactly one medium"),
+            ({"picture": "a.png"}, "must name exactly one medium"),
+            ("a.png", "must name exactly one medium"),
+            ({"image": "missing.png"}, "not a valid path"),
+            ({"video": "missing.mp4"}, "not a valid path"),
+            ({"audio": "missing.wav"}, "not a valid path"),
+        ],
+        ids=["empty", "two_media", "unknown_medium", "bare_path", "missing_image", "missing_video", "missing_audio"],
+    )
+    def test_load_references_block_rejects(self, entry, message):
+        r"""The medium is named rather than guessed from the file, and the path has to name a file it can open."""
+        pipe = MiniMaxH3Ref2VALoadReferencesStep().init_pipeline()
+
+        with pytest.raises(ValueError, match=message):
+            pipe(reference_media=[entry])
 
 
 class TestMiniMaxH3ReferenceGeometry:
@@ -840,6 +906,18 @@ class TestMiniMaxH3ReferenceGeometry:
     These are the passes `MiniMaxH3Ref2VASetupStep` runs a reference through before any VAE sees it.
     """
 
+    def test_video_reference_vision_blocks(self):
+        r"""
+        The conditioner reads a reference video at 2 fps and Qwen3-VL merges every two of those frames into one
+        vision block, labelled with the mean timestamp of the pair.
+
+        A 25 frame reference at 24 fps samples three frames, which merge into two blocks at 0.25 and 1.0 seconds.
+        """
+        frames, timestamps = packing_ref2va.sample_reference_video_frames(_video_frames(25, 32))
+
+        assert len(frames) == 3
+        assert timestamps == [0.25, 1.0]
+
     def test_reference_image_geometry(self, monkeypatch):
         r"""
         A reference image is encoded at a 2048 pixel short edge, both axes rounded to a multiple of 32, with no area
@@ -847,8 +925,8 @@ def test_reference_image_geometry(self, monkeypatch):
         """
         monkeypatch.setattr(packing_ref2va, "MINIMAX_H3_REFERENCE_IMAGE_SHORT_EDGE", 2048)
 
-        assert packing_ref2va.resolve_reference_image_size(80, 48) == (2048, 3424)
-        assert packing_ref2va.resolve_reference_image_size(48, 80) == (3424, 2048)
+        assert packing_ref2va.resolve_reference_image_size(80, 48, 32) == (2048, 3424)
+        assert packing_ref2va.resolve_reference_image_size(48, 80, 32) == (3424, 2048)
 
     def test_video_reference_resampled_to_the_model_frame_rate(self):
         r"""

From 01f07156acbb2ca1b373fd43cecfa86f9d60d65e Mon Sep 17 00:00:00 2001
From: yiyixuxu <yixu310@gmail.com>
Date: Mon, 3 Aug 2026 16:33:29 +0000
Subject: [PATCH 08/16] Fold MiniMax-H3 into one pipeline with
 workflow-selected blocks
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Both transformer partitions ship in one repo, so there is no reason for two
pipeline classes. `MiniMaxH3Ref2VABlocks` and `MiniMaxH3Ref2VAModularPipeline`
are gone; `MiniMaxH3Blocks` becomes the auto blockset — the before-encode,
text-encoder, VAE-encoder and core-denoise slots each pick their branch on the
`references` trigger, the way `z_image` and `krea2` pack theirs — with four
workflows: `t2va`, `fl2va`, `fl2va_last_frame`, `ref2va`.
`from_pretrained(..., workflow="ref2va")` prunes to the ref2va branch and loads
only `transformer_ref`; the released repo's `modular_model_index.json` keeps
working because the class name is reused. The two loop denoisers merge — they
differed only in which transformer partition they read, which becomes block
config — and `patch_size` on the one pipeline reads whichever partition is
loaded.

The rest is each block owning its own work. Validation moves out of
`_check_inputs` into `__call__` — which also leaves ref2va's duration ceiling
checked once instead of twice with two different messages. `num_frames` is now
required on ref2va: with it passed, every audio-bearing reference already rides
at its own truncated length, so deriving it from a soundtrack added no
capability — it filled in one number, worked only in the single-soundtrack
case, and cost a conditional-optional API rule plus two error paths. Media
normalization becomes two staticmethods on the setup step, with the image
branch inlined; the seeded VAE conditioning recipe and the Qwen3-VL embedding
call are shared functions, `encode_vae_condition` and
`get_qwen3vl_prompt_embeds`, used by both halves; the packed-sequence builders
land on their layout steps with the rotary helpers module-level beside them.
That empties `packing.py` and `packing_ref2va.py`; what remains of the latter —
the four public reference dataclasses — is renamed `references.py`.

Two guards for hand-assembled chains: `prepare_latents` verifies the packed
condition rows match the counts the layout reserved for both modalities, and
the ref2va layout validates the canvas multiple the way t2va's already did.

All 11 documented cases — t2va, the three fl2va anchorings, the six ref2va
configurations, and the defaults path — are bit-exact on frames and audio
against the pre-refactor baseline.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 docs/source/en/api/pipelines/minimax_h3.md    |  79 +-
 src/diffusers/__init__.py                     |   4 -
 src/diffusers/modular_pipelines/__init__.py   |   4 -
 .../modular_pipelines/minimax_h3/__init__.py  |  22 +-
 .../minimax_h3/before_denoise.py              | 461 +++++++++++-
 .../minimax_h3/before_encoder.py              | 381 +++++-----
 .../modular_pipelines/minimax_h3/denoise.py   | 107 +--
 .../modular_pipelines/minimax_h3/encoders.py  | 688 ++++++++++--------
 .../minimax_h3/modular_blocks_minimax_h3.py   | 616 +++++++++++++---
 .../minimax_h3/modular_pipeline.py            | 171 +++--
 .../modular_pipelines/minimax_h3/packing.py   | 359 ---------
 .../minimax_h3/packing_ref2va.py              | 675 -----------------
 .../minimax_h3/reference_loading.py           |  16 +-
 .../minimax_h3/references.py                  | 151 ++++
 .../modular_pipelines/modular_pipeline.py     |   1 -
 .../dummy_torch_and_transformers_objects.py   |  30 -
 .../test_modular_pipeline_minimax_h3.py       | 241 +++---
 17 files changed, 1995 insertions(+), 2011 deletions(-)
 delete mode 100644 src/diffusers/modular_pipelines/minimax_h3/packing.py
 delete mode 100644 src/diffusers/modular_pipelines/minimax_h3/packing_ref2va.py
 create mode 100644 src/diffusers/modular_pipelines/minimax_h3/references.py

diff --git a/docs/source/en/api/pipelines/minimax_h3.md b/docs/source/en/api/pipelines/minimax_h3.md
index cccf2d712b64..860d961c4e96 100644
--- a/docs/source/en/api/pipelines/minimax_h3.md
+++ b/docs/source/en/api/pipelines/minimax_h3.md
@@ -27,32 +27,29 @@ MiniMax-H3 is integrated as [Modular Diffusers](../../modular_diffusers/overview
 
 MiniMax-H3 was released as two checkpoint partitions that share every component except the transformer, so the diffusers conversion puts both in **one repository**:
 
-| Subfolder | Blocks | Tasks |
-|---|---|---|
-| `transformer/` | [`MiniMaxH3Blocks`] | `t2va` (text only) and `fl2va` (first and/or last keyframe) |
-| `transformer_ref/` | [`MiniMaxH3Ref2VABlocks`] | `ref2va` (an ordered mix of image, video and audio references) |
+| Subfolder | Workflows |
+|---|---|
+| `transformer/` | `t2va` (text only), `fl2va` and `fl2va_last_frame` (first and/or last keyframe) |
+| `transformer_ref/` | `ref2va` (an ordered mix of image, video and audio references) |
 
 Everything but the transformer, i.e. the video VAE, the audio VAE, the Qwen3-VL conditioner, its tokenizer and processor, and the two schedulers, is shared and stored once.
 
-The repository carries one `modular_model_index.json`, which names every component of both halves with its own loading spec. Each blockset declares only the components it runs, and `load_components` fetches exactly those subfolders: loading the `t2va` / `fl2va` half never touches `transformer_ref/`, and loading the `ref2va` half never touches `transformer/`. Nothing else in the repository is fetched either, which is what lets one repository carry the two partitions, and the original checkpoint folders next to the converted ones.
-
-`modular_model_index.json` names the `t2va` / `fl2va` half as its own class, so [`~ModularPipeline.from_pretrained`] resolves that half. The `ref2va` half reads the very same file through its own blocks:
+All four tasks are workflows of the one [`MiniMaxH3Blocks`], and the repository carries one `modular_model_index.json` naming every component with its own loading spec. Selecting a workflow prunes the blocks to that task's own, and `load_components` then fetches exactly the subfolders they declare: a `t2va` / `fl2va` request never touches `transformer_ref/`, a `ref2va` request never touches `transformer/`.
 
 ```py
 import torch
 from diffusers import ModularPipeline
-from diffusers.modular_pipelines import MiniMaxH3Ref2VABlocks
 
 # `t2va` / `fl2va`: loads `transformer/`, and never `transformer_ref/`.
-pipe = ModularPipeline.from_pretrained("MiniMaxAI/MiniMax-H3")
+pipe = ModularPipeline.from_pretrained("MiniMaxAI/MiniMax-H3", workflow="t2va")
 
 # `ref2va`: loads `transformer_ref/`, and never `transformer/`, out of the same repository.
-pipe = MiniMaxH3Ref2VABlocks().init_pipeline("MiniMaxAI/MiniMax-H3")
+pipe = ModularPipeline.from_pretrained("MiniMaxAI/MiniMax-H3", workflow="ref2va")
 
 pipe.load_components(dtype=torch.bfloat16)
 ```
 
-Each blockset also carries the workflows it serves — `t2va`, `fl2va` and `fl2va_last_frame` for [`MiniMaxH3Blocks`], `ref2va` for [`MiniMaxH3Ref2VABlocks`] — which name the inputs each task requires.
+Without a `workflow=`, the blocks keep every branch and `load_components` pulls **both** 61.7GB transformer partitions — pass one to load only what the task needs.
 
 The conditioner is a `Qwen3VLForConditionalGeneration`, and MiniMax-H3 reads the *unnormalized* hidden state after its 50th decoder layer rather than the last one, so the full released checkpoint is used with its language-model head unused.
 
@@ -193,22 +190,37 @@ Video and audio are generated jointly and come out of the call as separate outpu
 
 ## Omni-references
 
-[`MiniMaxH3Ref2VABlocks`] conditions on an ordered list of references: up to 9 images, 3 videos and 3 audio clips, 12 in total. The order is semantic. It labels the references in the prompt presentation (`"<Picture 1>"`, `"<Audio 1>"`, `"<Video 1>"`) and it advances the shared audio/video rotary clock, so reordering the same references is a different request.
+The `ref2va` workflow conditions on an ordered list of references: up to 9 images, 3 videos and 3 audio clips, 12 in total. The order is semantic. It labels the references in the prompt presentation (`"<Picture 1>"`, `"<Audio 1>"`, `"<Video 1>"`) and it advances the shared audio/video rotary clock, so reordering the same references is a different request.
 
 Unlike the keyframes above, references do not bind the generated geometry: they are encoded at their own resolution and the target canvas defaults to MiniMax-H3's 16:9.
 
-Every reference is a [`~modular_pipelines.minimax_h3.MiniMaxH3Reference`], and it takes a path or a URL as well as in-memory media: a path is decoded when the reference is built, with [`~utils.load_image`] for an image and [PyAV](https://github.com/PyAV-Org/PyAV) for a video or an audio file, so the blocks themselves never open a media file. Decoding brings the rates along, which is what the model needs: a video reference reads its frame rate off the container and adopts the container's soundtrack when it has one, and an audio reference its sample rate.
+There is one reference class per modality, each holding in-memory media and the rate that media carries:
+
+| reference | media | rate it declares |
+| --- | --- | --- |
+| [`~modular_pipelines.minimax_h3.MiniMaxH3ImageReference`] | `image` | — |
+| [`~modular_pipelines.minimax_h3.MiniMaxH3VideoReference`] | `frames`, and `audio` for its own soundtrack | `fps`, defaulting to MiniMax-H3's 24.0, and `sample_rate` |
+| [`~modular_pipelines.minimax_h3.MiniMaxH3AudioReference`] | `audio` | `sample_rate`, defaulting to the audio VAE's own |
+
+The rates are what everything is resampled from: frames onto MiniMax-H3's own 24 fps by dropping and duplicating whole frames, a waveform onto the audio VAE's sample rate. Media at MiniMax-H3's own rates flows through untouched, so only data produced at another rate has to say so.
 
-In-memory media declares the rates it carries instead, defaulting to MiniMax-H3's own: `fps=24.0` and the audio VAE's sample rate, so only self-generated data at another rate has to say so. An explicit `fps` or `sample_rate` also wins over a container whose metadata is wrong. Frames are resampled onto MiniMax-H3's own 24 fps by dropping and duplicating whole frames, and a waveform onto the audio VAE's sample rate. A video reference conditions on its motion **and**, when it carries an `audio` waveform, on that soundtrack, which is then packed as this reference's own.
+The blocks never open a media file — decoding a path is the caller's job, as it is everywhere else in the library. [`~modular_pipelines.minimax_h3.decode_reference_video`] and [`~modular_pipelines.minimax_h3.decode_reference_audio`] do it with [PyAV](https://github.com/PyAV-Org/PyAV) and return a reference carrying the rates the container reports — a video brings its frame rate and its soundtrack along. Prefer them over [`~utils.load_video`], which drops the frame rate: a reference built from frames whose real rate was lost is conditioned on at the wrong speed, and nothing raises. For a whole request, [`~modular_pipelines.minimax_h3.MiniMaxH3Ref2VALoadReferencesStep`] is the same thing as a block you can put in front of [`MiniMaxH3Blocks`].
 
 ```py
 import torch
-from diffusers.modular_pipelines import MiniMaxH3Ref2VABlocks
-from diffusers.modular_pipelines.minimax_h3 import MiniMaxH3Reference
+from diffusers import ModularPipeline
+from diffusers.modular_pipelines.minimax_h3 import (
+    MiniMaxH3ImageReference,
+    MiniMaxH3VideoReference,
+    decode_reference_audio,
+    decode_reference_video,
+)
 from diffusers.utils import load_image, load_video
 from diffusers.utils.export_utils import encode_video
 
-pipe = MiniMaxH3Ref2VABlocks().init_pipeline("MiniMaxAI/MiniMax-H3")
+# `ref2va` is a workflow of the one MiniMax-H3 pipeline; selecting it loads only the `transformer_ref/`
+# checkpoint partition.
+pipe = ModularPipeline.from_pretrained("MiniMaxAI/MiniMax-H3", workflow="ref2va")
 pipe.load_components(dtype=torch.bfloat16)
 pipe.to("cuda")
 
@@ -216,25 +228,24 @@ subject = load_image(
     "https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/diffusers/astronaut.jpg"
 )
 
-# A reference decodes a path or a URL as it is built, rates included: the video brings its own frame rate and its
-# soundtrack, the audio clip its sample rate.
+# Decoding a file brings its rates along: the video its own frame rate and its soundtrack, the clip its sample rate.
 state = pipe(
     prompt="The character speaks in time with the reference recording, natural lip movement",
     references=[
-        MiniMaxH3Reference(image=subject),
-        MiniMaxH3Reference(
-            video="https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/diffusers/hiker.mp4"
+        MiniMaxH3ImageReference(image=subject),
+        decode_reference_video(
+            "https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/diffusers/hiker.mp4"
         ),
-        MiniMaxH3Reference(audio="voice.wav"),
+        decode_reference_audio("voice.wav"),
     ],
     num_frames=124,
 )
 
-# In-memory media says which rates it carries, MiniMax-H3's own by default.
+# Frames a request already holds declare the rate they carry — `load_video` does not preserve it.
 motion = load_video("motion_ref.mp4")
 state = pipe(
     prompt="The subject walks toward camera, matching the reference video's shot rhythm",
-    references=[MiniMaxH3Reference(image=subject), MiniMaxH3Reference(video=motion, fps=30.0)],
+    references=[MiniMaxH3ImageReference(image=subject), MiniMaxH3VideoReference(frames=motion, fps=30.0)],
     num_frames=124,
 )
 
@@ -247,7 +258,7 @@ encode_video(
 )
 ```
 
-`num_frames` may be left out, but only when exactly one reference carries audio: the duration is then that soundtrack's, snapped up to the next `17 * n + 5` the video VAE can decode. A soundtrack whose *aligned* duration falls outside the 5 to 15 seconds MiniMax-H3 generates is rejected rather than silently stretched, so a clip just under 15 seconds — which rounds up to 362 frames, i.e. 15.083 seconds — has to name a shorter `num_frames` explicitly.
+`num_frames` is required for `ref2va`. To generate a video exactly as long as a reference soundtrack, compute it from the clip — `round(samples / sample_rate * 24)` — and it is snapped up to the next `17 * n + 5` the video VAE can decode; the resulting duration must stay between the 5 and 15 seconds MiniMax-H3 generates.
 
 ## MiniMaxH3ModularPipeline
 
@@ -257,14 +268,18 @@ encode_video(
 
 [[autodoc]] MiniMaxH3Blocks
 
-## MiniMaxH3Ref2VAModularPipeline
+## MiniMaxH3ImageReference
+
+[[autodoc]] modular_pipelines.minimax_h3.MiniMaxH3ImageReference
+
+## MiniMaxH3VideoReference
 
-[[autodoc]] MiniMaxH3Ref2VAModularPipeline
+[[autodoc]] modular_pipelines.minimax_h3.MiniMaxH3VideoReference
 
-## MiniMaxH3Ref2VABlocks
+## MiniMaxH3AudioReference
 
-[[autodoc]] MiniMaxH3Ref2VABlocks
+[[autodoc]] modular_pipelines.minimax_h3.MiniMaxH3AudioReference
 
-## MiniMaxH3Reference
+## MiniMaxH3Ref2VALoadReferencesStep
 
-[[autodoc]] modular_pipelines.minimax_h3.MiniMaxH3Reference
+[[autodoc]] modular_pipelines.minimax_h3.MiniMaxH3Ref2VALoadReferencesStep
diff --git a/src/diffusers/__init__.py b/src/diffusers/__init__.py
index 3c8a46426d2a..2deff4b71cb2 100644
--- a/src/diffusers/__init__.py
+++ b/src/diffusers/__init__.py
@@ -537,8 +537,6 @@
             "LTXModularPipeline",
             "MiniMaxH3Blocks",
             "MiniMaxH3ModularPipeline",
-            "MiniMaxH3Ref2VABlocks",
-            "MiniMaxH3Ref2VAModularPipeline",
             "QwenImageAutoBlocks",
             "QwenImageEditAutoBlocks",
             "QwenImageEditModularPipeline",
@@ -1365,8 +1363,6 @@
             LTXModularPipeline,
             MiniMaxH3Blocks,
             MiniMaxH3ModularPipeline,
-            MiniMaxH3Ref2VABlocks,
-            MiniMaxH3Ref2VAModularPipeline,
             QwenImageAutoBlocks,
             QwenImageEditAutoBlocks,
             QwenImageEditModularPipeline,
diff --git a/src/diffusers/modular_pipelines/__init__.py b/src/diffusers/modular_pipelines/__init__.py
index a107a004b7f2..008a654c3fa3 100644
--- a/src/diffusers/modular_pipelines/__init__.py
+++ b/src/diffusers/modular_pipelines/__init__.py
@@ -124,8 +124,6 @@
     _import_structure["minimax_h3"] = [
         "MiniMaxH3Blocks",
         "MiniMaxH3ModularPipeline",
-        "MiniMaxH3Ref2VABlocks",
-        "MiniMaxH3Ref2VAModularPipeline",
     ]
     _import_structure["z_image"] = [
         "ZImageAutoBlocks",
@@ -184,8 +182,6 @@
         from .minimax_h3 import (
             MiniMaxH3Blocks,
             MiniMaxH3ModularPipeline,
-            MiniMaxH3Ref2VABlocks,
-            MiniMaxH3Ref2VAModularPipeline,
         )
         from .modular_pipeline import (
             AutoPipelineBlocks,
diff --git a/src/diffusers/modular_pipelines/minimax_h3/__init__.py b/src/diffusers/modular_pipelines/minimax_h3/__init__.py
index eac92574b60c..0b8b32de4312 100644
--- a/src/diffusers/modular_pipelines/minimax_h3/__init__.py
+++ b/src/diffusers/modular_pipelines/minimax_h3/__init__.py
@@ -21,9 +21,9 @@
 
     _dummy_objects.update(get_objects_from_module(dummy_torch_and_transformers_objects))
 else:
-    _import_structure["modular_blocks_minimax_h3"] = ["MiniMaxH3Blocks", "MiniMaxH3Ref2VABlocks"]
-    _import_structure["modular_pipeline"] = ["MiniMaxH3ModularPipeline", "MiniMaxH3Ref2VAModularPipeline"]
-    _import_structure["packing_ref2va"] = [
+    _import_structure["modular_blocks_minimax_h3"] = ["MiniMaxH3Blocks"]
+    _import_structure["modular_pipeline"] = ["MiniMaxH3ModularPipeline"]
+    _import_structure["references"] = [
         "MiniMaxH3AudioReference",
         "MiniMaxH3ImageReference",
         "MiniMaxH3Reference",
@@ -42,19 +42,19 @@
     except OptionalDependencyNotAvailable:
         from ...utils.dummy_torch_and_transformers_objects import *  # noqa F403
     else:
-        from .modular_blocks_minimax_h3 import MiniMaxH3Blocks, MiniMaxH3Ref2VABlocks
-        from .modular_pipeline import MiniMaxH3ModularPipeline, MiniMaxH3Ref2VAModularPipeline
-        from .packing_ref2va import (
-            MiniMaxH3AudioReference,
-            MiniMaxH3ImageReference,
-            MiniMaxH3Reference,
-            MiniMaxH3VideoReference,
-        )
+        from .modular_blocks_minimax_h3 import MiniMaxH3Blocks
+        from .modular_pipeline import MiniMaxH3ModularPipeline
         from .reference_loading import (
             MiniMaxH3Ref2VALoadReferencesStep,
             decode_reference_audio,
             decode_reference_video,
         )
+        from .references import (
+            MiniMaxH3AudioReference,
+            MiniMaxH3ImageReference,
+            MiniMaxH3Reference,
+            MiniMaxH3VideoReference,
+        )
 else:
     import sys
 
diff --git a/src/diffusers/modular_pipelines/minimax_h3/before_denoise.py b/src/diffusers/modular_pipelines/minimax_h3/before_denoise.py
index 95bd786cca97..c7e03d22683b 100644
--- a/src/diffusers/modular_pipelines/minimax_h3/before_denoise.py
+++ b/src/diffusers/modular_pipelines/minimax_h3/before_denoise.py
@@ -12,6 +12,7 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+import numpy as np
 import torch
 
 from ...schedulers import MiniMaxH3Scheduler
@@ -19,22 +20,148 @@
 from ...utils.torch_utils import randn_tensor
 from ..modular_pipeline import ModularPipelineBlocks, PipelineState
 from ..modular_pipeline_utils import ComponentSpec, InputParam, OutputParam
-from .modular_pipeline import MiniMaxH3ModularPipeline, MiniMaxH3Ref2VAModularPipeline
-from .packing import (
+from .modular_pipeline import (
+    MINIMAX_H3_AUDIO_CHANNELS,
+    MINIMAX_H3_AUDIO_TAG,
+    MINIMAX_H3_VIDEO_TAG,
+    MiniMaxH3ModularPipeline,
     align_num_frames,
     audio_latent_num_frames,
-    build_packed_sequence,
-    build_row_timesteps,
-    patchify_video_latents,
     resolve_canvas_size,
     video_latent_num_frames,
 )
-from .packing_ref2va import MiniMaxH3Reference, build_ref2va_packed_sequence
+from .references import MiniMaxH3Reference
 
 
 logger = logging.get_logger(__name__)  # pylint: disable=invalid-name
 
 
+# Rotary-time constants. One latent frame spans `5/3 * frames_per_latent` rotary units, where the pattern
+# `(1, 4, 4, 4, 4)` mirrors the VAE's 17-pixel-frames-to-5-latent-frames grouping; the spatial axes are normalized
+# by the square root of the latent area and scaled by 32.
+_ROPE_FRAME_RESCALE = 5.0 / 3.0
+_ROPE_FRAMES_PER_LATENT = (1, 4, 4, 4, 4)
+_ROPE_SPATIAL_SCALE = 32
+
+
+def patchify_video_latents(latents: torch.Tensor, patch_size: tuple[int, int, int]) -> torch.Tensor:
+    r"""
+    Pack video latents into transformer rows.
+
+    Args:
+        latents (`torch.Tensor` of shape `(batch_size, channels, num_frames, height, width)`):
+            The latents to pack.
+        patch_size (`tuple[int, int, int]`): The `(t, h, w)` patch.
+
+    Returns:
+        `torch.Tensor` of shape `(batch_size * num_patches, channels * prod(patch_size))`: The packed rows, ordered
+        frame-major then row-major.
+    """
+    patch_t, patch_h, patch_w = patch_size
+    batch_size, channels, num_frames, height, width = latents.shape
+    if num_frames % patch_t or height % patch_h or width % patch_w:
+        raise ValueError(f"Latents of shape {tuple(latents.shape)} are not divisible by the patch {patch_size}.")
+
+    latents = latents.reshape(
+        batch_size,
+        channels,
+        num_frames // patch_t,
+        patch_t,
+        height // patch_h,
+        patch_h,
+        width // patch_w,
+        patch_w,
+    )
+    latents = latents.permute(0, 2, 4, 6, 1, 3, 5, 7)
+    return latents.reshape(-1, channels * patch_t * patch_h * patch_w).contiguous()
+
+
+def _spatial_position_grid(dim: int, patch: int, sqrt_area: float) -> torch.Tensor:
+    r"""
+    One aspect-normalized spatial rotary axis: `dim // patch` coordinates centred on the unit interval, scaled up by
+    32. The right endpoint is excluded, so a square canvas spans `[0, 32)`.
+    """
+    ratio = dim / sqrt_area
+    left = (1.0 - ratio) / 2.0
+    # Built with numpy: `np.linspace(..., endpoint=False)` is `start + arange(num) * (stop - start) / num`, which is
+    # not what `torch.linspace` computes, and the float64 grid has to be reproduced exactly.
+    grid = np.linspace(left, left + ratio, dim // patch, endpoint=False) * _ROPE_SPATIAL_SCALE
+    return torch.from_numpy(grid).to(torch.float64)
+
+
+def _temporal_position_grid(num_latent_frames: int, origin: float) -> torch.Tensor:
+    r"""The rotary time of every latent frame, starting at `origin`. Spacing is non-uniform: `5/3 * (1, 4, 4, 4, 4)`."""
+    spans = torch.tensor(
+        [
+            _ROPE_FRAME_RESCALE * _ROPE_FRAMES_PER_LATENT[index % len(_ROPE_FRAMES_PER_LATENT)]
+            for index in range(num_latent_frames)
+        ],
+        dtype=torch.float64,
+    )
+    return origin + torch.cat([torch.zeros(1, dtype=torch.float64), spans[:-1].cumsum(0)])
+
+
+def _temporal_position_span_pairwise(num_latent_frames: int) -> float:
+    r"""
+    The rotary time spanned by `num_latent_frames` latent frames.
+
+    Summed by numpy (pairwise summation) rather than sequentially: the reference computes the keyframe anchor this
+    way and the two summation orders differ in the last ulp from 16 latent frames onwards.
+    """
+    spans = np.ones(num_latent_frames, dtype=np.float64) * _ROPE_FRAME_RESCALE
+    for index in range(len(_ROPE_FRAMES_PER_LATENT)):
+        spans[index :: len(_ROPE_FRAMES_PER_LATENT)] *= _ROPE_FRAMES_PER_LATENT[index]
+    return float(spans.sum())
+
+
+def _temporal_position_span_sequential(num_latent_frames: int) -> float:
+    r"""
+    The rotary time a video reference advances the clock by.
+
+    Summed sequentially in float64, which is *not* how [`_temporal_position_span_pairwise`] sums
+    the same series: that one reproduces a numpy pairwise sum, and the two orders differ in the last ulp from 16
+    latent frames onwards. The reference implementation keeps both, one per call site, so the port has to as well.
+    """
+    return sum(
+        _ROPE_FRAME_RESCALE * _ROPE_FRAMES_PER_LATENT[index % len(_ROPE_FRAMES_PER_LATENT)]
+        for index in range(num_latent_frames)
+    )
+
+
+def _frame_position_grid(
+    latent_height: int, latent_width: int, patch_h: int, patch_w: int
+) -> tuple[torch.Tensor, torch.Tensor]:
+    r"""The `(h, w)` rotary coordinates of one latent frame, and the width axis they were built from."""
+    sqrt_area = np.sqrt(latent_height * latent_width)
+    height_grid = _spatial_position_grid(latent_height, patch_h, sqrt_area)
+    width_grid = _spatial_position_grid(latent_width, patch_w, sqrt_area)
+    grids = torch.meshgrid(height_grid, width_grid, indexing="ij")
+    return torch.stack([grid.reshape(-1) for grid in grids], dim=-1), width_grid
+
+
+def _fill_audio_positions(
+    position_ids: torch.Tensor,
+    rows: slice,
+    num_audio_latents: int,
+    rotary_time: float,
+    width_grid: torch.Tensor,
+) -> None:
+    r"""
+    Place one channel-major audio block.
+
+    Audio rows carry no height coordinate and are pinned to the two extremes of the width grid of *their own* block —
+    the target grid for a standalone audio reference, the video's grid for a soundtrack.
+    """
+    time = rotary_time + torch.arange(num_audio_latents, dtype=torch.float64)
+    position_ids[rows, 0] = time.repeat(MINIMAX_H3_AUDIO_CHANNELS)
+    position_ids[rows, 2] = torch.cat(
+        [
+            torch.full((num_audio_latents,), float(width_grid[0]), dtype=torch.float64),
+            torch.full((num_audio_latents,), float(width_grid[-1]), dtype=torch.float64),
+        ]
+    )
+
+
 class MiniMaxH3PrepareLayoutStep(ModularPipelineBlocks):
     model_name = "minimax-h3"
 
@@ -130,6 +257,104 @@ def intermediate_outputs(self) -> list[OutputParam]:
             ),
         ]
 
+    @staticmethod
+    def build_packed_sequence(
+        text_token_tags: torch.Tensor,
+        num_latent_frames: int,
+        latent_height: int,
+        latent_width: int,
+        num_audio_latents: int,
+        patch_size: tuple[int, int, int],
+        keyframe_anchors: tuple[str, ...] = (),
+    ) -> tuple[torch.Tensor, torch.Tensor, torch.Tensor, torch.Tensor, torch.Tensor, int, int]:
+        r"""
+        Build the `[text | keyframe conditions | target audio | target video]` layout used by the `t2va` and `fl2va`
+        tasks.
+
+        Args:
+            text_token_tags (`torch.Tensor` of shape `(num_text_tokens,)`):
+                The modality tag of every text row. Text is tagged `1`, except for the rows of a keyframe's vision block,
+                which MiniMax-H3 tags `0` (video).
+            num_latent_frames (`int`): Number of target latent frames.
+            latent_height (`int`): Target latent height.
+            latent_width (`int`): Target latent width.
+            num_audio_latents (`int`): Number of target audio latents per channel.
+            patch_size (`tuple[int, int, int]`): The transformer's `(t, h, w)` patch.
+            keyframe_anchors (`tuple[str, ...]`):
+                One entry per keyframe conditioning block, in packed order: `"first"` anchors the block at the first
+                latent frame, `"last"` at the last one.
+
+        Returns:
+            `tuple`: `position_ids`, `token_tags`, `video_indices`, `audio_indices`, `text_indices`, and the number of
+            leading video and audio rows that are conditioning rather than generated.
+        """
+        _, patch_h, patch_w = patch_size
+        rows_per_frame = (latent_height // patch_h) * (latent_width // patch_w)
+        num_text_tokens = text_token_tags.shape[0]
+        num_condition_rows = len(keyframe_anchors) * rows_per_frame
+        num_audio_rows = num_audio_latents * MINIMAX_H3_AUDIO_CHANNELS
+        num_video_rows = num_latent_frames * rows_per_frame
+        sequence_length = num_text_tokens + num_condition_rows + num_audio_rows + num_video_rows
+
+        condition_start = num_text_tokens
+        audio_start = condition_start + num_condition_rows
+        video_start = audio_start + num_audio_rows
+
+        # 1. The (t, h, w) grid. Text rows sit on the time axis at their row index, and the media rows continue the time
+        # axis from there, so text length shifts the whole media clock.
+        position_ids = torch.zeros(sequence_length, 3, dtype=torch.float64)
+        position_ids[:num_text_tokens, 0] = torch.arange(num_text_tokens, dtype=torch.float64)
+
+        sqrt_area = np.sqrt(latent_height * latent_width)
+        height_grid = _spatial_position_grid(latent_height, patch_h, sqrt_area)
+        width_grid = _spatial_position_grid(latent_width, patch_w, sqrt_area)
+        frame_grid = torch.stack(
+            [grid.reshape(-1) for grid in torch.meshgrid(height_grid, width_grid, indexing="ij")], -1
+        )
+
+        for index, anchor in enumerate(keyframe_anchors):
+            if anchor == "first":
+                anchor_time = float(num_text_tokens)
+            elif anchor == "last":
+                anchor_time = (
+                    float(num_text_tokens) + _temporal_position_span_pairwise(num_latent_frames) - _ROPE_FRAME_RESCALE
+                )
+            else:
+                raise ValueError(f"A keyframe anchor must be 'first' or 'last', got {anchor!r}.")
+            rows = slice(condition_start + index * rows_per_frame, condition_start + (index + 1) * rows_per_frame)
+            position_ids[rows, 0] = anchor_time
+            position_ids[rows, 1:] = frame_grid
+
+        # Audio rows are channel-major and share the video's rotary clock: one unit per latent at 40 latents/s equals
+        # 24 fps * 5/3. They carry no height coordinate and are pinned to the two extremes of the width grid.
+        audio_time = float(num_text_tokens) + torch.arange(num_audio_latents, dtype=torch.float64)
+        position_ids[audio_start:video_start, 0] = audio_time.repeat(MINIMAX_H3_AUDIO_CHANNELS)
+        position_ids[audio_start:video_start, 2] = torch.cat(
+            [
+                torch.full((num_audio_latents,), float(width_grid[0]), dtype=torch.float64),
+                torch.full((num_audio_rows - num_audio_latents,), float(width_grid[-1]), dtype=torch.float64),
+            ]
+        )
+
+        video_position_ids = torch.empty(num_latent_frames, rows_per_frame, 3, dtype=torch.float64)
+        video_position_ids[:, :, 0] = _temporal_position_grid(num_latent_frames, float(num_text_tokens))[:, None]
+        video_position_ids[:, :, 1:] = frame_grid[None]
+        position_ids[video_start:] = video_position_ids.reshape(-1, 3)
+
+        # 2. Row indices and modality tags.
+        video_indices = torch.cat(
+            [torch.arange(condition_start, audio_start), torch.arange(video_start, sequence_length)]
+        )
+        audio_indices = torch.arange(audio_start, video_start)
+        text_indices = torch.arange(num_text_tokens)
+
+        token_tags = torch.empty(sequence_length, dtype=torch.long)
+        token_tags[text_indices] = text_token_tags.to(torch.long)
+        token_tags[audio_indices] = MINIMAX_H3_AUDIO_TAG
+        token_tags[video_indices] = MINIMAX_H3_VIDEO_TAG
+
+        return position_ids, token_tags, video_indices, audio_indices, text_indices, num_condition_rows, 0
+
     @torch.no_grad()
     def __call__(self, components: MiniMaxH3ModularPipeline, state: PipelineState) -> PipelineState:
         block_state = self.get_block_state(state)
@@ -180,7 +405,7 @@ def __call__(self, components: MiniMaxH3ModularPipeline, state: PipelineState) -
             text_indices,
             block_state.num_condition_video_rows,
             block_state.num_condition_audio_rows,
-        ) = build_packed_sequence(
+        ) = self.build_packed_sequence(
             block_state.text_token_tags,
             block_state.num_latent_frames,
             block_state.latent_height,
@@ -200,7 +425,7 @@ def __call__(self, components: MiniMaxH3ModularPipeline, state: PipelineState) -
 
 
 class MiniMaxH3Ref2VAPrepareLayoutStep(ModularPipelineBlocks):
-    model_name = "minimax-h3-ref2va"
+    model_name = "minimax-h3"
 
     @property
     def description(self) -> str:
@@ -220,7 +445,7 @@ def inputs(self) -> list[InputParam]:
                 description="The per-row modality tag of every row of `prompt_embeds`.",
             ),
             InputParam(
-                name="prepared_references",
+                name="normalized_references",
                 type_hint=list[MiniMaxH3Reference],
                 required=True,
                 description="The references normalized by the setup step, in packed order.",
@@ -304,13 +529,161 @@ def intermediate_outputs(self) -> list[OutputParam]:
             ),
         ]
 
+    @staticmethod
+    def build_ref2va_packed_sequence(
+        text_token_tags: torch.Tensor,
+        references: list[MiniMaxH3Reference],
+        condition_latents: list[torch.Tensor],
+        audio_condition_latents: list[torch.Tensor],
+        num_latent_frames: int,
+        latent_height: int,
+        latent_width: int,
+        num_audio_latents: int,
+        patch_size: tuple[int, int, int],
+    ) -> tuple[torch.Tensor, torch.Tensor, torch.Tensor, torch.Tensor, torch.Tensor, int, int]:
+        r"""
+        Build the `[text | reference blocks | target audio | target video]` layout of the `ref2va` task.
+
+        Args:
+            text_token_tags (`torch.Tensor` of shape `(num_text_tokens,)`):
+                The modality tag of every text row. Text is tagged `1`, except for the rows of a reference's vision block,
+                which MiniMax-H3 tags `0` (video).
+            references (`list[MiniMaxH3Reference]`):
+                The references, in packed order. Only their modality is read here; the geometry comes from the latents.
+            condition_latents (`list[torch.Tensor]`):
+                One `(1, channels, num_latent_frames, latent_height, latent_width)` tensor per image and video reference,
+                in packed order, as [`MiniMaxH3Ref2VAReferenceEncoderStep`] produced them.
+            audio_condition_latents (`list[torch.Tensor]`):
+                One `(num_audio_latents * 2, audio_latent_channels)` tensor per audio-bearing reference, in packed order.
+            num_latent_frames (`int`): Number of target latent frames.
+            latent_height (`int`): Target latent height.
+            latent_width (`int`): Target latent width.
+            num_audio_latents (`int`): Number of target audio latents per channel.
+            patch_size (`tuple[int, int, int]`): The transformer's `(t, h, w)` patch.
+
+        Returns:
+            `tuple`: `position_ids`, `token_tags`, `video_indices`, `audio_indices`, `text_indices`, and the number of
+            leading video and audio rows that are references rather than generated.
+        """
+        _, patch_h, patch_w = patch_size
+        num_text_tokens = text_token_tags.shape[0]
+        num_target_video_rows = num_latent_frames * (latent_height // patch_h) * (latent_width // patch_w)
+        num_target_audio_rows = num_audio_latents * MINIMAX_H3_AUDIO_CHANNELS
+
+        # The geometry of every reference block is the shape of what the encoder produced for it, so the two can never
+        # disagree. Both lists are in packed order but skip the references they do not apply to, so they are consumed as
+        # iterators alongside the reference list rather than indexed by it.
+        visual_geometry = iter(tuple(latents.shape[2:5]) for latents in condition_latents)
+        audio_row_counts = iter(rows.shape[0] for rows in audio_condition_latents)
+        num_reference_video_rows = sum(
+            frames * (height // patch_h) * (width // patch_w)
+            for frames, height, width in (tuple(latents.shape[2:5]) for latents in condition_latents)
+        )
+        num_reference_audio_rows = sum(rows.shape[0] for rows in audio_condition_latents)
+        sequence_length = (
+            num_text_tokens
+            + num_reference_video_rows
+            + num_reference_audio_rows
+            + num_target_audio_rows
+            + num_target_video_rows
+        )
+
+        position_ids = torch.zeros(sequence_length, 3, dtype=torch.float64)
+        position_ids[:num_text_tokens, 0] = torch.arange(num_text_tokens, dtype=torch.float64)
+        target_frame_grid, target_width_grid = _frame_position_grid(latent_height, latent_width, patch_h, patch_w)
+
+        # Reference blocks, in request order. `rotary_time` is the shared audio/video clock: it starts where the text
+        # rows end and every block pushes it forward by the time that block occupies.
+        video_indices, audio_indices = [], []
+        cursor = num_text_tokens
+        rotary_time = float(num_text_tokens)
+        for reference in references:
+            if reference.kind == "image":
+                num_latent_frames_, reference_height, reference_width = next(visual_geometry)
+                num_video_rows = num_latent_frames_ * (reference_height // patch_h) * (reference_width // patch_w)
+                rows = slice(cursor, cursor + num_video_rows)
+                cursor = rows.stop
+                video_indices.append(torch.arange(rows.start, rows.stop))
+                frame_grid, _ = _frame_position_grid(reference_height, reference_width, patch_h, patch_w)
+                position_ids[rows, 0] = rotary_time
+                position_ids[rows, 1:] = frame_grid
+                # An image is a single frame and takes a single integer rotary slot, not a latent frame's 5/3 units.
+                rotary_time += 1.0
+            elif reference.kind == "audio":
+                num_audio_rows = next(audio_row_counts)
+                reference_audio_latents = num_audio_rows // MINIMAX_H3_AUDIO_CHANNELS
+                rows = slice(cursor, cursor + num_audio_rows)
+                cursor = rows.stop
+                audio_indices.append(torch.arange(rows.start, rows.stop))
+                _fill_audio_positions(position_ids, rows, reference_audio_latents, rotary_time, target_width_grid)
+                rotary_time += float(reference_audio_latents)
+            elif reference.kind == "video":
+                # A video reference's soundtrack rows are packed immediately before its video rows and share their
+                # origin, so the two are rotary-aligned exactly as the generated audio and video are.
+                num_audio_rows = next(audio_row_counts) if reference.has_audio else 0
+                reference_audio_latents = num_audio_rows // MINIMAX_H3_AUDIO_CHANNELS
+                num_latent_frames_, reference_height, reference_width = next(visual_geometry)
+                num_video_rows = num_latent_frames_ * (reference_height // patch_h) * (reference_width // patch_w)
+                audio_rows = slice(cursor, cursor + num_audio_rows)
+                video_rows = slice(audio_rows.stop, audio_rows.stop + num_video_rows)
+                cursor = video_rows.stop
+                audio_indices.append(torch.arange(audio_rows.start, audio_rows.stop))
+                video_indices.append(torch.arange(video_rows.start, video_rows.stop))
+
+                frame_grid, width_grid = _frame_position_grid(reference_height, reference_width, patch_h, patch_w)
+                _fill_audio_positions(position_ids, audio_rows, reference_audio_latents, rotary_time, width_grid)
+                frame_time = _temporal_position_grid(num_latent_frames_, rotary_time)
+                position_ids[video_rows, 0] = frame_time.repeat_interleave(frame_grid.shape[0])
+                position_ids[video_rows, 1:] = frame_grid.repeat(num_latent_frames_, 1)
+                rotary_time += max(
+                    float(reference_audio_latents), _temporal_position_span_sequential(num_latent_frames_)
+                )
+            else:
+                raise ValueError(f"A reference must be an 'image', a 'video' or an 'audio', got {reference.kind!r}.")
+
+        # The generated rows. Target audio and target video share the origin the reference blocks left behind.
+        audio_start = cursor
+        video_start = audio_start + num_target_audio_rows
+        _fill_audio_positions(
+            position_ids, slice(audio_start, video_start), num_audio_latents, rotary_time, target_width_grid
+        )
+        frame_time = _temporal_position_grid(num_latent_frames, rotary_time)
+        position_ids[video_start:, 0] = frame_time.repeat_interleave(target_frame_grid.shape[0])
+        position_ids[video_start:, 1:] = target_frame_grid.repeat(num_latent_frames, 1)
+
+        video_indices = torch.cat(video_indices + [torch.arange(video_start, sequence_length)])
+        audio_indices = torch.cat(audio_indices + [torch.arange(audio_start, video_start)])
+        text_indices = torch.arange(num_text_tokens)
+
+        token_tags = torch.empty(sequence_length, dtype=torch.long)
+        token_tags[text_indices] = text_token_tags.to(torch.long)
+        token_tags[audio_indices] = MINIMAX_H3_AUDIO_TAG
+        token_tags[video_indices] = MINIMAX_H3_VIDEO_TAG
+
+        return (
+            position_ids,
+            token_tags,
+            video_indices,
+            audio_indices,
+            text_indices,
+            num_reference_video_rows,
+            num_reference_audio_rows,
+        )
+
     @torch.no_grad()
-    def __call__(self, components: MiniMaxH3Ref2VAModularPipeline, state: PipelineState) -> PipelineState:
+    def __call__(self, components: MiniMaxH3ModularPipeline, state: PipelineState) -> PipelineState:
         block_state = self.get_block_state(state)
         device = components._execution_device
 
-        # The canvas and the frame count are settled by the setup step: a `ref2va` soundtrack is truncated to the
-        # generated duration as the references are prepared, so `num_frames` has to be final before that runs.
+        # The canvas and the frame count are settled by the setup step, but in a hand-assembled chain this block
+        # sees user input directly — and a canvas off the multiple floor-divides into a broken decode.
+        multiple = components.canvas_multiple
+        if block_state.height % multiple or block_state.width % multiple:
+            raise ValueError(
+                f"`height` and `width` must be multiples of {multiple}, got {block_state.height}x{block_state.width}."
+            )
+        # A `ref2va` soundtrack is truncated to the generated duration as the references are prepared, so
+        # `num_frames` has to be final before the setup step runs.
         ratio = components.vae_spatial_compression_ratio
         block_state.num_latent_frames = video_latent_num_frames(
             block_state.num_frames, components.vae_frames_per_chunk, components.vae_latents_per_chunk
@@ -327,9 +700,9 @@ def __call__(self, components: MiniMaxH3Ref2VAModularPipeline, state: PipelineSt
             text_indices,
             block_state.num_condition_video_rows,
             block_state.num_condition_audio_rows,
-        ) = build_ref2va_packed_sequence(
+        ) = self.build_ref2va_packed_sequence(
             block_state.text_token_tags,
-            block_state.prepared_references,
+            block_state.normalized_references,
             block_state.condition_latents,
             block_state.audio_condition_latents,
             block_state.num_latent_frames,
@@ -402,6 +775,12 @@ def inputs(self) -> list[InputParam]:
                 default=0,
                 description="How many conditioning rows the layout reserved, which the packed conditioning must match.",
             ),
+            InputParam(
+                name="num_condition_audio_rows",
+                type_hint=int,
+                default=0,
+                description="How many reference audio rows the layout reserved, which the packed rows must match.",
+            ),
             InputParam(
                 name="condition_latents",
                 type_hint=list[torch.Tensor],
@@ -503,9 +882,14 @@ def __call__(self, components: MiniMaxH3ModularPipeline, state: PipelineState) -
         if condition_rows is not None:
             video_rows = torch.cat([condition_rows, video_rows])
         if block_state.audio_condition_latents:
-            audio_rows = torch.cat(
-                [rows.to(device) for rows in block_state.audio_condition_latents] + [audio_rows]
-            )
+            num_reference_audio_rows = sum(rows.shape[0] for rows in block_state.audio_condition_latents)
+            if num_reference_audio_rows != block_state.num_condition_audio_rows:
+                raise ValueError(
+                    f"The layout reserved {block_state.num_condition_audio_rows} reference audio rows but the encoded "
+                    f"soundtracks pack into {num_reference_audio_rows}. The references the layout was built from and "
+                    "the ones the audio conditioning was encoded from do not agree."
+                )
+            audio_rows = torch.cat([rows.to(device) for rows in block_state.audio_condition_latents] + [audio_rows])
         block_state.latents, block_state.audio_latents = video_rows, audio_rows
 
         self.set_block_state(state, block_state)
@@ -582,6 +966,47 @@ def intermediate_outputs(self) -> list[OutputParam]:
             ),
         ]
 
+    @staticmethod
+    def build_row_timesteps(
+        video_indices: torch.Tensor,
+        audio_indices: torch.Tensor,
+        num_condition_video_rows: int,
+        num_condition_audio_rows: int,
+        num_text_tokens: int,
+        video_timestep: float,
+        audio_timestep: float,
+        condition_video_timestep: float,
+        condition_audio_timestep: float,
+    ) -> tuple[torch.Tensor, torch.Tensor]:
+        r"""
+        Assign a timestep to every row of the packed sequence and reduce it to the transformer's `(timestep,
+        timestep_indices)` pair.
+
+        One forward serves rows at different noise levels: the generated video and audio rows step down their own
+        schedules while the conditioning rows stay pinned at their noise-augmentation level. Text rows never reach an
+        output head and inherit the video timestep.
+
+        Args:
+            video_indices (`torch.Tensor`): Sequence positions of the video rows, conditioning rows first.
+            audio_indices (`torch.Tensor`): Sequence positions of the audio rows, reference rows first.
+            num_condition_video_rows (`int`): How many leading video rows are conditioning rows.
+            num_condition_audio_rows (`int`): How many leading audio rows are reference rows.
+            num_text_tokens (`int`): Number of text rows, which never reach an output head.
+            video_timestep (`float`): Timestep of the generated video rows.
+            audio_timestep (`float`): Timestep of the generated audio rows.
+            condition_video_timestep (`float`): Timestep of the video conditioning rows.
+            condition_audio_timestep (`float`): Timestep of the audio reference rows.
+
+        Returns:
+            `tuple[torch.Tensor, torch.Tensor]`: the distinct timesteps, sorted, and the index of every row into them.
+        """
+        sequence_length = int(video_indices.numel() + audio_indices.numel() + num_text_tokens)
+        row_timesteps = torch.full((sequence_length,), video_timestep, dtype=torch.float32)
+        row_timesteps[video_indices[:num_condition_video_rows]] = condition_video_timestep
+        row_timesteps[audio_indices[num_condition_audio_rows:]] = audio_timestep
+        row_timesteps[audio_indices[:num_condition_audio_rows]] = condition_audio_timestep
+        return torch.unique(row_timesteps, sorted=True, return_inverse=True)
+
     @torch.no_grad()
     def __call__(self, components: MiniMaxH3ModularPipeline, state: PipelineState) -> PipelineState:
         block_state = self.get_block_state(state)
@@ -595,7 +1020,7 @@ def __call__(self, components: MiniMaxH3ModularPipeline, state: PipelineState) -
         block_state.row_timestep_plan = [
             tuple(
                 tensor.to(device)
-                for tensor in build_row_timesteps(
+                for tensor in self.build_row_timesteps(
                     block_state.video_indices,
                     block_state.audio_indices,
                     block_state.num_condition_video_rows,
diff --git a/src/diffusers/modular_pipelines/minimax_h3/before_encoder.py b/src/diffusers/modular_pipelines/minimax_h3/before_encoder.py
index 41eee332faf4..d1f4690daf12 100644
--- a/src/diffusers/modular_pipelines/minimax_h3/before_encoder.py
+++ b/src/diffusers/modular_pipelines/minimax_h3/before_encoder.py
@@ -12,31 +12,29 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+import math
+
+import numpy as np
 import PIL
 import torch
-from PIL import Image, ImageOps
+from PIL import Image
 
 from ...configuration_utils import FrozenDict
 from ...image_processor import VaeImageProcessor
 from ...utils import logging
 from ..modular_pipeline import ModularPipelineBlocks, PipelineState
 from ..modular_pipeline_utils import ComponentSpec, InputParam, OutputParam
-from .modular_pipeline import MiniMaxH3ModularPipeline, MiniMaxH3Ref2VAModularPipeline
-from .packing import (
+from .modular_pipeline import (
+    MINIMAX_H3_FPS,
+    MiniMaxH3ModularPipeline,
     align_num_frames,
     resolve_canvas_size,
 )
-from .packing_ref2va import (
+from .references import (
     MiniMaxH3AudioReference,
     MiniMaxH3ImageReference,
     MiniMaxH3Reference,
     MiniMaxH3VideoReference,
-    prepare_reference_frames,
-    prepare_reference_image,
-    prepare_reference_waveform,
-    reference_media_to_uint8,
-    resample_reference_frames,
-    resolve_reference_image_size,
 )
 
 
@@ -119,9 +117,7 @@ def __call__(self, components: MiniMaxH3ModularPipeline, state: PipelineState) -
             if keyframe is not None
         )
         if block_state.height is None:
-            block_state.height, block_state.width = resolve_canvas_size(
-                *keyframes[0].size, components.canvas_multiple
-            )
+            block_state.height, block_state.width = resolve_canvas_size(*keyframes[0].size, components.canvas_multiple)
 
         prepared = []
         for index, keyframe in enumerate(keyframes):
@@ -155,96 +151,55 @@ def __call__(self, components: MiniMaxH3ModularPipeline, state: PipelineState) -
 
 
 class MiniMaxH3Ref2VASetupStep(ModularPipelineBlocks):
-    model_name = "minimax-h3-ref2va"
+    model_name = "minimax-h3"
 
     def __init__(
-        self, max_images: int = 9, max_videos: int = 3, max_audios: int = 3, max_references: int = 12
+        self,
+        max_images: int = 9,
+        max_videos: int = 3,
+        max_audios: int = 3,
+        max_references: int = 12,
+        reference_image_short_edge: int = 2048,
     ):
         r"""
-        Resolve a `ref2va` request's plan.
+        Resolve a `ref2va` request's plan and normalize its references onto MiniMax-H3's own rates and resolutions.
 
         Args:
             max_images (`int`, defaults to 9): Image references a request may carry.
             max_videos (`int`, defaults to 3): Video references a request may carry.
             max_audios (`int`, defaults to 3): Audio references a request may carry.
             max_references (`int`, defaults to 12): References of any modality a request may carry in total.
+            reference_image_short_edge (`int`, defaults to 2048):
+                The short edge an image reference is resized to, upscaling included.
 
-        The four limits are what MiniMax-H3 documents for the released checkpoint; they bound nothing but this
-        block's own validation, so a fine-tune that packs more can raise them.
+        The limits are what MiniMax-H3 documents for the released checkpoint; they bound nothing but this block's own
+        validation, so a fine-tune that packs more can raise them.
         """
         self.max_images = max_images
         self.max_videos = max_videos
         self.max_audios = max_audios
         self.max_references = max_references
+        self.reference_image_short_edge = reference_image_short_edge
         super().__init__()
 
     @property
     def description(self) -> str:
         return (
-            "Resolves the `ref2va` plan: the canvas (MiniMax-H3's own 16:9 unless asked otherwise — references never "
-            "bind the generated geometry), the references prepared at their own resolutions, the frame count they "
-            "imply when it was left open, and the latent geometry every later block keys off."
-        )
-
-    def _check_inputs(self, components, block_state) -> None:
-        if (block_state.height is None) != (block_state.width is None):
-            raise ValueError("`height` and `width` have to be passed together, or neither of them.")
-        multiple = components.canvas_multiple
-        if block_state.height is not None and (block_state.height % multiple or block_state.width % multiple):
-            raise ValueError(
-                f"`height` and `width` must be multiples of {multiple}, got "
-                f"{block_state.height}x{block_state.width}."
-            )
-        # The duration the request generates is the one of the *aligned* frame count, so that is what the ceiling has
-        # to hold for: 346 frames would otherwise pass the check and then be rounded up to 362, i.e. 15.083 seconds.
-        aligned_num_frames = (
-            None
-            if block_state.num_frames is None
-            else align_num_frames(
-                block_state.num_frames, components.vae_frames_per_chunk, components.vae_latents_per_chunk
-            )
+            "Resolves the `ref2va` plan — the canvas (MiniMax-H3's own 16:9 unless asked otherwise; references never "
+            "bind the generated geometry) and the `17 * n + 5` frame count — and normalizes every reference onto "
+            "MiniMax-H3's own rates and resolutions."
         )
-        duration = None if aligned_num_frames is None else aligned_num_frames / components.fps
-        if duration is not None and not components.min_duration <= duration <= components.max_duration:
-            raise ValueError(
-                f"MiniMax-H3 generates between {components.min_duration} and {components.max_duration} seconds at "
-                f"{components.fps} fps, so `num_frames`, rounded up to the next `17 * n + 5` the video VAE can "
-                f"encode, must be between {int(components.min_duration * components.fps)} and "
-                f"{int(components.max_duration * components.fps)}, got {block_state.num_frames} (rounded up to "
-                f"{aligned_num_frames})."
-            )
 
-        if not block_state.references:
-            raise ValueError(
-                "`ref2va` needs at least one reference; use `MiniMaxH3ModularPipeline` for text-only requests."
-            )
-        for index, entry in enumerate(block_state.references):
-            if not isinstance(entry, MiniMaxH3Reference):
-                raise ValueError(
-                    f"`references[{index}]` must be a [`MiniMaxH3ImageReference`], [`MiniMaxH3VideoReference`] or "
-                    f"[`MiniMaxH3AudioReference`], got {type(entry)}. MiniMax-H3 blocks never open media files, so a "
-                    "request that holds paths decodes them first — with "
-                    "[`~modular_pipelines.minimax_h3.decode_reference_video`] and "
-                    "[`~modular_pipelines.minimax_h3.decode_reference_audio`], or by putting a "
-                    "[`MiniMaxH3Ref2VALoadReferencesStep`] in front of these blocks."
-                )
-        kinds = [entry.kind for entry in block_state.references]
-        for kind, limit in (
-            ("image", self.max_images),
-            ("video", self.max_videos),
-            ("audio", self.max_audios),
-        ):
-            if kinds.count(kind) > limit:
-                raise ValueError(f"MiniMax-H3 accepts at most {limit} {kind} references, got {kinds.count(kind)}.")
-        if len(kinds) > self.max_references:
-            raise ValueError(
-                f"MiniMax-H3 accepts at most {self.max_references} references in total, got {len(kinds)}."
-            )
-        if set(kinds) == {"audio"}:
-            raise ValueError(
-                "An audio reference has to be paired with at least one image or video reference and cannot be used "
-                "on its own."
-            )
+    @property
+    def expected_components(self) -> list[ComponentSpec]:
+        return [
+            ComponentSpec(
+                "image_processor",
+                VaeImageProcessor,
+                config=FrozenDict({"vae_scale_factor": 16}),
+                default_creation_method="from_config",
+            ),
+        ]
 
     @property
     def inputs(self) -> list[InputParam]:
@@ -271,10 +226,11 @@ def inputs(self) -> list[InputParam]:
             InputParam(
                 name="num_frames",
                 type_hint=int,
+                required=True,
                 description=(
                     "Number of frames to generate, at the fixed 24 fps. Snapped up to the next `17 * n + 5` the video "
-                    "VAE can decode. May be left out, but only when exactly one reference carries audio, in which "
-                    "case the duration is that soundtrack's."
+                    "VAE can decode; the resulting duration must stay between 5 and 15 seconds. To generate a video "
+                    "as long as a reference soundtrack, pass `round(samples / sample_rate * 24)`."
                 ),
             ),
         ]
@@ -286,133 +242,222 @@ def intermediate_outputs(self) -> list[OutputParam]:
             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."),
             OutputParam(
-                "prepared_references",
+                "normalized_references",
                 type_hint=list[MiniMaxH3Reference],
                 description=(
                     "The references normalized onto MiniMax-H3's own rates and resolutions, in packed order: the "
-                    "same public reference types the request passed in, with an image resized to its own 2048 pixel "
-                    "short edge, a video resampled onto 24 fps and onto the canvas its own aspect ratio resolves "
-                    "to, and a soundtrack put on the audio VAE's sample rate and truncated to the generated "
+                    "same public reference types the request passed in, with an image resized to its own "
+                    "2048 pixel short edge, a video resampled onto 24 fps and onto the canvas its own aspect ratio "
+                    "resolves to, and a soundtrack put on the audio VAE's sample rate and truncated to the generated "
                     "duration."
                 ),
             ),
         ]
 
     @staticmethod
-    def prepare_references(
-        components, references: list[MiniMaxH3Reference], num_frames: int | None
-    ) -> tuple[list[MiniMaxH3Reference], int]:
+    def _normalize_video_condition(frames, fps: float, num_frames: int, canvas_multiple: int) -> np.ndarray:
         r"""
-        Resolve the references and, if it was left open, the duration they imply.
+        Normalize a video reference's frames: any accepted layout, onto `uint8` at 24 fps, truncated to the generated
+        frame count, on the canvas its own aspect ratio resolves to.
+
+        The two passes reproduce the reference implementation's `ffmpeg` decode, in the same order: the constant frame
+        rate resample first (dropping and duplicating whole frames, as `ffmpeg`'s `fps` filter does), the LANCZOS
+        rescale second. Frames handed over at 24 fps and already at the canvas their own aspect ratio resolves to flow
+        through untouched, which is the parity-exact route: the reference rescaled with `ffmpeg`'s own LANCZOS while
+        decoding, so only frames decoded at the canvas reproduce its pixels bit for bit.
 
-        Every reference is prepared at its own resolution: an image is resized to a 2048 pixel short edge, a video is
-        resampled onto MiniMax-H3's own 24 fps, rescaled onto the 768 pixel canvas of *its own* aspect ratio and
-        truncated to the generated frame count, and a soundtrack is put on the audio VAE's sample rate and truncated to
-        the generated duration. None of this touches the target canvas.
+        Args:
+            frames (`list[PIL.Image.Image]`, `np.ndarray` or `torch.Tensor`):
+                The reference frames: a list of images, a `(num_frames, height, width, 3)` array or a
+                `(num_frames, 3, height, width)` tensor, `uint8` or floating point over `[0, 1]`.
+            fps (`float`): The frame rate `frames` carries.
+            num_frames (`int`): The generated frame count the reference is truncated to.
+            canvas_multiple (`int`): What both canvas axes round to, i.e. `components.canvas_multiple`.
+
+        Returns:
+            `np.ndarray` of shape `(num_frames, height, width, 3)`: the normalized `uint8` RGB frames.
+        """
+        # Any accepted layout onto `uint8` THWC. A `torch.Tensor` is channels-first, as everywhere else in
+        # diffusers, and a `np.ndarray` channels-last; floating point values are read over `[0, 1]`.
+        if isinstance(frames, list):
+            frames = np.stack([np.asarray(frame.convert("RGB")) for frame in frames])
+        if isinstance(frames, torch.Tensor):
+            frames = frames.movedim(-3, -1).cpu().numpy()
+        frames = np.asarray(frames)
+        if frames.dtype != np.uint8:
+            frames = (frames * 255.0).round().clip(0, 255).astype(np.uint8)
+        if frames.ndim != 4 or frames.shape[3] != 3:
+            raise ValueError(
+                f"A reference video must be `(num_frames, height, width, 3)` RGB frames, got {tuple(frames.shape)}."
+            )
+
+        # Onto MiniMax-H3's 24 fps grid: every frame is held until the slot of the next one, and the last one until
+        # the slot the stream's end rounds to.
+        if fps <= 0:
+            raise ValueError(f"A reference video must have a positive frame rate, got {fps}.")
+        if fps != MINIMAX_H3_FPS:
+            scale = MINIMAX_H3_FPS / fps
+            slots = np.floor(np.arange(frames.shape[0]) * scale + 0.5).astype(np.int64)
+            frames = np.repeat(frames, np.diff(slots, append=math.floor(frames.shape[0] * scale + 0.5)), axis=0)
+
+        # Truncated to the generated frame count and put on the canvas of its *own* aspect ratio — the same rule the
+        # target canvas follows, unlike an image reference.
+        frames = frames[:num_frames]
+        height, width = resolve_canvas_size(frames.shape[2], frames.shape[1], canvas_multiple)
+        if frames.shape[1:3] == (height, width):
+            return frames
+        return np.stack(
+            [np.asarray(Image.fromarray(frame).resize((width, height), Image.Resampling.LANCZOS)) for frame in frames]
+        )
 
-        A reference that left its `fps` or its `sample_rate` out is taken to already be at MiniMax-H3's own rate, and
-        its frames or its samples then flow through untouched. Decoding a file with
-        [`~modular_pipelines.minimax_h3.decode_reference_video`] or
-        [`~modular_pipelines.minimax_h3.decode_reference_audio`] fills both in from the container.
+    @staticmethod
+    def _normalize_audio_condition(
+        waveform: torch.Tensor, sample_rate: int, target_sample_rate: int, max_duration: float
+    ) -> torch.Tensor:
+        r"""
+        Normalize a reference soundtrack onto the audio VAE's sample rate, as a stereo waveform.
 
-        A video reference goes through the two passes the reference implementation's `ffmpeg` decode applied, in the
-        same order: the constant frame rate resample of `resample_reference_frames` and the LANCZOS rescale of
-        `prepare_reference_frames`. Frames handed over at 24 fps and already at the canvas their own aspect ratio
-        resolves to therefore reach the VAE untouched, which is the parity-exact route.
+        The reference implementation extracts a soundtrack at a native rate, truncates it there and resamples it once,
+        in torch, which this mirrors: the truncation is applied at `sample_rate` and the resampling is a single
+        `torchaudio` pass. A mono waveform is upmixed by repeating its channel.
 
         Args:
-            references (`list[MiniMaxH3Reference]`):
-                The `references` input of a [`MiniMaxH3Ref2VABlocks`] request.
-            num_frames (`int`, *optional*):
-                The requested frame count, or `None` to derive it from the single audio-bearing reference.
+            waveform (`torch.Tensor` of shape `(channels, num_samples)`): The soundtrack, mono or stereo.
+            sample_rate (`int`): The sample rate `waveform` carries its samples at.
+            target_sample_rate (`int`): The audio VAE's sample rate, i.e. what the waveform is resampled to.
+            max_duration (`float`): Truncate the reference to this many seconds.
 
         Returns:
-            `tuple[list[MiniMaxH3Reference], int]`: the references normalized onto MiniMax-H3's own rates and
-            resolutions, in packed order and of the same public types they came in as, and the frame count.
+            `torch.Tensor` of shape `(2, num_samples)`: the float32 waveform.
         """
-        # The duration may be left open, but then exactly one reference may carry audio, or the request is ambiguous.
-        if num_frames is None:
-            audio_bearing = [index for index, reference in enumerate(references) if reference.has_audio]
-            if len(audio_bearing) != 1:
-                raise ValueError(
-                    "`num_frames` may only be left to the references when exactly one of them carries audio, got "
-                    f"{len(audio_bearing)}."
-                )
-            index = audio_bearing[0]
-            sample_rate = references[index].sample_rate
-            if sample_rate is None:
-                sample_rate = components.audio_sampling_rate
-            duration = references[index].audio.shape[-1] / sample_rate
-            if not components.min_duration <= duration <= components.max_duration:
-                raise ValueError(
-                    f"`references[{index}]` is {duration:g} seconds long, outside the "
-                    f"{components.min_duration} to {components.max_duration} seconds MiniMax-H3 generates."
-                )
-            num_frames = align_num_frames(
-                round(duration * components.fps), components.vae_frames_per_chunk, components.vae_latents_per_chunk
+        waveform = torch.as_tensor(waveform)
+        if waveform.ndim != 2 or waveform.shape[0] not in (1, 2):
+            raise ValueError(
+                "A reference soundtrack must be a `(channels, num_samples)` mono or stereo waveform, got "
+                f"{tuple(waveform.shape)}."
+            )
+        waveform = waveform.to(torch.float32)[:, : int(max_duration * sample_rate)]
+        if waveform.shape[0] != 2:
+            waveform = waveform.expand(2, -1).contiguous()
+        if sample_rate == target_sample_rate:
+            return waveform
+
+        try:
+            import torchaudio
+        except ImportError as error:
+            raise ImportError(
+                f"Resampling a MiniMax-H3 reference soundtrack from {sample_rate} Hz to {target_sample_rate} Hz "
+                "needs `torchaudio`. Pass a waveform already at the audio VAE's sample rate to do without it."
+            ) from error
+        return torchaudio.transforms.Resample(sample_rate, target_sample_rate)(waveform)
+
+    @torch.no_grad()
+    def __call__(self, components: MiniMaxH3ModularPipeline, state: PipelineState) -> PipelineState:
+        block_state = self.get_block_state(state)
+
+        # 1. Validate the request.
+        if (block_state.height is None) != (block_state.width is None):
+            raise ValueError("`height` and `width` have to be passed together, or neither of them.")
+        multiple = components.canvas_multiple
+        if block_state.height is not None and (block_state.height % multiple or block_state.width % multiple):
+            raise ValueError(
+                f"`height` and `width` must be multiples of {multiple}, got {block_state.height}x{block_state.width}."
             )
-            # The duration the request generates is the one of the *aligned* frame count, so that is what the
-            # ceiling has to hold for: a 14.99 second soundtrack rounds up to 362 frames, i.e. 15.083 seconds.
-            if num_frames / components.fps > components.max_duration:
+        if not block_state.references:
+            raise ValueError("`ref2va` needs at least one reference; use the `t2va` workflow for text-only requests.")
+        for index, entry in enumerate(block_state.references):
+            if not isinstance(entry, MiniMaxH3Reference):
                 raise ValueError(
-                    f"`references[{index}]` is {duration:g} seconds long, which rounds up to {num_frames} frames "
-                    f"(`17 * n + 5`), i.e. {num_frames / components.fps:g} seconds — past the "
-                    f"{components.max_duration} seconds MiniMax-H3 generates. Pass `num_frames` to generate a "
-                    "shorter video from this soundtrack."
+                    f"`references[{index}]` must be a [`MiniMaxH3ImageReference`], [`MiniMaxH3VideoReference`] or "
+                    f"[`MiniMaxH3AudioReference`], got {type(entry)}. MiniMax-H3 blocks never open media files, so a "
+                    "request that holds paths decodes them first — with "
+                    "[`~modular_pipelines.minimax_h3.decode_reference_video`] and "
+                    "[`~modular_pipelines.minimax_h3.decode_reference_audio`], or by putting a "
+                    "[`MiniMaxH3Ref2VALoadReferencesStep`] in front of these blocks."
                 )
-        num_frames = align_num_frames(num_frames, components.vae_frames_per_chunk, components.vae_latents_per_chunk)
+        kinds = [entry.kind for entry in block_state.references]
+        for kind, limit in (("image", self.max_images), ("video", self.max_videos), ("audio", self.max_audios)):
+            if kinds.count(kind) > limit:
+                raise ValueError(f"MiniMax-H3 accepts at most {limit} {kind} references, got {kinds.count(kind)}.")
+        if len(kinds) > self.max_references:
+            raise ValueError(
+                f"MiniMax-H3 accepts at most {self.max_references} references in total, got {len(kinds)}."
+            )
+        if set(kinds) == {"audio"}:
+            raise ValueError(
+                "An audio reference has to be paired with at least one image or video reference and cannot be used "
+                "on its own."
+            )
 
-        prepared = []
-        for entry in references:
+        # 2. Resolve the canvas and the frame count. The duration the request generates is the one of the *aligned*
+        # frame count, so that is what the ceiling holds for: 346 frames would otherwise pass the check and then be
+        # rounded up to 362, i.e. 15.083 seconds.
+        if block_state.height is None:
+            block_state.height, block_state.width = resolve_canvas_size(16, 9, multiple)
+        aligned_num_frames = align_num_frames(
+            block_state.num_frames, components.vae_frames_per_chunk, components.vae_latents_per_chunk
+        )
+        duration = aligned_num_frames / components.fps
+        if not components.min_duration <= duration <= components.max_duration:
+            raise ValueError(
+                f"MiniMax-H3 generates between {components.min_duration} and {components.max_duration} seconds at "
+                f"{components.fps} fps, so `num_frames`, rounded up to the next `17 * n + 5` the video VAE can "
+                f"encode, must be between {int(components.min_duration * components.fps)} and "
+                f"{int(components.max_duration * components.fps)}, got {block_state.num_frames} (rounded up to "
+                f"{aligned_num_frames})."
+            )
+        if aligned_num_frames != block_state.num_frames:
+            logger.warning(
+                f"`num_frames` has to be of the form 17 * n + 5 for the video VAE; rounding {block_state.num_frames} "
+                f"up to {aligned_num_frames}."
+            )
+        block_state.num_frames = aligned_num_frames
+
+        # 3. Normalize the media, in packed order.
+        normalized = []
+        for entry in block_state.references:
             waveform = None
             if entry.has_audio:
                 sample_rate = entry.sample_rate
                 if sample_rate is None:
                     sample_rate = components.audio_sampling_rate
-                waveform = prepare_reference_waveform(
+                waveform = self._normalize_audio_condition(
                     entry.audio,
                     sample_rate,
                     components.audio_sampling_rate,
-                    max_duration=num_frames / components.fps,
+                    max_duration=block_state.num_frames / components.fps,
                 )
 
             if entry.kind == "image":
-                image = ImageOps.exif_transpose(entry.image).convert("RGB")
-                height, width = resolve_reference_image_size(*image.size, components.canvas_multiple)
-                prepared.append(MiniMaxH3ImageReference(image=prepare_reference_image(image, height, width)))
+                # Images are encoded at high detail — a 2048 pixel short edge, upscaling included, with *no* area
+                # cap — unlike video references and the target itself, which share the one canvas rule. Expected in
+                # RGB, as `load_image` returns.
+                image = entry.image
+                if image.size[0] <= 0 or image.size[1] <= 0:
+                    raise ValueError(f"A reference image must have a positive size, got {image.size}.")
+                width, height = image.size
+                if width > 4 * height or height > 4 * width:
+                    raise ValueError(f"A reference image must be within 1:4 and 4:1, got {width}x{height}.")
+                scale = self.reference_image_short_edge / min(width, height)
+                target_height = max(multiple, round(height * scale / multiple) * multiple)
+                target_width = max(multiple, round(width * scale / multiple) * multiple)
+                if image.size != (target_width, target_height):
+                    image = components.image_processor.resize(image, height=target_height, width=target_width)
+                normalized.append(MiniMaxH3ImageReference(image=image))
             elif entry.kind == "video":
-                frames = resample_reference_frames(reference_media_to_uint8(entry.frames), float(entry.fps))
-                prepared.append(
+                normalized.append(
                     MiniMaxH3VideoReference(
-                        frames=prepare_reference_frames(frames, num_frames, components.canvas_multiple),
+                        frames=self._normalize_video_condition(
+                            entry.frames, float(entry.fps), block_state.num_frames, multiple
+                        ),
                         fps=float(components.fps),
                         audio=waveform,
                         sample_rate=None if waveform is None else components.audio_sampling_rate,
                     )
                 )
             else:
-                prepared.append(
-                    MiniMaxH3AudioReference(audio=waveform, sample_rate=components.audio_sampling_rate)
-                )
-        return prepared, num_frames
-
-    @torch.no_grad()
-    def __call__(self, components: MiniMaxH3Ref2VAModularPipeline, state: PipelineState) -> PipelineState:
-        block_state = self.get_block_state(state)
-        self._check_inputs(components, block_state)
-
-        if block_state.height is None:
-            block_state.height, block_state.width = resolve_canvas_size(16, 9, components.canvas_multiple)
-
-        requested_num_frames = block_state.num_frames
-        block_state.prepared_references, block_state.num_frames = self.prepare_references(
-            components, block_state.references, block_state.num_frames
-        )
-        if requested_num_frames is not None and requested_num_frames != block_state.num_frames:
-            logger.warning(
-                f"`num_frames` has to be of the form 17 * n + 5 for the video VAE; rounding {requested_num_frames} up "
-                f"to {block_state.num_frames}."
-            )
+                normalized.append(MiniMaxH3AudioReference(audio=waveform, sample_rate=components.audio_sampling_rate))
+        block_state.normalized_references = normalized
 
         self.set_block_state(state, block_state)
         return components, state
diff --git a/src/diffusers/modular_pipelines/minimax_h3/denoise.py b/src/diffusers/modular_pipelines/minimax_h3/denoise.py
index 156242907339..2f2ce59bfda6 100644
--- a/src/diffusers/modular_pipelines/minimax_h3/denoise.py
+++ b/src/diffusers/modular_pipelines/minimax_h3/denoise.py
@@ -26,7 +26,7 @@
     PipelineState,
 )
 from ..modular_pipeline_utils import ComponentSpec, InputParam, OutputParam
-from .modular_pipeline import MiniMaxH3ModularPipeline, MiniMaxH3Ref2VAModularPipeline
+from .modular_pipeline import MiniMaxH3ModularPipeline
 
 
 logger = logging.get_logger(__name__)  # pylint: disable=invalid-name
@@ -35,6 +35,19 @@
 class MiniMaxH3LoopDenoiser(ModularPipelineBlocks):
     model_name = "minimax-h3"
 
+    def __init__(self, transformer_name: str = "transformer"):
+        r"""
+        Run the one MiniMax-H3 forward pass of a denoising iteration.
+
+        Args:
+            transformer_name (`str`, defaults to `"transformer"`):
+                The component the forward runs against. One repository holds both checkpoint partitions —
+                `transformer/` for `t2va`/`fl2va` and `transformer_ref/` for `ref2va` — under different component
+                names, so which partition a loop drives is configuration, not a separate block.
+        """
+        self.transformer_name = transformer_name
+        super().__init__()
+
     @property
     def description(self) -> str:
         return (
@@ -45,7 +58,7 @@ def description(self) -> str:
 
     @property
     def expected_components(self) -> list[ComponentSpec]:
-        return [ComponentSpec("transformer", MiniMaxH3Transformer3DModel)]
+        return [ComponentSpec(self.transformer_name, MiniMaxH3Transformer3DModel)]
 
     @property
     def inputs(self) -> list[InputParam]:
@@ -96,7 +109,7 @@ def intermediate_outputs(self) -> list[OutputParam]:
 
     @torch.no_grad()
     def __call__(self, components: MiniMaxH3ModularPipeline, block_state: BlockState, i: int, t: torch.Tensor):
-        transformer = components.transformer
+        transformer = getattr(components, self.transformer_name)
         unique_timesteps, timestep_indices = block_state.row_timestep_plan[i]
         # The layout tags its outputs `denoiser_input_fields`, and their names are the transformer's own parameter
         # names, so the rows of the packed sequence are described to it without this block enumerating them.
@@ -118,89 +131,11 @@ def __call__(self, components: MiniMaxH3ModularPipeline, block_state: BlockState
         return components, block_state
 
 
-class MiniMaxH3Ref2VALoopDenoiser(ModularPipelineBlocks):
-    model_name = "minimax-h3-ref2va"
-
-    @property
-    def description(self) -> str:
-        return (
-            "Runs the one MiniMax-H3 forward pass of a `ref2va` denoising iteration, against the `transformer_ref` "
-            "partition of the checkpoint."
-        )
-
-    @property
-    def expected_components(self) -> list[ComponentSpec]:
-        return [ComponentSpec("transformer_ref", MiniMaxH3Transformer3DModel)]
-
-    @property
-    def inputs(self) -> list[InputParam]:
-        return [
-            InputParam(
-                name="latents",
-                type_hint=torch.Tensor,
-                required=True,
-                description="The video rows of the packed sequence, conditioning rows first.",
-            ),
-            InputParam(
-                name="audio_latents",
-                type_hint=torch.Tensor,
-                required=True,
-                description="The channel-major audio rows of the packed sequence, reference rows first.",
-            ),
-            InputParam.template("prompt_embeds"),
-            InputParam(
-                name="row_timestep_plan",
-                type_hint=list,
-                required=True,
-                description="One `(timestep, timestep_indices)` pair per step.",
-            ),
-            InputParam(
-                kwargs_type="denoiser_input_fields",
-                description=(
-                    "The structural description of the packed sequence the transformer reads by name: `token_tags`, "
-                    "`position_ids` and the three row-index tensors."
-                ),
-            ),
-            InputParam.template("attention_kwargs"),
-        ]
+class MiniMaxH3Ref2VALoopDenoiser(MiniMaxH3LoopDenoiser):
+    model_name = "minimax-h3"
 
-    @property
-    def intermediate_outputs(self) -> list[OutputParam]:
-        return [
-            OutputParam(
-                "noise_pred",
-                type_hint=torch.Tensor,
-                description="Predicted velocity of the video rows of the sequence.",
-            ),
-            OutputParam(
-                "audio_noise_pred",
-                type_hint=torch.Tensor,
-                description="Predicted velocity of the audio rows of the sequence.",
-            ),
-        ]
-
-    @torch.no_grad()
-    def __call__(self, components: MiniMaxH3Ref2VAModularPipeline, block_state: BlockState, i: int, t: torch.Tensor):
-        transformer = components.transformer_ref
-        unique_timesteps, timestep_indices = block_state.row_timestep_plan[i]
-        # The layout tags its outputs `denoiser_input_fields`, and their names are the transformer's own parameter
-        # names, so the rows of the packed sequence are described to it without this block enumerating them.
-        layout_kwargs = {
-            name: value
-            for name, value in block_state.denoiser_input_fields.items()
-            if name in inspect.signature(transformer.forward).parameters
-        }
-        block_state.noise_pred, block_state.audio_noise_pred = transformer(
-            hidden_states=block_state.latents[None],
-            audio_hidden_states=block_state.audio_latents[None],
-            encoder_hidden_states=block_state.prompt_embeds,
-            timestep=unique_timesteps,
-            timestep_indices=timestep_indices,
-            attention_kwargs=block_state.attention_kwargs,
-            return_dict=False,
-            **layout_kwargs,
-        )
-        return components, block_state
+    def __init__(self):
+        super().__init__(transformer_name="transformer_ref")
 
 
 class MiniMaxH3LoopSchedulerStep(ModularPipelineBlocks):
@@ -343,7 +278,7 @@ def description(self) -> str:
 
 
 class MiniMaxH3Ref2VADenoiseStep(MiniMaxH3DenoiseLoopWrapper):
-    model_name = "minimax-h3-ref2va"
+    model_name = "minimax-h3"
     block_classes = [MiniMaxH3Ref2VALoopDenoiser, MiniMaxH3LoopSchedulerStep]
     block_names = ["denoiser", "update"]
 
diff --git a/src/diffusers/modular_pipelines/minimax_h3/encoders.py b/src/diffusers/modular_pipelines/minimax_h3/encoders.py
index a6ae5c7f9a07..122fd0812ffc 100644
--- a/src/diffusers/modular_pipelines/minimax_h3/encoders.py
+++ b/src/diffusers/modular_pipelines/minimax_h3/encoders.py
@@ -20,18 +20,123 @@
 from ...utils import logging
 from ..modular_pipeline import ModularPipelineBlocks, PipelineState
 from ..modular_pipeline_utils import ComponentSpec, InputParam, OutputParam
-from .modular_pipeline import MiniMaxH3ModularPipeline, MiniMaxH3Ref2VAModularPipeline
-from .packing_ref2va import (
-    MiniMaxH3Reference,
-    build_ref2va_presentation,
-    sample_reference_video_frames,
-    trim_reference_num_frames,
-)
+from .modular_pipeline import MiniMaxH3ModularPipeline
+from .references import MiniMaxH3Reference
 
 
 logger = logging.get_logger(__name__)  # pylint: disable=invalid-name
 
 
+def get_qwen3vl_prompt_embeds(
+    text_encoder,
+    processor,
+    token_ids: list[int],
+    vision_inputs: dict | None = None,
+    text_encoder_layer: int = 50,
+    device: torch.device | None = None,
+    dtype: torch.dtype | None = None,
+) -> torch.Tensor:
+    r"""
+    Encode one tokenized MiniMax-H3 presentation with the Qwen3-VL conditioner.
+
+    Unlike its `get_<encoder>_prompt_embeds` siblings this takes the *tokenized* presentation rather than a prompt
+    string: MiniMax-H3's tokenization is the presentation-building phase that precedes it, where every reference or
+    keyframe prepends a label and a vision block. The `mm_token_type_ids` built here are Qwen-internal (`0` text, `1`
+    image, `2` video — they drive Qwen3-VL's per-modality-run rotary layout and never leave this function) and are not
+    MiniMax-H3's own per-row modality tags, which the presentation phase produces alongside `token_ids`.
+
+    Args:
+        text_encoder (`Qwen3VLForConditionalGeneration`): The conditioner.
+        processor (`Qwen3VLProcessor`): Its processor, which derives the token type ids from the vision pad ids.
+        token_ids (`list[int]`): The tokenized presentation.
+        vision_inputs (`dict`, *optional*):
+            The vision tensors of the presentation's blocks, by the conditioner's own parameter names —
+            `pixel_values` / `image_grid_thw` for images, `pixel_values_videos` / `video_grid_thw` for videos.
+        text_encoder_layer (`int`, *optional*, defaults to 50):
+            Which hidden state conditions the transformer, i.e. `components.text_encoder_layer`.
+        device (`torch.device`, *optional*): The device to run the conditioner on.
+        dtype (`torch.dtype`, *optional*): The dtype of the returned embeddings.
+
+    Returns:
+        `torch.Tensor`: the `(1, num_text_tokens, 5120)` hidden state after decoder layer `text_encoder_layer`.
+    """
+    num_layers = text_encoder.config.text_config.num_hidden_layers
+    if num_layers <= text_encoder_layer:
+        raise ValueError(
+            f"MiniMax-H3 conditions on `hidden_states[{text_encoder_layer}]` of its Qwen3-VL "
+            f"conditioner, which needs more than {text_encoder_layer} decoder layers, but "
+            f"`text_encoder` has {num_layers}. The last hidden state of a stack truncated to exactly "
+            f"{text_encoder_layer} layers is post-norm and is not the conditioning MiniMax-H3 expects."
+        )
+
+    input_ids = torch.tensor([token_ids], dtype=torch.long, device=device)
+    mm_token_type_ids = torch.tensor(processor.create_mm_token_type_ids([token_ids]), dtype=torch.long, device=device)
+
+    vision_kwargs = {}
+    for name, value in (vision_inputs or {}).items():
+        vision_kwargs[name] = value.to(device, text_encoder.dtype) if name.startswith("pixel_") else value.to(device)
+
+    # `text_encoder.model` is a submodule, and a CPU-offload hook — accelerate's or the one the
+    # `ComponentsManager` attaches — wraps the *top-level* module's `forward` alone, so calling the submodule
+    # directly would leave the conditioner on the CPU. Fire the hook by hand instead of routing through
+    # `text_encoder(...)`: MiniMax-H3 reads `hidden_states[50]` and never uses the language-model head, whose
+    # vocabulary-wide projection over every token is all the top-level forward would add.
+    # TODO: firing another module's offload hook by hand is not something a block should do. It is here
+    # because MiniMax-H3 reads `hidden_states[50]` off `text_encoder.model` while the hook wraps only the
+    # top-level `forward`. Needs a real answer — an opt-in on the conditioner, or a hook that follows
+    # submodule calls.
+    hook = getattr(text_encoder, "_hf_hook", None)
+    if hook is not None and hasattr(hook, "pre_forward"):
+        hook.pre_forward(text_encoder)
+    outputs = text_encoder.model(
+        input_ids=input_ids,
+        attention_mask=torch.ones_like(input_ids),
+        mm_token_type_ids=mm_token_type_ids,
+        use_cache=False,
+        output_hidden_states=True,
+        **vision_kwargs,
+    )
+    return outputs.hidden_states[text_encoder_layer].to(device=device, dtype=dtype)
+
+
+def encode_vae_condition(
+    vae, pixels: torch.Tensor, pixel_mean: tuple, pixel_std: tuple, encode_seed: int = 42
+) -> torch.Tensor:
+    r"""
+    Encode one visual condition — a keyframe or a `ref2va` reference — into normalized conditioning latents.
+
+    The recipe is the released model's, and every part of it is needed to reproduce its conditioning: the pixels are
+    ImageNet-normalized, the posterior is *sampled* under a fresh generator seeded independently of the request, and
+    the sampled latent is rounded to float16 (~11 bits of every conditioning latent) before being normalized. A
+    single frame is encoded by the (tiled) spatial encoder alone; a frame stack goes through the temporal chunking,
+    which is what turns `17 * n + 5` frames into `5 * n + 2` latent frames.
+
+    Args:
+        vae (`AutoencoderKLMiniMaxH3`): The video VAE.
+        pixels (`torch.Tensor` of shape `(1, 3, num_frames, height, width)`):
+            The condition's `uint8` pixels, on the VAE's device. `num_frames` is 1 for a keyframe or an image
+            reference.
+        pixel_mean (`tuple[float, float, float]`), pixel_std (`tuple[float, float, float]`):
+            The video VAE's pixel convention, i.e. `components.pixel_mean` / `components.pixel_std`.
+        encode_seed (`int`, *optional*, defaults to 42):
+            Seed the posterior is sampled under, i.e. `components.keyframe_encode_seed`.
+
+    Returns:
+        `torch.Tensor`: one `(1, latent_channels, num_latent_frames, latent_height, latent_width)` float32 CPU
+        tensor.
+    """
+    latents_mean = torch.tensor(vae.config.latents_mean).view(1, -1, 1, 1, 1)
+    latents_std = torch.tensor(vae.config.latents_std).view(1, -1, 1, 1, 1)
+    pixel_mean = torch.tensor(pixel_mean, device=pixels.device).view(1, -1, 1, 1, 1)
+    pixel_std = torch.tensor(pixel_std, device=pixels.device).view(1, -1, 1, 1, 1)
+
+    pixels = (pixels.to(torch.float32).div(255.0) - pixel_mean) / pixel_std
+    posterior = vae.encode(pixels, return_dict=False)[0]
+    latents = posterior.sample(generator=torch.Generator().manual_seed(encode_seed))
+    latents = latents.to(torch.float16).float().cpu()
+    return (latents - latents_mean) / latents_std
+
+
 class MiniMaxH3TextEncoderStep(ModularPipelineBlocks):
     model_name = "minimax-h3"
 
@@ -81,56 +186,31 @@ def intermediate_outputs(self) -> list[OutputParam]:
             ),
         ]
 
-    @staticmethod
-    def encode_prompt(
-        text_encoder,
-        tokenizer,
-        processor,
-        prompt: str,
-        images: list | None = None,
-        *,
-        text_encoder_layer: int,# can you set the default?
-        text_tag: int,# can you set the default?
-        video_tag: int, # can you set the default?
-        device: torch.device | None = None,
-        dtype: torch.dtype | None = None,
-    ) -> tuple[torch.Tensor, torch.Tensor]:
-        r"""
-        Build MiniMax-H3's presentation of a request and encode it.
-
-        The presentation is the verbatim prompt for `t2va`. Every keyframe prepends a `"<Picture i>: "` label and a
-        vision block (`<|vision_start|>`, one `<|image_pad|>` per vision patch, `<|vision_end|>`) — no chat template
-        and no special tokens. The rows of a vision block are tagged as *video* rather than text, which is what the
-        transformer's AdaLN modulation keys off.
-
-        Args:
-            prompt (`str`): The prompt to encode.
-            images (`list[PIL.Image.Image]`, *optional*):
-                The keyframes, already prepared onto the target canvas, in packed order.
-            device (`torch.device`, *optional*): The device to run the conditioner on.
-            dtype (`torch.dtype`, *optional*): The dtype of the returned embeddings.
-
-        Returns:
-            `tuple[torch.Tensor, torch.Tensor]`: the `(1, num_text_tokens, 5120)` hidden states and the
-            `(num_text_tokens,)` per-row modality tags.
-        """
-
-        num_layers = text_encoder.config.text_config.num_hidden_layers
-        if num_layers <= text_encoder_layer:
+    @torch.no_grad()
+    def __call__(self, components: MiniMaxH3ModularPipeline, state: PipelineState) -> PipelineState:
+        block_state = self.get_block_state(state)
+        if not isinstance(block_state.prompt, str):
             raise ValueError(
-                f"MiniMax-H3 conditions on `hidden_states[{text_encoder_layer}]` of its Qwen3-VL "
-                f"conditioner, which needs more than {text_encoder_layer} decoder layers, but "
-                f"`text_encoder` has {num_layers}. The last hidden state of a stack truncated to exactly "
-                f"{text_encoder_layer} layers is post-norm and is not the conditioning MiniMax-H3 expects."
+                "MiniMax-H3 packs one request into one sequence, so `prompt` must be a single string, got "
+                f"{type(block_state.prompt)}."
             )
-
-        pixel_values, image_grid_thw = None, None
+        tokenizer, processor = components.tokenizer, components.processor
+        text_tag, video_tag = components.text_tag, components.video_tag
+
+        # 1. Vision features of the keyframes, batched. The presentation is text-only without them.
+        vision_inputs, image_grid_thw = {}, None
+        if block_state.keyframes:
+            vision = processor.image_processor(images=block_state.keyframes, return_tensors="pt")
+            image_grid_thw = vision["image_grid_thw"]
+            vision_inputs = {"pixel_values": vision["pixel_values"], "image_grid_thw": image_grid_thw}
+
+        # 2. The presentation, tokenized: a `"<Picture i>: "` label and a vision block per keyframe, then the prompt
+        # verbatim. The rows of a vision block are tagged as *video* rather than text, which is what the
+        # transformer's AdaLN modulation keys off.
         token_ids, token_tags = [], []
-        if images:
-            vision = processor.image_processor(images=images, return_tensors="pt")
-            pixel_values, image_grid_thw = vision["pixel_values"], vision["image_grid_thw"]
+        if block_state.keyframes:
             merge_size = processor.image_processor.merge_size**2
-            for index in range(len(images)):
+            for index in range(len(block_state.keyframes)):
                 num_image_tokens = int(image_grid_thw[index].prod()) // merge_size
                 label_ids = tokenizer(f"<Picture {index + 1}>: ", add_special_tokens=False)["input_ids"]
                 vision_ids = (
@@ -140,63 +220,22 @@ def encode_prompt(
                 )
                 token_ids += label_ids + vision_ids
                 token_tags += [text_tag] * len(label_ids) + [video_tag] * len(vision_ids)
-        prompt_ids = tokenizer(prompt, add_special_tokens=False)["input_ids"]
+        prompt_ids = tokenizer(block_state.prompt, add_special_tokens=False)["input_ids"]
         token_ids += prompt_ids
         token_tags += [text_tag] * len(prompt_ids)
 
-        input_ids = torch.tensor([token_ids], dtype=torch.long, device=device)
-        # Qwen3-VL lays its 3D rotary positions out per modality run, which it reads off the token type ids the
-        # processor derives from the vision pad ids (`0` text, `1` image, `2` video).
-        mm_token_type_ids = torch.tensor(
-            processor.create_mm_token_type_ids([token_ids]), dtype=torch.long, device=device
-        )
-        # `text_encoder.model` is a submodule, and a CPU-offload hook — accelerate's or the one the
-        # `ComponentsManager` attaches — wraps the *top-level* module's `forward` alone, so calling the submodule
-        # directly would leave the conditioner on the CPU. Fire the hook by hand instead of routing through
-        # `text_encoder(...)`: MiniMax-H3 reads `hidden_states[50]` and never uses the language-model head, whose
-        # vocabulary-wide projection over every token is all the top-level forward would add.
-        # TODO: firing another module's offload hook by hand is not something a block should do. It is here
-        # because MiniMax-H3 reads `hidden_states[50]` off `text_encoder.model` while the hook wraps only the
-        # top-level `forward`. Needs a real answer — an opt-in on the conditioner, or a hook that follows
-        # submodule calls.
-        hook = getattr(text_encoder, "_hf_hook", None)
-        if hook is not None and hasattr(hook, "pre_forward"):
-            hook.pre_forward(text_encoder)
-        outputs = text_encoder.model(
-            input_ids=input_ids,
-            attention_mask=torch.ones_like(input_ids),
-            mm_token_type_ids=mm_token_type_ids,
-            pixel_values=None if pixel_values is None else pixel_values.to(device, text_encoder.dtype),
-            image_grid_thw=None if image_grid_thw is None else image_grid_thw.to(device),
-            use_cache=False,
-            output_hidden_states=True,
-        )
-        prompt_embeds = outputs.hidden_states[text_encoder_layer].to(device=device, dtype=dtype)
-        return prompt_embeds, torch.tensor(token_tags, dtype=torch.long)
-
-    @torch.no_grad()
-    def __call__(self, components: MiniMaxH3ModularPipeline, state: PipelineState) -> PipelineState:
-        block_state = self.get_block_state(state)
-        if not isinstance(block_state.prompt, str):
-            raise ValueError(
-                "MiniMax-H3 packs one request into one sequence, so `prompt` must be a single string, got "
-                f"{type(block_state.prompt)}."
-            )
-
-        # `encode_prompt` defaults the embedding dtype to the denoiser's; a text encoder block has no denoiser of
-        # its own — it is meant to run on its own — so it emits the conditioner's dtype, as every other model does.
-        block_state.prompt_embeds, block_state.text_token_tags = self.encode_prompt(
+        # 3. One conditioner call. The block emits the conditioner's dtype, as every other model does — it has no
+        # denoiser of its own, since it is meant to run on its own.
+        block_state.prompt_embeds = get_qwen3vl_prompt_embeds(
             components.text_encoder,
-            components.tokenizer,
-            components.processor,
-            block_state.prompt,
-            block_state.keyframes,
+            processor,
+            token_ids,
+            vision_inputs,
             text_encoder_layer=components.text_encoder_layer,
-            text_tag=components.text_tag,
-            video_tag=components.video_tag,
             device=components._execution_device,
             dtype=components.text_encoder.dtype,
         )
+        block_state.text_token_tags = torch.tensor(token_tags, dtype=torch.long)
 
         self.set_block_state(state, block_state)
         return components, state
@@ -236,74 +275,49 @@ def intermediate_outputs(self) -> list[OutputParam]:
                 type_hint=list[torch.Tensor],
                 description=(
                     "The normalized video conditioning latents, one `(1, latent_channels, 1, latent_height, "
-                    "latent_width)` tensor per keyframe, in packed order."
+                    "latent_width)` tensor per keyframe, in packed order. One entry per condition is what the "
+                    "prepare-latents step draws its noise against, so the list is the unit the request's generator "
+                    "is consumed in."
                 ),
             )
         ]
 
-    @staticmethod
-    def encode_keyframes(
-        vae, images: list, pixel_mean: tuple, pixel_std: tuple, encode_seed: int, device: torch.device
-    ) -> list[torch.Tensor]:
-        r"""
-        Encode the `fl2va` keyframes into normalized conditioning latents.
-
-        A keyframe is a single frame, so `vae.encode` runs its spatial encoder alone with none of the 17-frame
-        temporal chunking. The posterior is *sampled*, under a generator seeded with 42 independently of the request
-        seed, and the sampled latent is rounded to float16 before being normalized, as in the reference
-        implementation; both are part of reproducing the released model's conditioning.
-
-        Args:
-            vae (`AutoencoderKLMiniMaxH3`): The video VAE.
-            images (`list[PIL.Image.Image]`):
-                The keyframes, already prepared onto the target canvas, in packed order.
-            pixel_mean (`tuple[float, float, float]`), pixel_std (`tuple[float, float, float]`):
-                The video VAE's pixel convention, i.e. `components.pixel_mean` / `components.pixel_std`.
-            encode_seed (`int`): Seed the posterior is sampled under, i.e. `components.keyframe_encode_seed`.
-            device (`torch.device`): The device to run the VAE on.
-
-        Returns:
-            `list[torch.Tensor]`: one `(1, latent_channels, 1, latent_height, latent_width)` float32 CPU tensor per
-            keyframe, in packed order. One entry per condition is what the prepare-latents step draws its noise
-            against, so the list is the unit the request's generator is consumed in.
-        """
-        latents_mean = torch.tensor(vae.config.latents_mean).view(1, -1, 1, 1, 1)
-        latents_std = torch.tensor(vae.config.latents_std).view(1, -1, 1, 1, 1)
-        pixel_mean = torch.tensor(pixel_mean, device=device).view(1, -1, 1, 1, 1)
-        pixel_std = torch.tensor(pixel_std, device=device).view(1, -1, 1, 1, 1)
-
-        keyframe_latents = []
-        for image in images:
-            pixels = torch.from_numpy(np.array(image)).to(device).permute(2, 0, 1)[None, :, None]
-            pixels = (pixels.to(torch.float32).div(255.0) - pixel_mean) / pixel_std
-            posterior = vae.encode(pixels, return_dict=False)[0]
-            latents = posterior.sample(generator=torch.Generator().manual_seed(encode_seed))
-            # The sampled latent is rounded to float16 before it is normalized: ~11 bits of every conditioning
-            # latent, so the released model's conditioning cannot be reproduced without it.
-            latents = latents.to(torch.float16).float().cpu()
-            keyframe_latents.append((latents - latents_mean) / latents_std)
-        return keyframe_latents
-
     @torch.no_grad()
     def __call__(self, components: MiniMaxH3ModularPipeline, state: PipelineState) -> PipelineState:
         block_state = self.get_block_state(state)
         device = components._execution_device
 
-        block_state.condition_latents = self.encode_keyframes(
-            components.vae,
-            block_state.keyframes,
-            components.pixel_mean,
-            components.pixel_std,
-            components.keyframe_encode_seed,
-            device,
-        )
+        # A keyframe is a single frame, so the VAE runs its spatial encoder alone with none of the 17-frame
+        # temporal chunking.
+        block_state.condition_latents = [
+            encode_vae_condition(
+                components.vae,
+                torch.from_numpy(np.array(image)).to(device).permute(2, 0, 1)[None, :, None],
+                components.pixel_mean,
+                components.pixel_std,
+                components.keyframe_encode_seed,
+            )
+            for image in block_state.keyframes
+        ]
 
         self.set_block_state(state, block_state)
         return components, state
 
 
 class MiniMaxH3Ref2VATextEncoderStep(ModularPipelineBlocks):
-    model_name = "minimax-h3-ref2va"
+    model_name = "minimax-h3"
+
+    def __init__(self, video_sample_fps: float = 2.0):
+        r"""
+        Encode the presentation of a `ref2va` request.
+
+        Args:
+            video_sample_fps (`float`, defaults to 2.0):
+                The rate the conditioner reads a reference video at: every `24 / video_sample_fps`-th of the
+                normalized 24 fps frames.
+        """
+        self.video_sample_fps = video_sample_fps
+        super().__init__()
 
     @property
     def description(self) -> str:
@@ -327,10 +341,10 @@ def inputs(self) -> list[InputParam]:
         return [
             InputParam.template("prompt", description="The prompt to guide generation, a single string."),
             InputParam(
-                name="prepared_references",
+                name="normalized_references",
                 type_hint=list[MiniMaxH3Reference],
                 required=True,
-                description="The prepared references, in packed order.",
+                description="The references normalized by the setup step, in packed order.",
             ),
         ]
 
@@ -354,144 +368,211 @@ def intermediate_outputs(self) -> list[OutputParam]:
         ]
 
     @staticmethod
-    def encode_prompt(
-        text_encoder,
-        tokenizer,
-        processor,
-        prompt: str,
-        references: list[MiniMaxH3Reference],
-        *,
-        text_encoder_layer: int, # can you add default
-        text_tag: int, # can you add default
-        video_tag: int, # can you add default
-        device: torch.device | None = None,
-        dtype: torch.dtype | None = None,
-    ) -> tuple[torch.Tensor, torch.Tensor]:
+    def _sample_video_condition_frames(
+        frames: np.ndarray, fps: float, sample_fps: float, temporal_patch: int
+    ) -> tuple[list[np.ndarray], list[float]]:
         r"""
-        Build MiniMax-H3's presentation of a `ref2va` request and encode it.
+        Sample the frames the conditioner sees from a normalized reference video, and label their vision blocks.
 
-        Every reference prepends a label, in request order and numbered per modality: `"<Picture i>: "` plus a vision
-        block for an image, `"<Audio j>: "` alone for audio (a waveform never reaches the conditioner), and
-        `"<Video k>: "` plus one timestamped vision block per merged frame pair for a video. A video that carries
-        sound is labelled `"<Audio j>: "` *before* `"<Video k>: "`, mirroring the order its rows are packed in. The
-        prompt then follows, verbatim, with no chat template and no special tokens. The rows of a vision block are
-        tagged as *video* rather than text, which is what the transformer's AdaLN modulation keys off.
+        The conditioner reads a reference at `sample_fps`: every `fps / sample_fps`-th frame, deduplicated. Qwen3-VL
+        then merges the sampled frames in groups of `temporal_patch` — repeating the last one when the count does not
+        divide — and a merged group is labelled with the mean of its timestamps, which `"<{timestamp:.1f} seconds>"`
+        renders with Python's round-half-to-even, so the first block of a 2 fps pair is `"<0.2 seconds>"` rather than
+        `"<0.3 seconds>"`.
 
         Args:
-            prompt (`str`): The prompt to encode.
-            references (`list[MiniMaxH3Reference]`):
-                The prepared references, in packed order, as returned by
-                [`~MiniMaxH3Ref2VASetupStep.prepare_references`].
-            device (`torch.device`, *optional*): The device to run the conditioner on.
-            dtype (`torch.dtype`, *optional*): The dtype of the returned embeddings.
+            frames (`np.ndarray` of shape `(num_frames, height, width, 3)`): The normalized reference video.
+            fps (`float`): The rate `frames` is at, i.e. `components.fps`.
+            sample_fps (`float`): The rate the conditioner reads at, i.e. the block's `video_sample_fps`.
+            temporal_patch (`int`): Qwen3-VL's temporal patch, read off the processor.
 
         Returns:
-            `tuple[torch.Tensor, torch.Tensor]`: the `(1, num_text_tokens, 5120)` hidden states and the
-            `(num_text_tokens,)` per-row modality tags.
+            `tuple[list[np.ndarray], list[float]]`: the sampled frames and one timestamp per vision block.
         """
+        stride = fps / sample_fps
+        indices, cursor = [], 0.0
+        while round(cursor) < frames.shape[0]:
+            if not indices or round(cursor) > indices[-1]:
+                indices.append(round(cursor))
+            cursor += stride
+
+        timestamps = [index / sample_fps for index in range(len(indices))]
+        timestamps += [timestamps[-1]] * (-len(timestamps) % temporal_patch)
+        block_timestamps = [
+            (timestamps[index] + timestamps[index + temporal_patch - 1]) / 2
+            for index in range(0, len(timestamps), temporal_patch)
+        ]
+        return [frames[index] for index in indices], block_timestamps
 
-        num_layers = text_encoder.config.text_config.num_hidden_layers
-        if num_layers <= text_encoder_layer:
-            raise ValueError(
-                f"MiniMax-H3 conditions on `hidden_states[{text_encoder_layer}]` of its Qwen3-VL "
-                f"conditioner, which needs more than {text_encoder_layer} decoder layers, but "
-                f"`text_encoder` has {num_layers}. The last hidden state of a stack truncated to exactly "
-                f"{text_encoder_layer} layers is post-norm and is not the conditioning MiniMax-H3 expects."
-            )
+    def _gather_vision_features(
+        self, processor, references: list[MiniMaxH3Reference], fps: float
+    ) -> tuple[dict, list[int], list[int], list[list[float]]]:
+        r"""
+        Run the references' pixels through the conditioner's processors, batched per modality.
+
+        The vision tensors are batched per modality while the presentation is tokenized in request order; the two
+        agree because the filtering here preserves relative order within each modality and Qwen3-VL fills the n-th
+        pad *run* of a modality with the n-th entry of that modality's batch. Audio contributes nothing — a waveform
+        never reaches the conditioner.
 
+        Returns:
+            `tuple`: the vision tensors by the conditioner's parameter names, the vision token count per image
+            reference, the per-block token count per video reference, and the block timestamps per video reference.
+        """
         merge_size = processor.image_processor.merge_size**2
-        pixel_values, image_grid_thw, image_token_counts = None, None, []
+        vision_inputs = {}
+
+        image_token_counts = []
         images = [reference.image for reference in references if reference.kind == "image"]
         if images:
-            vision = processor.image_processor(images=images, return_tensors="pt")
-            pixel_values, image_grid_thw = vision["pixel_values"], vision["image_grid_thw"]
-            image_token_counts = [int(grid.prod()) // merge_size for grid in image_grid_thw]
+            image_features = processor.image_processor(images=images, return_tensors="pt")
+            vision_inputs["pixel_values"] = image_features["pixel_values"]
+            vision_inputs["image_grid_thw"] = image_features["image_grid_thw"]
+            image_token_counts = [int(grid.prod()) // merge_size for grid in image_features["image_grid_thw"]]
 
-        pixel_values_videos, video_grid_thw = None, None
         video_block_token_counts, video_block_timestamps = [], []
         videos = [reference for reference in references if reference.kind == "video"]
         if videos:
-            sampled = [sample_reference_video_frames(reference.frames) for reference in videos]
+            temporal_patch = processor.video_processor.temporal_patch_size
+            sampled = [
+                self._sample_video_condition_frames(reference.frames, fps, self.video_sample_fps, temporal_patch)
+                for reference in videos
+            ]
             video_block_timestamps = [timestamps for _, timestamps in sampled]
-            vision = processor.video_processor(
+            video_features = processor.video_processor(
                 videos=[np.stack(frames) for frames, _ in sampled], do_sample_frames=False, return_tensors="pt"
             )
-            pixel_values_videos, video_grid_thw = vision["pixel_values_videos"], vision["video_grid_thw"]
-            video_block_token_counts = [int(grid[1]) * int(grid[2]) // merge_size for grid in video_grid_thw]
-            for timestamps, grid in zip(video_block_timestamps, video_grid_thw):
+            vision_inputs["pixel_values_videos"] = video_features["pixel_values_videos"]
+            vision_inputs["video_grid_thw"] = video_features["video_grid_thw"]
+            video_block_token_counts = [
+                int(grid[1]) * int(grid[2]) // merge_size for grid in video_features["video_grid_thw"]
+            ]
+            for timestamps, grid in zip(video_block_timestamps, video_features["video_grid_thw"]):
                 if int(grid[0]) != len(timestamps):
                     raise ValueError(
                         f"The processor merged a reference video into {int(grid[0])} vision blocks, but MiniMax-H3 "
                         f"labels {len(timestamps)} of them."
                     )
 
-        token_ids, token_tags = build_ref2va_presentation(
-            tokenizer, prompt, references, image_token_counts, video_block_token_counts, video_block_timestamps
-        )
-        input_ids = torch.tensor([token_ids], dtype=torch.long, device=device)
-        # Qwen3-VL lays its 3D rotary positions out per modality run, which it reads off the token type ids the
-        # processor derives from the vision pad ids (`0` text, `1` image, `2` video).
-        mm_token_type_ids = torch.tensor(
-            processor.create_mm_token_type_ids([token_ids]), dtype=torch.long, device=device
-        )
-        # `text_encoder.model` is a submodule, and a CPU-offload hook — accelerate's or the one the
-        # `ComponentsManager` attaches — wraps the *top-level* module's `forward` alone, so calling the submodule
-        # directly would leave the conditioner on the CPU. Fire the hook by hand instead of routing through
-        # `text_encoder(...)`: MiniMax-H3 reads `hidden_states[50]` and never uses the language-model head, whose
-        # vocabulary-wide projection over every token is all the top-level forward would add.
-        # TODO: firing another module's offload hook by hand is not something a block should do. It is here
-        # because MiniMax-H3 reads `hidden_states[50]` off `text_encoder.model` while the hook wraps only the
-        # top-level `forward`. Needs a real answer — an opt-in on the conditioner, or a hook that follows
-        # submodule calls.
-        hook = getattr(text_encoder, "_hf_hook", None)
-        if hook is not None and hasattr(hook, "pre_forward"):
-            hook.pre_forward(text_encoder)
-        outputs = text_encoder.model(
-            input_ids=input_ids,
-            attention_mask=torch.ones_like(input_ids),
-            mm_token_type_ids=mm_token_type_ids,
-            pixel_values=None if pixel_values is None else pixel_values.to(device, text_encoder.dtype),
-            image_grid_thw=None if image_grid_thw is None else image_grid_thw.to(device),
-            pixel_values_videos=(
-                None if pixel_values_videos is None else pixel_values_videos.to(device, text_encoder.dtype)
-            ),
-            video_grid_thw=None if video_grid_thw is None else video_grid_thw.to(device),
-            use_cache=False,
-            output_hidden_states=True,
-        )
-        prompt_embeds = outputs.hidden_states[text_encoder_layer].to(device=device, dtype=dtype)
-        return prompt_embeds, torch.tensor(token_tags, dtype=torch.long)
+        return vision_inputs, image_token_counts, video_block_token_counts, video_block_timestamps
+
+    @staticmethod
+    def _build_presentation(
+        tokenizer,
+        prompt: str,
+        references: list[MiniMaxH3Reference],
+        image_token_counts: list[int],
+        video_block_token_counts: list[int],
+        video_block_timestamps: list[list[float]],
+        text_tag: int = 1,
+        video_tag: int = 0,
+    ) -> tuple[list[int], list[int]]:
+        r"""
+        Tokenize MiniMax-H3's presentation of a `ref2va` request.
+
+        Every reference prepends a label, in packed order and numbered per modality: `"<Picture i>: "` plus a vision
+        block for an image, `"<Audio j>: "` alone for audio — a waveform never reaches the conditioner — and
+        `"<Video k>: "` plus one timestamped vision block per merged frame pair for a video. A video that carries
+        sound is labelled `"<Audio j>: "` *before* `"<Video k>: "`, mirroring the order its rows are packed in. The
+        prompt follows verbatim, with no chat template and no special tokens.
+
+        Args:
+            tokenizer (`Qwen2TokenizerFast`): Tokenizer of the conditioner.
+            prompt (`str`): The prompt, appended verbatim.
+            references (`list[MiniMaxH3Reference]`): The normalized references, in packed order.
+            image_token_counts (`list[int]`): Number of vision tokens of every image reference's block.
+            video_block_token_counts (`list[int]`): Number of vision tokens per block of every video reference.
+            video_block_timestamps (`list[list[float]]`): The timestamp of every vision block, per video reference.
+            text_tag (`int`, *optional*, defaults to 1): MiniMax-H3's modality tag for a text row.
+            video_tag (`int`, *optional*, defaults to 0): MiniMax-H3's modality tag for a vision block's rows.
+
+        Returns:
+            `tuple[list[int], list[int]]`: the token ids and their modality tags.
+        """
+
+        def text(value: str) -> tuple[list[int], list[int]]:
+            token_ids = tokenizer(value, add_special_tokens=False)["input_ids"]
+            return token_ids, [text_tag] * len(token_ids)
+
+        def vision(pad_token: str, num_tokens: int) -> tuple[list[int], list[int]]:
+            token_ids = (
+                [tokenizer.convert_tokens_to_ids("<|vision_start|>")]
+                + [tokenizer.convert_tokens_to_ids(pad_token)] * num_tokens
+                + [tokenizer.convert_tokens_to_ids("<|vision_end|>")]
+            )
+            return token_ids, [video_tag] * len(token_ids)
+
+        token_ids, token_tags = [], []
+
+        def emit(segment: tuple[list[int], list[int]]) -> None:
+            token_ids.extend(segment[0])
+            token_tags.extend(segment[1])
+
+        counts = {"image": 0, "video": 0, "audio": 0}
+        for reference in references:
+            if reference.has_audio:
+                counts["audio"] += 1
+                emit(text(f"<Audio {counts['audio']}>: "))
+            if reference.kind == "image":
+                counts["image"] += 1
+                emit(text(f"<Picture {counts['image']}>: "))
+                emit(vision("<|image_pad|>", image_token_counts[counts["image"] - 1]))
+            elif reference.kind == "video":
+                counts["video"] += 1
+                emit(text(f"<Video {counts['video']}>: "))
+                for timestamp in video_block_timestamps[counts["video"] - 1]:
+                    # `"{:.1f}"` rounds half to even, so the mean of a 2 fps pair renders as "<0.2 seconds>".
+                    emit(text(f"<{timestamp:.1f} seconds>"))
+                    emit(vision("<|video_pad|>", video_block_token_counts[counts["video"] - 1]))
+        emit(text(prompt))
+        return token_ids, token_tags
 
     @torch.no_grad()
-    def __call__(self, components: MiniMaxH3Ref2VAModularPipeline, state: PipelineState) -> PipelineState:
+    def __call__(self, components: MiniMaxH3ModularPipeline, state: PipelineState) -> PipelineState:
         block_state = self.get_block_state(state)
         if not isinstance(block_state.prompt, str):
             raise ValueError(
                 "MiniMax-H3 packs one request into one sequence, so `prompt` must be a single string, got "
                 f"{type(block_state.prompt)}."
             )
+        references = block_state.normalized_references
 
-        # `encode_prompt` defaults the embedding dtype to the denoiser's; a text encoder block has no denoiser of
-        # its own — it is meant to run on its own — so it emits the conditioner's dtype, as every other model does.
-        block_state.prompt_embeds, block_state.text_token_tags = self.encode_prompt(
-            components.text_encoder,
+        # 1. Vision features, batched per modality — audio contributes nothing to the conditioner.
+        vision_inputs, image_token_counts, video_token_counts, video_timestamps = self._gather_vision_features(
+            components.processor, references, components.fps
+        )
+
+        # 2. The presentation, tokenized in request order.
+        token_ids, token_tags = self._build_presentation(
             components.tokenizer,
-            components.processor,
             block_state.prompt,
-            block_state.prepared_references,
-            text_encoder_layer=components.text_encoder_layer,
+            references,
+            image_token_counts,
+            video_token_counts,
+            video_timestamps,
             text_tag=components.text_tag,
             video_tag=components.video_tag,
+        )
+
+        # 3. One conditioner call. The block emits the conditioner's dtype, as every other model does — it has no
+        # denoiser of its own, since it is meant to run on its own.
+        block_state.prompt_embeds = get_qwen3vl_prompt_embeds(
+            components.text_encoder,
+            components.processor,
+            token_ids,
+            vision_inputs,
+            text_encoder_layer=components.text_encoder_layer,
             device=components._execution_device,
             dtype=components.text_encoder.dtype,
         )
+        block_state.text_token_tags = torch.tensor(token_tags, dtype=torch.long)
 
         self.set_block_state(state, block_state)
         return components, state
 
 
 class MiniMaxH3Ref2VAReferenceEncoderStep(ModularPipelineBlocks):
-    model_name = "minimax-h3-ref2va"
+    model_name = "minimax-h3"
 
     @property
     def description(self) -> str:
@@ -499,8 +580,8 @@ def description(self) -> str:
             "Encodes the `ref2va` references — image and video references through the video VAE, soundtracks through "
             "the audio VAE. They are the anchors of the whole denoising loop, which only ever writes the generated "
             "rows; the prepare-latents step noises the visual ones to MiniMax-H3's conditioning level and packs them, "
-            "while soundtracks ride along clean at `t = 1.0`. The latent geometry of every reference is resolved "
-            "here, so this runs before the packed layout is built."
+            "while soundtracks ride along clean at `t = 1.0`. The latent geometry of every reference is the shape of "
+            "what this emits, which is what the packed layout is built from."
         )
 
     @property
@@ -514,7 +595,7 @@ def expected_components(self) -> list[ComponentSpec]:
     def inputs(self) -> list[InputParam]:
         return [
             InputParam(
-                name="prepared_references",
+                name="normalized_references",
                 type_hint=list[MiniMaxH3Reference],
                 required=True,
                 description="The references normalized by the setup step, in packed order.",
@@ -545,82 +626,57 @@ def intermediate_outputs(self) -> list[OutputParam]:
             ),
         ]
 
-    @staticmethod
-    def encode_references(
-        components, references: list[MiniMaxH3Reference], device: torch.device | None = None
-    ) -> tuple[list[torch.Tensor], list[torch.Tensor]]:
-        r"""
-        Encode the references into conditioning latents.
-
-        Image and video references go through the video VAE with the same recipe the `fl2va` keyframes use: the
-        posterior is *sampled* under a generator seeded with 42 independently of the request seed, and the sampled
-        latent is rounded to float16 before being normalized. An image is a single frame and is encoded by the spatial
-        encoder alone, while a video reference goes through the 17-frames-per-5-latents temporal chunking. Reference
-        soundtracks instead take the posterior *mean*, and are never sampled.
-
-        The latent geometry every later block keys off is the shape of what this returns, so nothing has to be
-        written back onto the references.
-
-        Args:
-            references (`list[MiniMaxH3Reference]`):
-                The references normalized by the setup step, in packed order.
-            device (`torch.device`, *optional*): The device to run the VAEs on.
+    @torch.no_grad()
+    def __call__(self, components: MiniMaxH3ModularPipeline, state: PipelineState) -> PipelineState:
+        block_state = self.get_block_state(state)
+        device = components._execution_device
 
-        Returns:
-            `tuple[list[torch.Tensor], list[torch.Tensor]]`: one `(1, latent_channels, num_latent_frames,
-            latent_height, latent_width)` tensor per image and video reference, and one `(num_audio_latents * 2,
-            audio_latent_channels)` tensor per audio-bearing reference, both in packed order and float32 on CPU.
-        """
-        latents_mean = torch.tensor(components.vae.config.latents_mean).view(1, -1, 1, 1, 1)
-        latents_std = torch.tensor(components.vae.config.latents_std).view(1, -1, 1, 1, 1)
-        pixel_mean = torch.tensor(components.pixel_mean, device=device).view(1, -1, 1, 1, 1)
-        pixel_std = torch.tensor(components.pixel_std, device=device).view(1, -1, 1, 1, 1)
         audio_latents_mean = torch.tensor(components.audio_vae.config.latents_mean).view(1, 1, -1)
         audio_latents_std = torch.tensor(components.audio_vae.config.latents_std).view(1, 1, -1)
 
-        video_latents, audio_rows = [], []
-        for reference in references:
-            if reference.kind != "audio":
-                if reference.kind == "image":
-                    pixels = torch.from_numpy(np.array(reference.image)).to(device).permute(2, 0, 1)[None, :, None]
-                else:
-                    frames = reference.frames[
-                        : trim_reference_num_frames(
-                            reference.frames.shape[0],
-                            components.vae_frames_per_chunk,
-                            components.vae_latents_per_chunk,
-                        )
-                    ]
-                    pixels = torch.from_numpy(frames.copy()).to(device).permute(3, 0, 1, 2)[None]
-                pixels = (pixels.to(torch.float32).div(255.0) - pixel_mean) / pixel_std
-                # A single frame is encoded by the (tiled) spatial encoder alone; a video goes through the temporal
-                # chunking, which is what turns `17 * n + 5` frames into `5 * n + 2` latent frames.
-                posterior = components.vae.encode(pixels, return_dict=False)[0]
-                latents = posterior.sample(
-                    generator=torch.Generator().manual_seed(components.keyframe_encode_seed)
+        condition_latents, audio_condition_latents = [], []
+        for reference in block_state.normalized_references:
+            if reference.kind == "image":
+                pixels = torch.from_numpy(np.array(reference.image)).to(device).permute(2, 0, 1)[None, :, None]
+                condition_latents.append(
+                    encode_vae_condition(
+                        components.vae,
+                        pixels,
+                        components.pixel_mean,
+                        components.pixel_std,
+                        components.keyframe_encode_seed,
+                    )
+                )
+            elif reference.kind == "video":
+                # Snap *down* to `17 * n + 5` so the VAE encodes without padding; this only bites when the reference
+                # is shorter than the target, whose own frame count already has that form.
+                frames_per_chunk = components.vae_frames_per_chunk
+                latents_per_chunk = components.vae_latents_per_chunk
+                num_frames = reference.frames.shape[0]
+                num_frames = (
+                    max(1, (num_frames - latents_per_chunk) // frames_per_chunk) * frames_per_chunk + latents_per_chunk
+                )
+                pixels = torch.from_numpy(reference.frames[:num_frames].copy()).to(device).permute(3, 0, 1, 2)[None]
+                condition_latents.append(
+                    encode_vae_condition(
+                        components.vae,
+                        pixels,
+                        components.pixel_mean,
+                        components.pixel_std,
+                        components.keyframe_encode_seed,
+                    )
                 )
-                # The sampled latent is rounded to float16 before it is normalized: ~11 bits of every conditioning
-                # latent, so the released model's conditioning cannot be reproduced without it.
-                latents = latents.to(torch.float16).float().cpu()
-                video_latents.append((latents - latents_mean) / latents_std)
 
             if reference.has_audio:
                 posterior = components.audio_vae.encode(reference.audio.to(device)[:, None], return_dict=False)[0]
-                # Channel-major rows: the two stereo channels are two batch items of the mono audio VAE.
+                # Channel-major rows: the two stereo channels are two batch items of the mono audio VAE. Soundtracks
+                # take the posterior *mean*, and are never sampled.
                 latents = posterior.mode().float().cpu().transpose(1, 2)
                 normalized = (latents - audio_latents_mean) / audio_latents_std
-                audio_rows.append(normalized.reshape(-1, components.audio_latent_channels))
-
-        return video_latents, audio_rows
-
-    @torch.no_grad()
-    def __call__(self, components: MiniMaxH3Ref2VAModularPipeline, state: PipelineState) -> PipelineState:
-        block_state = self.get_block_state(state)
-        device = components._execution_device
+                audio_condition_latents.append(normalized.reshape(-1, components.audio_latent_channels))
 
-        block_state.condition_latents, block_state.audio_condition_latents = self.encode_references(
-            components, block_state.prepared_references, device=device
-        )
+        block_state.condition_latents = condition_latents
+        block_state.audio_condition_latents = audio_condition_latents
 
         self.set_block_state(state, block_state)
         return components, state
diff --git a/src/diffusers/modular_pipelines/minimax_h3/modular_blocks_minimax_h3.py b/src/diffusers/modular_pipelines/minimax_h3/modular_blocks_minimax_h3.py
index bfe300c4f09e..ec15f540400a 100644
--- a/src/diffusers/modular_pipelines/minimax_h3/modular_blocks_minimax_h3.py
+++ b/src/diffusers/modular_pipelines/minimax_h3/modular_blocks_minimax_h3.py
@@ -14,7 +14,7 @@
 
 import torch
 
-from ..modular_pipeline import ConditionalPipelineBlocks, SequentialPipelineBlocks
+from ..modular_pipeline import AutoPipelineBlocks, ConditionalPipelineBlocks, SequentialPipelineBlocks
 from ..modular_pipeline_utils import OutputParam
 from .before_denoise import (
     MiniMaxH3PrepareLatentsStep,
@@ -50,7 +50,7 @@ def _generation_outputs() -> list[OutputParam]:
 class MiniMaxH3AutoResizeStep(ConditionalPipelineBlocks):
     """
     Keyframe canvas block.
-       - MiniMaxH3ResizeStep runs for the `fl2va` task, whichever of the two keyframes is given.
+       - MiniMaxH3ResizeStep runs for the `fl2va` workflow, whichever of the two keyframes is given.
        - when neither `image` nor `last_image` is provided (`t2va`), this block is skipped and the layout step falls back to MiniMax-H3's own 16:9 canvas.
 
       Components:
@@ -95,7 +95,7 @@ def select_block(self, **kwargs) -> str | None:
     def description(self):
         return (
             "Keyframe canvas block.\n"
-            + " - MiniMaxH3ResizeStep runs for the `fl2va` task, whichever of the two keyframes is given.\n"
+            + " - MiniMaxH3ResizeStep runs for the `fl2va` workflow, whichever of the two keyframes is given.\n"
             + " - when neither `image` nor `last_image` is provided (`t2va`), this block is skipped and the layout "
             "step falls back to MiniMax-H3's own 16:9 canvas."
         )
@@ -105,7 +105,7 @@ def description(self):
 class MiniMaxH3AutoKeyframeVaeEncoderStep(ConditionalPipelineBlocks):
     """
     Keyframe conditioning block.
-       - MiniMaxH3KeyframeVaeEncoderStep runs for the `fl2va` task, whichever of the two keyframes is given.
+       - MiniMaxH3KeyframeVaeEncoderStep runs for the `fl2va` workflow, whichever of the two keyframes is given.
        - when neither `image` nor `last_image` is provided (`t2va`), this block is skipped.
 
       Components:
@@ -118,7 +118,8 @@ class MiniMaxH3AutoKeyframeVaeEncoderStep(ConditionalPipelineBlocks):
       Outputs:
           condition_latents (`list`):
               The normalized video conditioning latents, one `(1, latent_channels, 1, latent_height, latent_width)` tensor per
-              keyframe, in packed order.
+              keyframe, in packed order. One entry per condition is what the prepare-latents step draws its noise against, so the
+              list is the unit the request's generator is consumed in.
     """
 
     model_name = "minimax-h3"
@@ -136,88 +137,184 @@ def select_block(self, **kwargs) -> str | None:
     def description(self):
         return (
             "Keyframe conditioning block.\n"
-            + " - MiniMaxH3KeyframeVaeEncoderStep runs for the `fl2va` task, whichever of the two keyframes is given.\n"
-            + " - when neither `image` nor `last_image` is provided (`t2va`), this block is skipped."
+            + " - MiniMaxH3KeyframeVaeEncoderStep runs for the `fl2va` workflow, whichever of the two keyframes is "
+            "given.\n" + " - when neither `image` nor `last_image` is provided (`t2va`), this block is skipped."
         )
 
 
 # auto_docstring
-class MiniMaxH3DecodeStep(SequentialPipelineBlocks):
+class MiniMaxH3AutoBeforeEncodeStep(AutoPipelineBlocks):
     """
-    Decodes the denoised rows of the packed sequence into the generated video and its soundtrack.
+    Media preparation block.
+       - `MiniMaxH3Ref2VASetupStep` runs when `references` is provided (`ref2va`): it resolves the plan and normalizes every reference onto MiniMax-H3's own rates and resolutions.
+       - otherwise the keyframe canvas block runs, which itself is skipped for a text-only request.
 
       Components:
-          vae (`AutoencoderKLMiniMaxH3`)
-          video_processor (`VideoProcessor`)
-          audio_vae (`AutoencoderKLMiniMaxH3Audio`)
+          image_processor (`VaeImageProcessor`)
 
       Inputs:
-          latents (`Tensor`):
-              The generated video latents.
-          output_type (`str`, *optional*, defaults to pil):
-              Output format: 'pil', 'np' or 'pt'.
-          audio_latents (`Tensor`):
-              The generated audio latents, one batch item per stereo channel.
+          references (`list`, *optional*):
+              The references to condition on, **in the order the model should read them**: the order labels them in the prompt
+              presentation and lays them out on the shared rotary clock, so a different order is a different request. One
+              dataclass per modality, all holding in-memory media — a [`MiniMaxH3ImageReference`] (at most 9), a
+              [`MiniMaxH3VideoReference`] at its own `fps` (at most 3, whose `audio` soundtrack is conditioned on as well), or a
+              [`MiniMaxH3AudioReference`] at its own `sample_rate` (at most 3) — for at most 12 references in total, and audio
+              references cannot be the only ones. These blocks never open a media file: decode with
+              [`~modular_pipelines.minimax_h3.decode_reference_video`] and
+              [`~modular_pipelines.minimax_h3.decode_reference_audio`], which bring the rates along, or put a
+              [`MiniMaxH3Ref2VALoadReferencesStep`] in front of these blocks.
+          height (`int`, *optional*):
+              Height of the generated video in pixels, a multiple of 32.
+          width (`int`, *optional*):
+              Width of the generated video in pixels, a multiple of 32.
+          num_frames (`int`, *optional*):
+              Number of frames to generate, at the fixed 24 fps. Snapped up to the next `17 * n + 5` the video VAE can decode;
+              the resulting duration must stay between 5 and 15 seconds. To generate a video as long as a reference soundtrack,
+              pass `round(samples / sample_rate * 24)`.
+          image (`Image`, *optional*):
+              Keyframe the video starts from. It is *stretched* onto the target canvas, which by default is derived from its own
+              aspect ratio.
+          last_image (`Image`, *optional*):
+              Keyframe the video ends on. Can be passed on its own to generate *up to* a frame. Combined with `image` it is the
+              follower of the two and is cover-cropped onto the canvas.
 
       Outputs:
-          videos (`list`):
-              The generated video.
-          audio (`Tensor`):
-              The generated soundtrack, of shape `(1, 2, num_samples)`.
-          sampling_rate (`int`):
-              Sample rate of the generated soundtrack in Hz.
+          height (`int`):
+              Resolved height of the generated video in pixels.
+          width (`int`):
+              Resolved width of the generated video in pixels.
+          num_frames (`int`):
+              Resolved number of frames, of the form 17 * n + 5.
+          normalized_references (`list`):
+              The references normalized onto MiniMax-H3's own rates and resolutions, in packed order: the same public reference
+              types the request passed in, with an image resized to its own 2048 pixel short edge, a video resampled onto 24 fps
+              and onto the canvas its own aspect ratio resolves to, and a soundtrack put on the audio VAE's sample rate and
+              truncated to the generated duration.
+          keyframes (`list`):
+              The keyframes put onto the target canvas, in packed order.
+          keyframe_anchors (`tuple`):
+              Which end of the video every keyframe is anchored to, in packed order. Positional with `keyframes`, so both are
+              resolved here.
     """
 
     model_name = "minimax-h3"
-    block_classes = [MiniMaxH3VideoDecodeStep, MiniMaxH3AudioDecodeStep]
-    block_names = ["video", "audio"]
+    block_classes = [MiniMaxH3Ref2VASetupStep, MiniMaxH3AutoResizeStep]
+    block_names = ["ref2va", "keyframes"]
+    block_trigger_inputs = ["references", None]
 
     @property
     def description(self):
-        return "Decodes the denoised rows of the packed sequence into the generated video and its soundtrack."
-
-    @property
-    def outputs(self):
-        return _generation_outputs()
+        return (
+            "Media preparation block.\n"
+            + " - `MiniMaxH3Ref2VASetupStep` runs when `references` is provided (`ref2va`): it resolves the plan and "
+            "normalizes every reference onto MiniMax-H3's own rates and resolutions.\n"
+            + " - otherwise the keyframe canvas block runs, which itself is skipped for a text-only request."
+        )
 
 
 # auto_docstring
-class MiniMaxH3Blocks(SequentialPipelineBlocks):
+class MiniMaxH3AutoTextEncoderStep(AutoPipelineBlocks):
     """
-    Modular pipeline blocks for joint video + audio generation with MiniMax-H3, covering the `t2va` (text only) and `fl2va` (first and/or last keyframe) tasks of the FL2VA checkpoint.
-
-      Supported workflows:
-        - `t2va`: requires `prompt`
-        - `fl2va`: requires `prompt`, `image`
-        - `fl2va_last_frame`: requires `prompt`, `last_image`
+    Text encoder block. Both branches encode MiniMax-H3's presentation of the request with the Qwen3-VL conditioner.
+       - `MiniMaxH3Ref2VATextEncoderStep` runs when `references` is provided (`ref2va`), labelling every reference in the presentation.
+       - `MiniMaxH3TextEncoderStep` runs otherwise, labelling the keyframes when there are any.
 
       Components:
-          image_processor (`VaeImageProcessor`)
           text_encoder (`Qwen3VLForConditionalGeneration`)
           tokenizer (`Qwen2Tokenizer`)
           processor (`Qwen3VLProcessor`)
+
+      Inputs:
+          prompt (`str`):
+              The prompt to guide generation, a single string.
+          normalized_references (`list`, *optional*):
+              The references normalized by the setup step, in packed order.
+          keyframes (`list`, *optional*):
+              The keyframes put onto the target canvas, in packed order (empty or None for `t2va`).
+
+      Outputs:
+          prompt_embeds (`Tensor`):
+              The hidden state MiniMax-H3 conditions on, of shape `(1, num_text_tokens, 5120)`, read after the 50th decoder layer
+              of the Qwen3-VL conditioner.
+          text_token_tags (`Tensor`):
+              The per-row modality tag of every row of `prompt_embeds`; a vision block is tagged as video.
+    """
+
+    model_name = "minimax-h3"
+    block_classes = [MiniMaxH3Ref2VATextEncoderStep, MiniMaxH3TextEncoderStep]
+    block_names = ["ref2va", "t2va"]
+    block_trigger_inputs = ["references", None]
+
+    @property
+    def description(self):
+        return (
+            "Text encoder block. Both branches encode MiniMax-H3's presentation of the request with the Qwen3-VL "
+            "conditioner.\n"
+            + " - `MiniMaxH3Ref2VATextEncoderStep` runs when `references` is provided (`ref2va`), labelling every "
+            "reference in the presentation.\n"
+            + " - `MiniMaxH3TextEncoderStep` runs otherwise, labelling the keyframes when there are any."
+        )
+
+
+# auto_docstring
+class MiniMaxH3AutoVaeEncoderStep(AutoPipelineBlocks):
+    """
+    VAE encoder block.
+       - `MiniMaxH3Ref2VAReferenceEncoderStep` runs when `references` is provided (`ref2va`).
+       - otherwise the keyframe conditioning block runs, which itself is skipped for a text-only request.
+
+      Components:
           vae (`AutoencoderKLMiniMaxH3`)
+          audio_vae (`AutoencoderKLMiniMaxH3Audio`)
+
+      Inputs:
+          normalized_references (`list`, *optional*):
+              The references normalized by the setup step, in packed order.
+          keyframes (`list`, *optional*):
+              The keyframes put onto the target canvas, in packed order.
+
+      Outputs:
+          condition_latents (`list`):
+              The encoded video conditioning latents of the image and video references, one `(1, latent_channels,
+              num_latent_frames, latent_height, latent_width)` tensor each in packed order, or None when the references carry
+              none.
+          audio_condition_latents (`list`):
+              The clean audio conditioning rows of the reference soundtracks, one `(num_audio_latents * 2,
+              audio_latent_channels)` tensor per audio-bearing reference in packed order. One entry per reference rather than one
+              concatenated block, because the packed layout is built from the row count of each.
+    """
+
+    model_name = "minimax-h3"
+    block_classes = [MiniMaxH3Ref2VAReferenceEncoderStep, MiniMaxH3AutoKeyframeVaeEncoderStep]
+    block_names = ["ref2va", "keyframes"]
+    block_trigger_inputs = ["references", None]
+
+    @property
+    def description(self):
+        return (
+            "VAE encoder block.\n"
+            + " - `MiniMaxH3Ref2VAReferenceEncoderStep` runs when `references` is provided (`ref2va`).\n"
+            + " - otherwise the keyframe conditioning block runs, which itself is skipped for a text-only request."
+        )
+
+
+# auto_docstring
+class MiniMaxH3CoreDenoiseStep(SequentialPipelineBlocks):
+    """
+    Core denoising workflow for `t2va` / `fl2va`: builds the packed layout, draws and packs the noise, plans the per-row timesteps and runs the denoising loop against the `transformer` partition.
+
+      Components:
           scheduler (`MiniMaxH3Scheduler`)
           audio_scheduler (`MiniMaxH3Scheduler`)
           transformer (`MiniMaxH3Transformer3DModel`)
-          video_processor (`VideoProcessor`)
-          audio_vae (`AutoencoderKLMiniMaxH3Audio`)
 
       Inputs:
-          image (`Image`, *optional*):
-              Keyframe the video starts from. It is *stretched* onto the target canvas, which by default is derived from its own
-              aspect ratio.
-          last_image (`Image`, *optional*):
-              Keyframe the video ends on. Can be passed on its own to generate *up to* a frame. Combined with `image` it is the
-              follower of the two and is cover-cropped onto the canvas.
+          text_token_tags (`Tensor`):
+              The per-row modality tag of every row of `prompt_embeds`.
           height (`int`, *optional*):
               Height of the generated video in pixels, a multiple of 32.
           width (`int`, *optional*):
               Width of the generated video in pixels, a multiple of 32.
-          prompt (`str`):
-              The prompt to guide generation, a single string.
-          keyframes (`list`, *optional*):
-              The keyframes put onto the target canvas, in packed order (empty or None for `t2va`).
           num_frames (`int`, *optional*, defaults to 124):
               Number of frames to generate, at the fixed 24 fps. Snapped up to the next `17 * n + 5` the video VAE can decode;
               the resulting duration must stay between 5 and 15 seconds.
@@ -233,81 +330,352 @@ class MiniMaxH3Blocks(SequentialPipelineBlocks):
           condition_latents (`list`, *optional*):
               The encoded video conditioning latents, one `(1, latent_channels, num_latent_frames, latent_height, latent_width)`
               tensor per condition in packed order, or None for a request that has none. Noised and packed here.
-          audio_condition_latents (`Tensor`, *optional*):
-              The audio conditioning rows to prepend, or None for a request that has none.
+          audio_condition_latents (`list`, *optional*):
+              The audio conditioning rows to prepend, one tensor per audio-bearing reference in packed order. Empty for a request
+              that has none, which is every `t2va` and `fl2va` one.
           num_inference_steps (`int`):
               The number of denoising steps.
+          prompt_embeds (`Tensor`):
+              text embeddings used to guide the image generation. Can be generated from text_encoder step.
           **denoiser_input_fields (`None`, *optional*):
               The structural description of the packed sequence the transformer reads by name: `token_tags`, `position_ids` and
               the three row-index tensors.
           attention_kwargs (`dict`, *optional*):
               Additional kwargs for attention processors.
-          output_type (`str`, *optional*, defaults to pil):
-              Output format: 'pil', 'np' or 'pt'.
 
       Outputs:
-          videos (`list`):
-              The generated video.
-          audio (`Tensor`):
-              The generated soundtrack, of shape `(1, 2, num_samples)`.
-          sampling_rate (`int`):
-              Sample rate of the generated soundtrack in Hz.
+          height (`int`):
+              Resolved height of the generated video in pixels.
+          width (`int`):
+              Resolved width of the generated video in pixels.
+          num_frames (`int`):
+              Resolved number of frames, of the form 17 * n + 5.
+          num_latent_frames (`int`):
+              Number of generated video latent frames.
+          latent_height (`int`):
+              Height of the generated video latents.
+          latent_width (`int`):
+              Width of the generated video latents.
+          num_audio_latents (`int`):
+              Number of generated audio latents per channel.
+          position_ids (`Tensor`):
+              The `(t, h, w)` rotary coordinate of every row, in float64.
+          token_tags (`Tensor`):
+              The modality tag of every row.
+          video_indices (`Tensor`):
+              Sequence positions of the video rows, conditioning rows first.
+          audio_indices (`Tensor`):
+              Sequence positions of the audio rows, reference rows first.
+          text_indices (`Tensor`):
+              Sequence positions of the text rows.
+          num_condition_video_rows (`int`):
+              How many leading video rows are conditioning rows rather than generated rows.
+          num_condition_audio_rows (`int`):
+              How many leading audio rows are reference rows rather than generated rows.
+          latents (`Tensor`):
+              The video rows of the packed sequence, conditioning rows first.
+          audio_latents (`Tensor`):
+              The channel-major audio rows of the packed sequence, reference rows first.
+          timesteps (`Tensor`):
+              Timesteps of the video schedule.
+          audio_timesteps (`Tensor`):
+              Timesteps of the audio schedule.
+          row_timestep_plan (`list`):
+              One `(timestep, timestep_indices)` pair per step: the distinct timesteps of the sequence and the index of every row
+              into them.
+          noise_pred (`Tensor`):
+              Predicted velocity of the video rows of the sequence.
+          audio_noise_pred (`Tensor`):
+              Predicted velocity of the audio rows of the sequence.
     """
 
     model_name = "minimax-h3"
     block_classes = [
-        MiniMaxH3AutoResizeStep,
-        MiniMaxH3TextEncoderStep,
-        MiniMaxH3AutoKeyframeVaeEncoderStep,
         MiniMaxH3PrepareLayoutStep,
         MiniMaxH3PrepareLatentsStep,
         MiniMaxH3SetTimestepsStep,
         MiniMaxH3DenoiseStep,
-        MiniMaxH3AfterDenoiseStep,
-        MiniMaxH3DecodeStep,
     ]
-    block_names = [
-        "resize",
-        "text_encoder",
-        "vae_encoder",
-        "prepare_layout",
-        "prepare_latents",
-        "set_timesteps",
-        "denoise",
-        "after_denoise",
-        "decode",
+    block_names = ["prepare_layout", "prepare_latents", "set_timesteps", "denoise"]
+
+    @property
+    def description(self):
+        return (
+            "Core denoising workflow for `t2va` / `fl2va`: builds the packed layout, draws and packs the noise, "
+            "plans the per-row timesteps and runs the denoising loop against the `transformer` partition."
+        )
+
+
+# auto_docstring
+class MiniMaxH3Ref2VACoreDenoiseStep(SequentialPipelineBlocks):
+    """
+    Core denoising workflow for `ref2va`: builds the packed layout with one block per reference, draws and packs the noise, plans the per-row timesteps and runs the denoising loop against the `transformer_ref` partition.
+
+      Components:
+          scheduler (`MiniMaxH3Scheduler`)
+          audio_scheduler (`MiniMaxH3Scheduler`)
+          transformer_ref (`MiniMaxH3Transformer3DModel`)
+
+      Inputs:
+          text_token_tags (`Tensor`):
+              The per-row modality tag of every row of `prompt_embeds`.
+          normalized_references (`list`):
+              The references normalized by the setup step, in packed order.
+          condition_latents (`list`):
+              The encoded video conditioning latents, one per image and video reference in packed order. Their shape is where
+              every reference block's geometry comes from.
+          audio_condition_latents (`list`):
+              The encoded audio conditioning rows, one per audio-bearing reference in packed order.
+          height (`int`):
+              Height of the generated video in pixels.
+          width (`int`):
+              Width of the generated video in pixels.
+          num_frames (`int`):
+              Resolved number of frames, of the form 17 * n + 5.
+          generator (`Generator`, *optional*):
+              The generator of the request. The video noise is drawn from it first, then the audio noise.
+          latents (`Tensor`, *optional*):
+              Pre-generated video noise of shape `(1, 24, num_latent_frames, latent_height, latent_width)`, used instead of the
+              draw.
+          audio_latents (`Tensor`, *optional*):
+              Pre-generated audio noise of shape `(2, 32, num_audio_latents)`.
+          num_inference_steps (`int`):
+              The number of denoising steps.
+          prompt_embeds (`Tensor`):
+              text embeddings used to guide the image generation. Can be generated from text_encoder step.
+          **denoiser_input_fields (`None`, *optional*):
+              The structural description of the packed sequence the transformer reads by name: `token_tags`, `position_ids` and
+              the three row-index tensors.
+          attention_kwargs (`dict`, *optional*):
+              Additional kwargs for attention processors.
+
+      Outputs:
+          height (`int`):
+              Resolved height of the generated video in pixels.
+          width (`int`):
+              Resolved width of the generated video in pixels.
+          num_frames (`int`):
+              Resolved number of frames, of the form 17 * n + 5.
+          num_latent_frames (`int`):
+              Number of generated video latent frames.
+          latent_height (`int`):
+              Height of the generated video latents.
+          latent_width (`int`):
+              Width of the generated video latents.
+          num_audio_latents (`int`):
+              Number of generated audio latents per channel.
+          position_ids (`Tensor`):
+              The `(t, h, w)` rotary coordinate of every row, in float64.
+          token_tags (`Tensor`):
+              The modality tag of every row.
+          video_indices (`Tensor`):
+              Sequence positions of the video rows, conditioning rows first.
+          audio_indices (`Tensor`):
+              Sequence positions of the audio rows, reference rows first.
+          text_indices (`Tensor`):
+              Sequence positions of the text rows.
+          num_condition_video_rows (`int`):
+              How many leading video rows are conditioning rows rather than generated rows.
+          num_condition_audio_rows (`int`):
+              How many leading audio rows are reference rows rather than generated rows.
+          latents (`Tensor`):
+              The video rows of the packed sequence, conditioning rows first.
+          audio_latents (`Tensor`):
+              The channel-major audio rows of the packed sequence, reference rows first.
+          timesteps (`Tensor`):
+              Timesteps of the video schedule.
+          audio_timesteps (`Tensor`):
+              Timesteps of the audio schedule.
+          row_timestep_plan (`list`):
+              One `(timestep, timestep_indices)` pair per step: the distinct timesteps of the sequence and the index of every row
+              into them.
+          noise_pred (`Tensor`):
+              Predicted velocity of the video rows of the sequence.
+          audio_noise_pred (`Tensor`):
+              Predicted velocity of the audio rows of the sequence.
+    """
+
+    model_name = "minimax-h3"
+    block_classes = [
+        MiniMaxH3Ref2VAPrepareLayoutStep,
+        MiniMaxH3PrepareLatentsStep,
+        MiniMaxH3SetTimestepsStep,
+        MiniMaxH3Ref2VADenoiseStep,
     ]
-    # One repository holds both checkpoint partitions, so the two blocksets are two workflows over one shared
-    # `modular_model_index.json`, and each declares only the components its own half loads. The keys below are the
-    # task names a `workflow=` argument to `ModularPipeline.from_pretrained` would take, so that the component subset
-    # of a task can be resolved from the index without instantiating the blocks first.
-    _workflow_map = {
-        "t2va": {"prompt": True},
-        "fl2va": {"prompt": True, "image": True},
-        "fl2va_last_frame": {"prompt": True, "last_image": True},
-    }
+    block_names = ["prepare_layout", "prepare_latents", "set_timesteps", "denoise"]
+
+    @property
+    def description(self):
+        return (
+            "Core denoising workflow for `ref2va`: builds the packed layout with one block per reference, draws and "
+            "packs the noise, plans the per-row timesteps and runs the denoising loop against the `transformer_ref` "
+            "partition."
+        )
+
+
+# auto_docstring
+class MiniMaxH3AutoDenoiseStep(AutoPipelineBlocks):
+    """
+    Denoise block.
+       - `MiniMaxH3Ref2VACoreDenoiseStep` runs when `references` is provided (`ref2va`), against the `transformer_ref` checkpoint partition.
+       - `MiniMaxH3CoreDenoiseStep` runs otherwise, against the `transformer` partition.
+
+      Components:
+          scheduler (`MiniMaxH3Scheduler`)
+          audio_scheduler (`MiniMaxH3Scheduler`)
+          transformer_ref (`MiniMaxH3Transformer3DModel`)
+          transformer (`MiniMaxH3Transformer3DModel`)
+
+      Inputs:
+          text_token_tags (`Tensor`):
+              The per-row modality tag of every row of `prompt_embeds`.
+          normalized_references (`list`, *optional*):
+              The references normalized by the setup step, in packed order.
+          condition_latents (`list`, *optional*):
+              The encoded video conditioning latents, one per image and video reference in packed order. Their shape is where
+              every reference block's geometry comes from.
+          audio_condition_latents (`list`, *optional*):
+              The encoded audio conditioning rows, one per audio-bearing reference in packed order.
+          height (`int`, *optional*):
+              Height of the generated video in pixels.
+          width (`int`, *optional*):
+              Width of the generated video in pixels.
+          num_frames (`int`, *optional*, defaults to 124):
+              Number of frames to generate, at the fixed 24 fps. Snapped up to the next `17 * n + 5` the video VAE can decode;
+              the resulting duration must stay between 5 and 15 seconds.
+          generator (`Generator`, *optional*):
+              The generator of the request. The video noise is drawn from it first, then the audio noise.
+          latents (`Tensor`):
+              Pre-generated video noise of shape `(1, 24, num_latent_frames, latent_height, latent_width)`, used instead of the
+              draw.
+          audio_latents (`Tensor`):
+              Pre-generated audio noise of shape `(2, 32, num_audio_latents)`.
+          num_inference_steps (`int`):
+              The number of denoising steps.
+          prompt_embeds (`Tensor`):
+              text embeddings used to guide the image generation. Can be generated from text_encoder step.
+          **denoiser_input_fields (`None`, *optional*):
+              The structural description of the packed sequence the transformer reads by name: `token_tags`, `position_ids` and
+              the three row-index tensors.
+          attention_kwargs (`dict`, *optional*):
+              Additional kwargs for attention processors.
+          keyframe_anchors (`tuple`, *optional*, defaults to ()):
+              Which end of the video every keyframe is anchored to, in packed order.
+
+      Outputs:
+          height (`int`):
+              Resolved height of the generated video in pixels.
+          width (`int`):
+              Resolved width of the generated video in pixels.
+          num_frames (`int`):
+              Resolved number of frames, of the form 17 * n + 5.
+          num_latent_frames (`int`):
+              Number of generated video latent frames.
+          latent_height (`int`):
+              Height of the generated video latents.
+          latent_width (`int`):
+              Width of the generated video latents.
+          num_audio_latents (`int`):
+              Number of generated audio latents per channel.
+          position_ids (`Tensor`):
+              The `(t, h, w)` rotary coordinate of every row, in float64.
+          token_tags (`Tensor`):
+              The modality tag of every row.
+          video_indices (`Tensor`):
+              Sequence positions of the video rows, conditioning rows first.
+          audio_indices (`Tensor`):
+              Sequence positions of the audio rows, reference rows first.
+          text_indices (`Tensor`):
+              Sequence positions of the text rows.
+          num_condition_video_rows (`int`):
+              How many leading video rows are conditioning rows rather than generated rows.
+          num_condition_audio_rows (`int`):
+              How many leading audio rows are reference rows rather than generated rows.
+          latents (`Tensor`):
+              The video rows of the packed sequence, conditioning rows first.
+          audio_latents (`Tensor`):
+              The channel-major audio rows of the packed sequence, reference rows first.
+          timesteps (`Tensor`):
+              Timesteps of the video schedule.
+          audio_timesteps (`Tensor`):
+              Timesteps of the audio schedule.
+          row_timestep_plan (`list`):
+              One `(timestep, timestep_indices)` pair per step: the distinct timesteps of the sequence and the index of every row
+              into them.
+          noise_pred (`Tensor`):
+              Predicted velocity of the video rows of the sequence.
+          audio_noise_pred (`Tensor`):
+              Predicted velocity of the audio rows of the sequence.
+    """
+
+    model_name = "minimax-h3"
+    block_classes = [MiniMaxH3Ref2VACoreDenoiseStep, MiniMaxH3CoreDenoiseStep]
+    block_names = ["ref2va", "t2va"]
+    block_trigger_inputs = ["references", None]
 
     @property
     def description(self):
         return (
-            "Modular pipeline blocks for joint video + audio generation with MiniMax-H3, covering the `t2va` (text "
-            "only) and `fl2va` (first and/or last keyframe) tasks of the FL2VA checkpoint."
+            "Denoise block.\n"
+            + " - `MiniMaxH3Ref2VACoreDenoiseStep` runs when `references` is provided (`ref2va`), against the "
+            "`transformer_ref` checkpoint partition.\n"
+            + " - `MiniMaxH3CoreDenoiseStep` runs otherwise, against the `transformer` partition."
         )
 
+
+# auto_docstring
+class MiniMaxH3DecodeStep(SequentialPipelineBlocks):
+    """
+    Decodes the denoised rows of the packed sequence into the generated video and its soundtrack.
+
+      Components:
+          vae (`AutoencoderKLMiniMaxH3`)
+          video_processor (`VideoProcessor`)
+          audio_vae (`AutoencoderKLMiniMaxH3Audio`)
+
+      Inputs:
+          latents (`Tensor`):
+              The generated video latents.
+          output_type (`str`, *optional*, defaults to pil):
+              Output format: 'pil', 'np' or 'pt'.
+          audio_latents (`Tensor`):
+              The generated audio latents, one batch item per stereo channel.
+
+      Outputs:
+          videos (`list`):
+              The generated video.
+          audio (`Tensor`):
+              The generated soundtrack, of shape `(1, 2, num_samples)`.
+          sampling_rate (`int`):
+              Sample rate of the generated soundtrack in Hz.
+    """
+
+    model_name = "minimax-h3"
+    block_classes = [MiniMaxH3VideoDecodeStep, MiniMaxH3AudioDecodeStep]
+    block_names = ["video", "audio"]
+
+    @property
+    def description(self):
+        return "Decodes the denoised rows of the packed sequence into the generated video and its soundtrack."
+
     @property
     def outputs(self):
         return _generation_outputs()
 
 
 # auto_docstring
-class MiniMaxH3Ref2VABlocks(SequentialPipelineBlocks):
+class MiniMaxH3Blocks(SequentialPipelineBlocks):
     """
-    Modular pipeline blocks for joint video + audio generation from an ordered list of image, video and audio references with MiniMax-H3, the `ref2va` task of the Ref2VA checkpoint.
+    Auto Modular pipeline blocks for joint video + audio generation with MiniMax-H3: the `t2va` (text only), `fl2va` (first and/or last keyframe) and `ref2va` (omni-reference) workflows, selected on the `references` and keyframe inputs. Without a `workflow=`, loading the components pulls **both** 61.7GB transformer partitions — pass one to load only what the task needs.
 
       Supported workflows:
+        - `t2va`: requires `prompt`
+        - `fl2va`: requires `prompt`, `image`
+        - `fl2va_last_frame`: requires `prompt`, `last_image`
         - `ref2va`: requires `prompt`, `references`
 
       Components:
+          image_processor (`VaeImageProcessor`)
           text_encoder (`Qwen3VLForConditionalGeneration`)
           tokenizer (`Qwen2Tokenizer`)
           processor (`Qwen3VLProcessor`)
@@ -316,32 +684,42 @@ class MiniMaxH3Ref2VABlocks(SequentialPipelineBlocks):
           scheduler (`MiniMaxH3Scheduler`)
           audio_scheduler (`MiniMaxH3Scheduler`)
           transformer_ref (`MiniMaxH3Transformer3DModel`)
+          transformer (`MiniMaxH3Transformer3DModel`)
           video_processor (`VideoProcessor`)
 
       Inputs:
-          references (`list`):
+          references (`list`, *optional*):
               The references to condition on, **in the order the model should read them**: the order labels them in the prompt
-              presentation and lays them out on the shared rotary clock, so a different order is a different request. Every
-              [`MiniMaxH3Reference`] carries exactly one medium, a path or in-memory media — `image` (at most 9), `video` at its
-              own `fps` (at most 3, whose `audio` soundtrack is conditioned on as well), or `audio` at its own `sample_rate` (at
-              most 3) — for at most 12 references in total, and audio references cannot be the only ones. A path is decoded when
-              the reference is built, so these blocks only ever see pixels and samples.
+              presentation and lays them out on the shared rotary clock, so a different order is a different request. One
+              dataclass per modality, all holding in-memory media — a [`MiniMaxH3ImageReference`] (at most 9), a
+              [`MiniMaxH3VideoReference`] at its own `fps` (at most 3, whose `audio` soundtrack is conditioned on as well), or a
+              [`MiniMaxH3AudioReference`] at its own `sample_rate` (at most 3) — for at most 12 references in total, and audio
+              references cannot be the only ones. These blocks never open a media file: decode with
+              [`~modular_pipelines.minimax_h3.decode_reference_video`] and
+              [`~modular_pipelines.minimax_h3.decode_reference_audio`], which bring the rates along, or put a
+              [`MiniMaxH3Ref2VALoadReferencesStep`] in front of these blocks.
           height (`int`, *optional*):
               Height of the generated video in pixels, a multiple of 32.
           width (`int`, *optional*):
               Width of the generated video in pixels, a multiple of 32.
           num_frames (`int`, *optional*):
-              Number of frames to generate, at the fixed 24 fps. Snapped up to the next `17 * n + 5` the video VAE can decode.
-              May be left out, but only when exactly one reference carries audio, in which case the duration is that
-              soundtrack's.
+              Number of frames to generate, at the fixed 24 fps. Snapped up to the next `17 * n + 5` the video VAE can decode;
+              the resulting duration must stay between 5 and 15 seconds. To generate a video as long as a reference soundtrack,
+              pass `round(samples / sample_rate * 24)`.
+          image (`Image`, *optional*):
+              Keyframe the video starts from. It is *stretched* onto the target canvas, which by default is derived from its own
+              aspect ratio.
+          last_image (`Image`, *optional*):
+              Keyframe the video ends on. Can be passed on its own to generate *up to* a frame. Combined with `image` it is the
+              follower of the two and is cover-cropped onto the canvas.
           prompt (`str`):
               The prompt to guide generation, a single string.
           generator (`Generator`, *optional*):
               The generator of the request. The video noise is drawn from it first, then the audio noise.
-          latents (`Tensor`, *optional*):
+          latents (`Tensor`):
               Pre-generated video noise of shape `(1, 24, num_latent_frames, latent_height, latent_width)`, used instead of the
               draw.
-          audio_latents (`Tensor`, *optional*):
+          audio_latents (`Tensor`):
               Pre-generated audio noise of shape `(2, 32, num_audio_latents)`.
           num_inference_steps (`int`):
               The number of denoising steps.
@@ -362,42 +740,42 @@ class MiniMaxH3Ref2VABlocks(SequentialPipelineBlocks):
               Sample rate of the generated soundtrack in Hz.
     """
 
-    # The `ref2va` task family has its own `MODULAR_PIPELINE_MAPPING` key, so that `init_pipeline` resolves
-    # `MiniMaxH3Ref2VAModularPipeline` (and its `transformer_ref` partition) rather than the FL2VA one.
-    model_name = "minimax-h3-ref2va"
+    model_name = "minimax-h3"
     block_classes = [
-        MiniMaxH3Ref2VASetupStep,
-        MiniMaxH3Ref2VATextEncoderStep,
-        MiniMaxH3Ref2VAReferenceEncoderStep,
-        MiniMaxH3Ref2VAPrepareLayoutStep,
-        MiniMaxH3PrepareLatentsStep,
-        MiniMaxH3SetTimestepsStep,
-        MiniMaxH3Ref2VADenoiseStep,
+        MiniMaxH3AutoBeforeEncodeStep,
+        MiniMaxH3AutoTextEncoderStep,
+        MiniMaxH3AutoVaeEncoderStep,
+        MiniMaxH3AutoDenoiseStep,
         MiniMaxH3AfterDenoiseStep,
         MiniMaxH3DecodeStep,
     ]
     block_names = [
-        "setup",
+        "before_encode",
         "text_encoder",
-        "reference_encoder",
-        "prepare_layout",
-        "prepare_latents",
-        "set_timesteps",
+        "vae_encoder",
         "denoise",
         "after_denoise",
         "decode",
     ]
-    # The `ref2va` task name, i.e. the value a `workflow=` argument to `ModularPipeline.from_pretrained` would take
-    # to resolve this half — and its `transformer_ref` partition — out of the shared `modular_model_index.json`.
+    # One repository holds both checkpoint partitions (`transformer/` for `t2va`/`fl2va`, `transformer_ref/` for
+    # `ref2va`), so the tasks are workflows over one shared `modular_model_index.json`, each declaring only the
+    # components its own half loads. The keys below are the task names a `workflow=` argument to
+    # `ModularPipeline.from_pretrained` takes, so that the component subset of a task can be resolved from the index
+    # without instantiating the blocks first.
     _workflow_map = {
+        "t2va": {"prompt": True},
+        "fl2va": {"prompt": True, "image": True},
+        "fl2va_last_frame": {"prompt": True, "last_image": True},
         "ref2va": {"prompt": True, "references": True},
     }
 
     @property
     def description(self):
         return (
-            "Modular pipeline blocks for joint video + audio generation from an ordered list of image, video and "
-            "audio references with MiniMax-H3, the `ref2va` task of the Ref2VA checkpoint."
+            "Auto Modular pipeline blocks for joint video + audio generation with MiniMax-H3: the `t2va` (text "
+            "only), `fl2va` (first and/or last keyframe) and `ref2va` (omni-reference) workflows, selected on the "
+            "`references` and keyframe inputs. Without a `workflow=`, loading the components pulls **both** 61.7GB "
+            "transformer partitions — pass one to load only what the task needs."
         )
 
     @property
diff --git a/src/diffusers/modular_pipelines/minimax_h3/modular_pipeline.py b/src/diffusers/modular_pipelines/minimax_h3/modular_pipeline.py
index f4084d03b0e7..925a9a0058ac 100644
--- a/src/diffusers/modular_pipelines/minimax_h3/modular_pipeline.py
+++ b/src/diffusers/modular_pipelines/minimax_h3/modular_pipeline.py
@@ -14,21 +14,131 @@
 
 from ...utils import logging
 from ..modular_pipeline import ModularPipeline
-from .packing import (
-    MINIMAX_H3_AUDIO_CHANNELS,
-    MINIMAX_H3_FPS,
-    MINIMAX_H3_TEXT_TAG,
-    MINIMAX_H3_VIDEO_TAG,
-)
 
 
 logger = logging.get_logger(__name__)  # pylint: disable=invalid-name
 
 
+# Per-row modality tags. They index the transformer's AdaLN table, so the values are a checkpoint contract.
+MINIMAX_H3_VIDEO_TAG = 0
+MINIMAX_H3_TEXT_TAG = 1
+MINIMAX_H3_AUDIO_TAG = 2
+
+# MiniMax-H3 generates at a fixed 24 fps and was released for a 768 pixel short edge only, with a soft area cap of
+# 768x1344. The multiple both axes round to follows from
+# the VAE and the transformer, so it is `MiniMaxH3ModularPipeline.canvas_multiple` below and reaches these helpers
+# as an argument.
+MINIMAX_H3_FPS = 24
+MINIMAX_H3_SHORT_EDGE = 768
+MINIMAX_H3_MAX_PIXELS = 768 * 1344
+MINIMAX_H3_MIN_ASPECT_RATIO = 1 / 4
+MINIMAX_H3_MAX_ASPECT_RATIO = 4
+
+# The audio VAE hops 800 samples at 32 kHz, i.e. 40 latents per second. Stereo is carried as two channel-major
+# blocks of audio rows (and as two batch items at the audio VAE boundary, which is mono).
+MINIMAX_H3_AUDIO_LATENTS_PER_SECOND = 40
+MINIMAX_H3_AUDIO_CHANNELS = 2
+
+
+def resolve_canvas_size(aspect_width: float, aspect_height: float, canvas_multiple: int) -> tuple[int, int]:
+    r"""
+    Resolve a display aspect ratio into a MiniMax-H3 canvas.
+
+    The short edge starts at 768, the area is capped at `768 * 1344` and both axes are then rounded to the nearest
+    `canvas_multiple` — so the final area may end up slightly above the pre-rounding budget. Only the ratio of the two
+    arguments matters; pass either the aspect ratio (`16, 9`) or the source dimensions of a keyframe.
+
+    Args:
+        aspect_width (`float`): Width of the target ratio.
+        aspect_height (`float`): Height of the target ratio.
+        canvas_multiple (`int`):
+            What both axes round to, i.e. `components.canvas_multiple` — 32 for the released checkpoint.
+
+    Returns:
+        `tuple[int, int]`: the `(height, width)` of the canvas.
+    """
+    if aspect_width <= 0 or aspect_height <= 0:
+        raise ValueError(f"The aspect ratio must be positive, got {aspect_width}:{aspect_height}.")
+
+    ratio = aspect_width / aspect_height
+    if not MINIMAX_H3_MIN_ASPECT_RATIO <= ratio <= MINIMAX_H3_MAX_ASPECT_RATIO:
+        raise ValueError(
+            f"MiniMax-H3 supports aspect ratios from 1:4 to 4:1, got {aspect_width}:{aspect_height} ({ratio:g})."
+        )
+
+    if ratio >= 1.0:
+        width, height = MINIMAX_H3_SHORT_EDGE * ratio, float(MINIMAX_H3_SHORT_EDGE)
+    else:
+        width, height = float(MINIMAX_H3_SHORT_EDGE), MINIMAX_H3_SHORT_EDGE / ratio
+
+    area = width * height
+    if area > MINIMAX_H3_MAX_PIXELS:
+        scale = (MINIMAX_H3_MAX_PIXELS / area) ** 0.5
+        width, height = width * scale, height * scale
+
+    multiple = canvas_multiple
+    return max(multiple, round(height / multiple) * multiple), max(multiple, round(width / multiple) * multiple)
+
+
+def align_num_frames(num_frames: int, frames_per_chunk: int, latents_per_chunk: int) -> int:
+    r"""
+    Snap a frame count up to the next `frames_per_chunk * n + latents_per_chunk` the video VAE can encode.
+
+    Args:
+        num_frames (`int`): The requested number of frames.
+        frames_per_chunk (`int`): Pixel frames the video VAE encodes per chunk, its `clip_length`.
+        latents_per_chunk (`int`): Latent frames a chunk keeps, the VAE's `tokens_chunk_size`.
+
+    Returns:
+        `int`: The aligned number of frames.
+    """
+    if num_frames < 1:
+        raise ValueError(f"`num_frames` must be positive, got {num_frames}.")
+    while num_frames % frames_per_chunk != latents_per_chunk:
+        num_frames += 1
+    return num_frames
+
+
+def video_latent_num_frames(num_frames: int, frames_per_chunk: int, latents_per_chunk: int) -> int:
+    r"""
+    The number of latent frames the video VAE produces for a `17 * n + 5` frame count.
+
+    Args:
+        num_frames (`int`): An aligned number of frames.
+
+    Returns:
+        `int`: The number of latent frames, `5 * n + 2`.
+    """
+    if num_frames % frames_per_chunk != latents_per_chunk:
+        raise ValueError(
+            f"`num_frames` must be of the form {frames_per_chunk} * n + {latents_per_chunk}, got {num_frames}."
+        )
+    return (num_frames - latents_per_chunk) // frames_per_chunk * latents_per_chunk + 2
+
+
+def audio_latent_num_frames(num_frames: int) -> int:
+    r"""
+    The number of audio latents that covers a video of `num_frames` frames at 24 fps.
+
+    Args:
+        num_frames (`int`): The number of video frames.
+
+    Returns:
+        `int`: The number of audio latents, rounded at the 40 Hz latent grid.
+    """
+    return int(round(num_frames / MINIMAX_H3_FPS * MINIMAX_H3_AUDIO_LATENTS_PER_SECOND))
+
+
 class MiniMaxH3ModularPipeline(ModularPipeline):
     """
-    A ModularPipeline for joint video + audio generation with MiniMax-H3, covering the `t2va` (text only) and `fl2va`
-    (first and/or last keyframe) tasks of the FL2VA checkpoint.
+    A ModularPipeline for joint video + audio generation with MiniMax-H3: the `t2va` (text only) and `fl2va` (first
+    and/or last keyframe) workflows against the `transformer/` checkpoint partition, and the `ref2va` (omni-reference)
+    workflow against `transformer_ref/`. One repository holds both partitions, and selecting a workflow loads only its
+    own:
+
+    ```py
+    pipe = ModularPipeline.from_pretrained("MiniMaxAI/MiniMax-H3", workflow="ref2va")
+    ```
 
     MiniMax-H3 denoises **one packed sequence** that holds the text conditioning, the keyframe conditioning latents,
     the audio latents and the video latents at once, which is why the blocks pass a row layout around rather than
@@ -39,8 +149,8 @@ class MiniMaxH3ModularPipeline(ModularPipeline):
     `negative_prompt` and no `guidance_scale`, and every step runs exactly one forward pass.
 
     MiniMax-H3 is modular only: this pipeline and its blocks are the whole integration, there is no
-    `DiffusionPipeline` half. This class carries the config-derived geometry the blocks read off the components, the
-    packed-sequence geometry lives in `modular_pipelines.minimax_h3.packing`, and the conditioning, encoding and noise
+    `DiffusionPipeline` half. This module carries the model facts every block keys off — the config-derived geometry
+    as properties, the canvas and frame-count arithmetic as functions — and the conditioning, encoding and noise
     contracts live on the blocks themselves.
 
     ```py
@@ -94,8 +204,11 @@ def audio_latent_channels(self):
 
     @property
     def patch_size(self):
-        if getattr(self, "transformer", None) is not None:
-            return tuple(self.transformer.config.patch_size)
+        # One repository holds both checkpoint partitions — `transformer/` for `t2va`/`fl2va`, `transformer_ref/`
+        # for `ref2va` — and a workflow loads only its own, so read whichever is present.
+        for name in ("transformer", "transformer_ref"):
+            if getattr(self, name, None) is not None:
+                return tuple(getattr(self, name).config.patch_size)
         return (1, 2, 2)
 
     @property
@@ -173,37 +286,3 @@ def text_tag(self):
     def video_tag(self):
         r"""The modality tag of a video row of the packed sequence, which a vision block's rows also carry."""
         return MINIMAX_H3_VIDEO_TAG
-
-
-class MiniMaxH3Ref2VAModularPipeline(MiniMaxH3ModularPipeline):
-    """
-    A ModularPipeline for joint video + audio generation from omni-references with MiniMax-H3, the `ref2va` task of the
-    Ref2VA checkpoint.
-
-    A request carries an ordered list of references — up to 9 images, 3 videos and 3 audio clips, 12 in total — and
-    MiniMax-H3 packs one block per reference in front of the generated rows. The order is semantic: it labels the
-    references in the prompt presentation and it advances the shared audio/video rotary clock, so reordering the same
-    references is a different request.
-
-    The transformer is registered as `transformer_ref`, so one repository can hold both checkpoint partitions
-    (`transformer/` for [`MiniMaxH3ModularPipeline`], `transformer_ref/` for this one) and either pipeline loads only
-    its own weights. One repository also means one `modular_model_index.json`, which names the `t2va` / `fl2va` half;
-    load this one through its blocks instead, which reads the very same file:
-
-    ```py
-    pipe = MiniMaxH3Ref2VABlocks().init_pipeline("MiniMaxAI/MiniMax-H3")
-    pipe.load_components(dtype=torch.bfloat16)
-    ```
-
-    The blocks carry the `ref2va` conditioning, encoding and noise contracts themselves.
-
-    > [!WARNING] > This is an experimental feature and is likely to change in the future.
-    """
-
-    default_blocks_name = "MiniMaxH3Ref2VABlocks"
-
-    @property
-    def patch_size(self):
-        if getattr(self, "transformer_ref", None) is not None:
-            return tuple(self.transformer_ref.config.patch_size)
-        return (1, 2, 2)
diff --git a/src/diffusers/modular_pipelines/minimax_h3/packing.py b/src/diffusers/modular_pipelines/minimax_h3/packing.py
deleted file mode 100644
index 681bc73caab5..000000000000
--- a/src/diffusers/modular_pipelines/minimax_h3/packing.py
+++ /dev/null
@@ -1,359 +0,0 @@
-# Copyright 2026 The MiniMax and HuggingFace Teams. All rights reserved.
-#
-# Licensed under the Apache License, Version 2.0 (the "License");
-# you may not use this file except in compliance with the License.
-# You may obtain a copy of the License at
-#
-#     http://www.apache.org/licenses/LICENSE-2.0
-#
-# Unless required by applicable law or agreed to in writing, software
-# distributed under the License is distributed on an "AS IS" BASIS,
-# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-# See the License for the specific language governing permissions and
-# limitations under the License.
-
-r"""
-Packed-sequence and conditioning machinery of the MiniMax-H3 blocks.
-
-This module holds no block of its own: it is the checkpoint's geometry and its constants, imported by every block
-of `modular_pipelines.minimax_h3` that has to place a row, so that none of them reimplements it.
-
-MiniMax-H3 runs its transformer over a single packed 1-D sequence that holds every modality at once. For the
-text/keyframe tasks the row order is
-
-```
-[ text (L) | keyframe conditions (C) | target audio (A) | target video (V) ]
-```
-
-and every piece of geometry in this module exists to place a row in that sequence and to give it its `(t, h, w)`
-rotary coordinate. The coordinates are built in float64 because video and audio share one 40-units-per-second
-rotary clock — video advances `5/3` rotary units per pixel frame at 24 fps, audio advances one unit per latent at
-40 latents/s — and that shared clock *is* the audio/video alignment.
-
-The reference implementation pads the packed sequence up to a multiple of 64 and keeps the padding tail as a
-separate attention document. Padding therefore cannot influence a live row, and this module builds the sequence
-without it: `MiniMaxH3Transformer3DModel` then needs no attention mask, which keeps the unmasked attention
-backends available.
-"""
-
-import numpy as np
-import torch
-
-
-# Per-row modality tags. They index the transformer's AdaLN table, so the values are a checkpoint contract.
-MINIMAX_H3_VIDEO_TAG = 0
-MINIMAX_H3_TEXT_TAG = 1
-MINIMAX_H3_AUDIO_TAG = 2
-
-# MiniMax-H3 generates at a fixed 24 fps and was released for a 768 pixel short edge only, with a soft area cap of
-# 768x1344. The multiple both axes round to is not here: it follows from the VAE and the transformer, so it is
-# `MiniMaxH3ModularPipeline.canvas_multiple` and reaches these helpers as an argument.
-MINIMAX_H3_FPS = 24
-MINIMAX_H3_SHORT_EDGE = 768
-MINIMAX_H3_MAX_PIXELS = 768 * 1344
-MINIMAX_H3_MIN_ASPECT_RATIO = 1 / 4
-MINIMAX_H3_MAX_ASPECT_RATIO = 4
-
-# The audio VAE hops 800 samples at 32 kHz, i.e. 40 latents per second. Stereo is carried as two channel-major
-# blocks of audio rows (and as two batch items at the audio VAE boundary, which is mono).
-MINIMAX_H3_AUDIO_LATENTS_PER_SECOND = 40
-MINIMAX_H3_AUDIO_CHANNELS = 2
-
-# Rotary-time constants. One latent frame spans `5/3 * frames_per_latent` rotary units, where the pattern
-# `(1, 4, 4, 4, 4)` mirrors the VAE's 17-pixel-frames-to-5-latent-frames grouping; the spatial axes are normalized
-# by the square root of the latent area and scaled by 32.
-_ROPE_FRAME_RESCALE = 5.0 / 3.0
-_ROPE_FRAMES_PER_LATENT = (1, 4, 4, 4, 4)
-_ROPE_SPATIAL_SCALE = 32
-
-
-def resolve_canvas_size(aspect_width: float, aspect_height: float, canvas_multiple: int) -> tuple[int, int]:
-    r"""
-    Resolve a display aspect ratio into a MiniMax-H3 canvas.
-
-    The short edge starts at 768, the area is capped at `768 * 1344` and both axes are then rounded to the nearest
-    `canvas_multiple` — so the final area may end up slightly above the pre-rounding budget. Only the ratio of the two
-    arguments matters; pass either the aspect ratio (`16, 9`) or the source dimensions of a keyframe.
-
-    Args:
-        aspect_width (`float`): Width of the target ratio.
-        aspect_height (`float`): Height of the target ratio.
-        canvas_multiple (`int`):
-            What both axes round to, i.e. `components.canvas_multiple` — 32 for the released checkpoint.
-
-    Returns:
-        `tuple[int, int]`: the `(height, width)` of the canvas.
-    """
-    if aspect_width <= 0 or aspect_height <= 0:
-        raise ValueError(f"The aspect ratio must be positive, got {aspect_width}:{aspect_height}.")
-
-    ratio = aspect_width / aspect_height
-    if not MINIMAX_H3_MIN_ASPECT_RATIO <= ratio <= MINIMAX_H3_MAX_ASPECT_RATIO:
-        raise ValueError(
-            f"MiniMax-H3 supports aspect ratios from 1:4 to 4:1, got {aspect_width}:{aspect_height} ({ratio:g})."
-        )
-
-    if ratio >= 1.0:
-        width, height = MINIMAX_H3_SHORT_EDGE * ratio, float(MINIMAX_H3_SHORT_EDGE)
-    else:
-        width, height = float(MINIMAX_H3_SHORT_EDGE), MINIMAX_H3_SHORT_EDGE / ratio
-
-    area = width * height
-    if area > MINIMAX_H3_MAX_PIXELS:
-        scale = (MINIMAX_H3_MAX_PIXELS / area) ** 0.5
-        width, height = width * scale, height * scale
-
-    multiple = canvas_multiple
-    return max(multiple, round(height / multiple) * multiple), max(multiple, round(width / multiple) * multiple)
-
-
-def align_num_frames(num_frames: int, frames_per_chunk: int, latents_per_chunk: int) -> int:
-    r"""
-    Snap a frame count up to the next `frames_per_chunk * n + latents_per_chunk` the video VAE can encode.
-
-    Args:
-        num_frames (`int`): The requested number of frames.
-        frames_per_chunk (`int`): Pixel frames the video VAE encodes per chunk, its `clip_length`.
-        latents_per_chunk (`int`): Latent frames a chunk keeps, the VAE's `tokens_chunk_size`.
-
-    Returns:
-        `int`: The aligned number of frames.
-    """
-    if num_frames < 1:
-        raise ValueError(f"`num_frames` must be positive, got {num_frames}.")
-    while num_frames % frames_per_chunk != latents_per_chunk:
-        num_frames += 1
-    return num_frames
-
-
-def video_latent_num_frames(num_frames: int, frames_per_chunk: int, latents_per_chunk: int) -> int:
-    r"""
-    The number of latent frames the video VAE produces for a `17 * n + 5` frame count.
-
-    Args:
-        num_frames (`int`): An aligned number of frames.
-
-    Returns:
-        `int`: The number of latent frames, `5 * n + 2`.
-    """
-    if num_frames % frames_per_chunk != latents_per_chunk:
-        raise ValueError(
-            f"`num_frames` must be of the form {frames_per_chunk} * n + {latents_per_chunk}, got {num_frames}."
-        )
-    return (num_frames - latents_per_chunk) // frames_per_chunk * latents_per_chunk + 2
-
-
-def audio_latent_num_frames(num_frames: int) -> int:
-    r"""
-    The number of audio latents that covers a video of `num_frames` frames at 24 fps.
-
-    Args:
-        num_frames (`int`): The number of video frames.
-
-    Returns:
-        `int`: The number of audio latents, rounded at the 40 Hz latent grid.
-    """
-    return int(round(num_frames / MINIMAX_H3_FPS * MINIMAX_H3_AUDIO_LATENTS_PER_SECOND))
-
-
-def patchify_video_latents(latents: torch.Tensor, patch_size: tuple[int, int, int]) -> torch.Tensor:
-    r"""
-    Pack video latents into transformer rows.
-
-    Args:
-        latents (`torch.Tensor` of shape `(batch_size, channels, num_frames, height, width)`):
-            The latents to pack.
-        patch_size (`tuple[int, int, int]`): The `(t, h, w)` patch.
-
-    Returns:
-        `torch.Tensor` of shape `(batch_size * num_patches, channels * prod(patch_size))`: The packed rows, ordered
-        frame-major then row-major.
-    """
-    patch_t, patch_h, patch_w = patch_size
-    batch_size, channels, num_frames, height, width = latents.shape
-    if num_frames % patch_t or height % patch_h or width % patch_w:
-        raise ValueError(f"Latents of shape {tuple(latents.shape)} are not divisible by the patch {patch_size}.")
-
-    latents = latents.reshape(
-        batch_size,
-        channels,
-        num_frames // patch_t,
-        patch_t,
-        height // patch_h,
-        patch_h,
-        width // patch_w,
-        patch_w,
-    )
-    latents = latents.permute(0, 2, 4, 6, 1, 3, 5, 7)
-    return latents.reshape(-1, channels * patch_t * patch_h * patch_w).contiguous()
-
-
-def _spatial_position_grid(dim: int, patch: int, sqrt_area: float) -> torch.Tensor:
-    r"""
-    One aspect-normalized spatial rotary axis: `dim // patch` coordinates centred on the unit interval, scaled up by
-    32. The right endpoint is excluded, so a square canvas spans `[0, 32)`.
-    """
-    ratio = dim / sqrt_area
-    left = (1.0 - ratio) / 2.0
-    # Built with numpy: `np.linspace(..., endpoint=False)` is `start + arange(num) * (stop - start) / num`, which is
-    # not what `torch.linspace` computes, and the float64 grid has to be reproduced exactly.
-    grid = np.linspace(left, left + ratio, dim // patch, endpoint=False) * _ROPE_SPATIAL_SCALE
-    return torch.from_numpy(grid).to(torch.float64)
-
-
-def _temporal_position_grid(num_latent_frames: int, origin: float) -> torch.Tensor:
-    r"""The rotary time of every latent frame, starting at `origin`. Spacing is non-uniform: `5/3 * (1, 4, 4, 4, 4)`."""
-    spans = torch.tensor(
-        [
-            _ROPE_FRAME_RESCALE * _ROPE_FRAMES_PER_LATENT[index % len(_ROPE_FRAMES_PER_LATENT)]
-            for index in range(num_latent_frames)
-        ],
-        dtype=torch.float64,
-    )
-    return origin + torch.cat([torch.zeros(1, dtype=torch.float64), spans[:-1].cumsum(0)])
-
-
-def _temporal_position_span(num_latent_frames: int) -> float:
-    r"""
-    The rotary time spanned by `num_latent_frames` latent frames.
-
-    Summed by numpy (pairwise summation) rather than sequentially: the reference computes the keyframe anchor this
-    way and the two summation orders differ in the last ulp from 16 latent frames onwards.
-    """
-    spans = np.ones(num_latent_frames, dtype=np.float64) * _ROPE_FRAME_RESCALE
-    for index in range(len(_ROPE_FRAMES_PER_LATENT)):
-        spans[index :: len(_ROPE_FRAMES_PER_LATENT)] *= _ROPE_FRAMES_PER_LATENT[index]
-    return float(spans.sum())
-
-
-def build_packed_sequence(
-    text_token_tags: torch.Tensor,
-    num_latent_frames: int,
-    latent_height: int,
-    latent_width: int,
-    num_audio_latents: int,
-    patch_size: tuple[int, int, int],
-    keyframe_anchors: tuple[str, ...] = (),
-) -> tuple[torch.Tensor, torch.Tensor, torch.Tensor, torch.Tensor, torch.Tensor, int, int]:
-    r"""
-    Build the `[text | keyframe conditions | target audio | target video]` layout used by the `t2va` and `fl2va`
-    tasks.
-
-    Args:
-        text_token_tags (`torch.Tensor` of shape `(num_text_tokens,)`):
-            The modality tag of every text row. Text is tagged `1`, except for the rows of a keyframe's vision block,
-            which MiniMax-H3 tags `0` (video).
-        num_latent_frames (`int`): Number of target latent frames.
-        latent_height (`int`): Target latent height.
-        latent_width (`int`): Target latent width.
-        num_audio_latents (`int`): Number of target audio latents per channel.
-        patch_size (`tuple[int, int, int]`): The transformer's `(t, h, w)` patch.
-        keyframe_anchors (`tuple[str, ...]`):
-            One entry per keyframe conditioning block, in packed order: `"first"` anchors the block at the first
-            latent frame, `"last"` at the last one.
-
-    Returns:
-        `tuple`: `position_ids`, `token_tags`, `video_indices`, `audio_indices`, `text_indices`, and the number of
-        leading video and audio rows that are conditioning rather than generated.
-    """
-    _, patch_h, patch_w = patch_size
-    rows_per_frame = (latent_height // patch_h) * (latent_width // patch_w)
-    num_text_tokens = text_token_tags.shape[0]
-    num_condition_rows = len(keyframe_anchors) * rows_per_frame
-    num_audio_rows = num_audio_latents * MINIMAX_H3_AUDIO_CHANNELS
-    num_video_rows = num_latent_frames * rows_per_frame
-    sequence_length = num_text_tokens + num_condition_rows + num_audio_rows + num_video_rows
-
-    condition_start = num_text_tokens
-    audio_start = condition_start + num_condition_rows
-    video_start = audio_start + num_audio_rows
-
-    # 1. The (t, h, w) grid. Text rows sit on the time axis at their row index, and the media rows continue the time
-    # axis from there, so text length shifts the whole media clock.
-    position_ids = torch.zeros(sequence_length, 3, dtype=torch.float64)
-    position_ids[:num_text_tokens, 0] = torch.arange(num_text_tokens, dtype=torch.float64)
-
-    sqrt_area = np.sqrt(latent_height * latent_width)
-    height_grid = _spatial_position_grid(latent_height, patch_h, sqrt_area)
-    width_grid = _spatial_position_grid(latent_width, patch_w, sqrt_area)
-    frame_grid = torch.stack([grid.reshape(-1) for grid in torch.meshgrid(height_grid, width_grid, indexing="ij")], -1)
-
-    for index, anchor in enumerate(keyframe_anchors):
-        if anchor == "first":
-            anchor_time = float(num_text_tokens)
-        elif anchor == "last":
-            anchor_time = float(num_text_tokens) + _temporal_position_span(num_latent_frames) - _ROPE_FRAME_RESCALE
-        else:
-            raise ValueError(f"A keyframe anchor must be 'first' or 'last', got {anchor!r}.")
-        rows = slice(condition_start + index * rows_per_frame, condition_start + (index + 1) * rows_per_frame)
-        position_ids[rows, 0] = anchor_time
-        position_ids[rows, 1:] = frame_grid
-
-    # Audio rows are channel-major and share the video's rotary clock: one unit per latent at 40 latents/s equals
-    # 24 fps * 5/3. They carry no height coordinate and are pinned to the two extremes of the width grid.
-    audio_time = float(num_text_tokens) + torch.arange(num_audio_latents, dtype=torch.float64)
-    position_ids[audio_start:video_start, 0] = audio_time.repeat(MINIMAX_H3_AUDIO_CHANNELS)
-    position_ids[audio_start:video_start, 2] = torch.cat(
-        [
-            torch.full((num_audio_latents,), float(width_grid[0]), dtype=torch.float64),
-            torch.full((num_audio_rows - num_audio_latents,), float(width_grid[-1]), dtype=torch.float64),
-        ]
-    )
-
-    video_position_ids = torch.empty(num_latent_frames, rows_per_frame, 3, dtype=torch.float64)
-    video_position_ids[:, :, 0] = _temporal_position_grid(num_latent_frames, float(num_text_tokens))[:, None]
-    video_position_ids[:, :, 1:] = frame_grid[None]
-    position_ids[video_start:] = video_position_ids.reshape(-1, 3)
-
-    # 2. Row indices and modality tags.
-    video_indices = torch.cat([torch.arange(condition_start, audio_start), torch.arange(video_start, sequence_length)])
-    audio_indices = torch.arange(audio_start, video_start)
-    text_indices = torch.arange(num_text_tokens)
-
-    token_tags = torch.empty(sequence_length, dtype=torch.long)
-    token_tags[text_indices] = text_token_tags.to(torch.long)
-    token_tags[audio_indices] = MINIMAX_H3_AUDIO_TAG
-    token_tags[video_indices] = MINIMAX_H3_VIDEO_TAG
-
-    return position_ids, token_tags, video_indices, audio_indices, text_indices, num_condition_rows, 0
-
-
-def build_row_timesteps(
-    video_indices: torch.Tensor,
-    audio_indices: torch.Tensor,
-    num_condition_video_rows: int,
-    num_condition_audio_rows: int,
-    num_text_tokens: int,
-    video_timestep: float,
-    audio_timestep: float,
-    condition_video_timestep: float,
-    condition_audio_timestep: float,
-) -> tuple[torch.Tensor, torch.Tensor]:
-    r"""
-    Assign a timestep to every row of the packed sequence and reduce it to the transformer's `(timestep,
-    timestep_indices)` pair.
-
-    One forward serves rows at different noise levels: the generated video and audio rows step down their own
-    schedules while the conditioning rows stay pinned at their noise-augmentation level. Text rows never reach an
-    output head and inherit the video timestep.
-
-    Args:
-        video_indices (`torch.Tensor`): Sequence positions of the video rows, conditioning rows first.
-        audio_indices (`torch.Tensor`): Sequence positions of the audio rows, reference rows first.
-        num_condition_video_rows (`int`): How many leading video rows are conditioning rows.
-        num_condition_audio_rows (`int`): How many leading audio rows are reference rows.
-        num_text_tokens (`int`): Number of text rows, which never reach an output head.
-        video_timestep (`float`): Timestep of the generated video rows.
-        audio_timestep (`float`): Timestep of the generated audio rows.
-        condition_video_timestep (`float`): Timestep of the video conditioning rows.
-        condition_audio_timestep (`float`): Timestep of the audio reference rows.
-
-    Returns:
-        `tuple[torch.Tensor, torch.Tensor]`: the distinct timesteps, sorted, and the index of every row into them.
-    """
-    sequence_length = int(video_indices.numel() + audio_indices.numel() + num_text_tokens)
-    row_timesteps = torch.full((sequence_length,), video_timestep, dtype=torch.float32)
-    row_timesteps[video_indices[:num_condition_video_rows]] = condition_video_timestep
-    row_timesteps[audio_indices[num_condition_audio_rows:]] = audio_timestep
-    row_timesteps[audio_indices[:num_condition_audio_rows]] = condition_audio_timestep
-    return torch.unique(row_timesteps, sorted=True, return_inverse=True)
diff --git a/src/diffusers/modular_pipelines/minimax_h3/packing_ref2va.py b/src/diffusers/modular_pipelines/minimax_h3/packing_ref2va.py
deleted file mode 100644
index 8f0646a4588e..000000000000
--- a/src/diffusers/modular_pipelines/minimax_h3/packing_ref2va.py
+++ /dev/null
@@ -1,675 +0,0 @@
-# Copyright 2026 The MiniMax and HuggingFace Teams. All rights reserved.
-#
-# Licensed under the Apache License, Version 2.0 (the "License");
-# you may not use this file except in compliance with the License.
-# You may obtain a copy of the License at
-#
-#     http://www.apache.org/licenses/LICENSE-2.0
-#
-# Unless required by applicable law or agreed to in writing, software
-# distributed under the License is distributed on an "AS IS" BASIS,
-# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-# See the License for the specific language governing permissions and
-# limitations under the License.
-
-r"""
-The `ref2va` half of MiniMax-H3's packed sequence: omni-reference conditioning.
-
-`ref2va` takes an ordered list of references — images, videos (with their soundtrack) and audio clips — and packs one
-block per reference ahead of the generated rows:
-
-```
-[ text (L) | reference block 1 | reference block 2 | ... | target audio (A) | target video (V) ]
-```
-
-The blocks are packed in **request order**, and a video reference packs its soundtrack rows immediately *before* its
-own video rows. Order is semantic twice over: it fixes the `"<Picture i>"` / `"<Audio j>"` / `"<Video k>"` labels of
-the prompt presentation, and it advances the shared rotary clock — an image reference occupies one rotary slot, an
-audio reference as many as it has latents, and a video reference the longer of its own two spans, its soundtrack and
-its frames sharing one origin.
-
-Unlike a `fl2va` keyframe, a reference never binds the target geometry: every reference is prepared at its own
-resolution (2048 pixel short edge for images, MiniMax-H3's 768 pixel canvas for videos) and carries its own
-aspect-normalized spatial grid.
-
-References reach the blocks as in-memory media, one dataclass per modality: a [`MiniMaxH3VideoReference`] is decoded
-frames plus the `fps` they carry, a [`MiniMaxH3AudioReference`] a waveform plus its sample rate, and a
-[`MiniMaxH3ImageReference`] a single image. No block of this model opens a media file; decoding a path is the caller's
-job, and [`~modular_pipelines.minimax_h3.reference_loading`] is the convenience for doing it.
-"""
-
-import math
-from dataclasses import dataclass
-
-import numpy as np
-import torch
-from PIL import Image
-
-from .packing import (
-    _ROPE_FRAME_RESCALE,
-    _ROPE_FRAMES_PER_LATENT,
-    MINIMAX_H3_AUDIO_CHANNELS,
-    MINIMAX_H3_AUDIO_TAG,
-    MINIMAX_H3_FPS,
-    MINIMAX_H3_TEXT_TAG,
-    MINIMAX_H3_VIDEO_TAG,
-    _spatial_position_grid,
-    _temporal_position_grid,
-    resolve_canvas_size,
-)
-
-
-# Reference images are resized to a 2048 pixel short edge — upscaling included — and both axes are rounded to a
-# multiple of 32 independently. There is no area cap, so a 4:1 reference is 8192x2048.
-MINIMAX_H3_REFERENCE_IMAGE_SHORT_EDGE = 2048
-
-# The conditioner sees a reference video at 2 fps, and Qwen3-VL merges every two of those frames into one vision
-# block labelled with the mean timestamp of the pair.
-MINIMAX_H3_QWEN_VIDEO_SAMPLE_FPS = 2.0
-MINIMAX_H3_QWEN_TEMPORAL_PATCH = 2
-
-# Documented per-request limits of the omni-reference task.
-MINIMAX_H3_MAX_REFERENCE_IMAGES = 9
-MINIMAX_H3_MAX_REFERENCE_VIDEOS = 3
-MINIMAX_H3_MAX_REFERENCE_AUDIOS = 3
-MINIMAX_H3_MAX_REFERENCES = 12
-
-
-@dataclass
-class MiniMaxH3Reference:
-    r"""
-    Base class of the three references a [`MiniMaxH3Ref2VABlocks`] request conditions on:
-    [`MiniMaxH3ImageReference`], [`MiniMaxH3VideoReference`] and [`MiniMaxH3AudioReference`].
-
-    References are passed to the blocks as a list, **in the order the model should read them**: the order labels them
-    in the prompt presentation and lays them out on the shared rotary clock, so a different order is a different
-    request.
-
-    Every reference holds in-memory media, and the rate that media carries where there is one — MiniMax-H3 resamples a
-    reference onto its own 24 fps and onto the audio VAE's sample rate, so a rate lost on the way in is a request
-    conditioned at the wrong speed. Decoding a file is the caller's job:
-    [`~modular_pipelines.minimax_h3.decode_reference_video`] and
-    [`~modular_pipelines.minimax_h3.decode_reference_audio`] do it along with the rates, and
-    [`MiniMaxH3Ref2VALoadReferencesStep`] wraps them in a block.
-
-    ```py
-    >>> import numpy as np
-    >>> from diffusers.utils import load_image
-    >>> from diffusers.modular_pipelines.minimax_h3 import (
-    ...     MiniMaxH3AudioReference,
-    ...     MiniMaxH3ImageReference,
-    ...     MiniMaxH3VideoReference,
-    ...     decode_reference_audio,
-    ...     decode_reference_video,
-    ... )
-
-    >>> references = [
-    ...     MiniMaxH3ImageReference(image=load_image("subject.png")),
-    ...     decode_reference_video("motion_ref.mp4"),  # frames, their `fps`, and the soundtrack
-    ...     decode_reference_audio("voice.wav"),  # waveform and its `sample_rate`
-    ... ]
-
-    >>> # Media a request produced itself declares the rate it was produced at.
-    >>> frames = np.zeros((30, 480, 854, 3), dtype="uint8")
-    >>> reference = MiniMaxH3VideoReference(frames=frames, fps=30.0)
-    ```
-    """
-
-
-@dataclass
-class MiniMaxH3ImageReference(MiniMaxH3Reference):
-    r"""
-    A subject, style or scene reference: at most 9 per request.
-
-    Attributes:
-        image (`PIL.Image.Image`):
-            The reference image. It never binds the generated geometry — it is encoded at a 2048 pixel short edge of
-            its own aspect ratio, whatever canvas the request generates at.
-    """
-
-    image: Image.Image
-
-    kind = "image"
-    has_audio = False
-
-
-@dataclass
-class MiniMaxH3VideoReference(MiniMaxH3Reference):
-    r"""
-    A motion and camera reference: at most 3 per request, conditioned on together with its own soundtrack.
-
-    Attributes:
-        frames (`list[PIL.Image.Image]`, `np.ndarray` or `torch.Tensor`):
-            The reference frames: a list of images, a `(num_frames, height, width, 3)` array or a `(num_frames, 3,
-            height, width)` tensor, `uint8` or floating point over `[0, 1]`.
-        fps (`float`, *optional*, defaults to 24.0):
-            The frame rate `frames` carries, which is what places the reference's vision blocks on the conditioner's 2
-            fps grid. MiniMax-H3's own clock is 24 fps, so any other rate is resampled onto it by dropping and
-            duplicating whole frames — which makes this the field to get right when the frames came from a file.
-        audio (`torch.Tensor` of shape `(channels, num_samples)`, *optional*):
-            This video's soundtrack, mono or stereo, conditioned on as the reference's own rather than as a reference
-            of its own. Left out, the reference conditions on motion alone.
-        sample_rate (`int`, *optional*):
-            The rate `audio` carries its samples at. Left out, it is the audio VAE's own, which leaves the samples
-            untouched; any other rate is resampled onto it.
-    """
-
-    frames: list[Image.Image] | np.ndarray | torch.Tensor
-    fps: float | None = None
-    audio: torch.Tensor | None = None
-    sample_rate: int | None = None
-
-    kind = "video"
-
-    def __post_init__(self):
-        if self.fps is None:
-            self.fps = float(MINIMAX_H3_FPS)
-
-    @property
-    def has_audio(self) -> bool:
-        r"""Whether this reference contributes audio rows, i.e. whether it carries a soundtrack."""
-        return self.audio is not None
-
-
-@dataclass
-class MiniMaxH3AudioReference(MiniMaxH3Reference):
-    r"""
-    A voice or music reference: at most 3 per request, and never on its own — an audio reference has to be paired with
-    at least one image or video reference. It never reaches the conditioner and is encoded by the audio VAE alone.
-
-    Attributes:
-        audio (`torch.Tensor` of shape `(channels, num_samples)`):
-            The reference waveform, mono or stereo.
-        sample_rate (`int`, *optional*):
-            The rate `audio` carries its samples at. Left out, it is the audio VAE's own, which leaves the samples
-            untouched; any other rate is resampled onto it.
-    """
-
-    audio: torch.Tensor
-    sample_rate: int | None = None
-
-    kind = "audio"
-    has_audio = True
-
-
-def _temporal_position_span(num_latent_frames: int) -> float:
-    r"""
-    The rotary time a video reference advances the clock by.
-
-    Summed sequentially in float64, which is *not* how [`~modular_pipelines.minimax_h3.packing._temporal_position_span`] sums
-    the same series: that one reproduces a numpy pairwise sum, and the two orders differ in the last ulp from 16
-    latent frames onwards. The reference implementation keeps both, one per call site, so the port has to as well.
-    """
-    return sum(
-        _ROPE_FRAME_RESCALE * _ROPE_FRAMES_PER_LATENT[index % len(_ROPE_FRAMES_PER_LATENT)]
-        for index in range(num_latent_frames)
-    )
-
-
-def _frame_position_grid(
-    latent_height: int, latent_width: int, patch_h: int, patch_w: int
-) -> tuple[torch.Tensor, torch.Tensor]:
-    r"""The `(h, w)` rotary coordinates of one latent frame, and the width axis they were built from."""
-    sqrt_area = np.sqrt(latent_height * latent_width)
-    height_grid = _spatial_position_grid(latent_height, patch_h, sqrt_area)
-    width_grid = _spatial_position_grid(latent_width, patch_w, sqrt_area)
-    grids = torch.meshgrid(height_grid, width_grid, indexing="ij")
-    return torch.stack([grid.reshape(-1) for grid in grids], dim=-1), width_grid
-
-
-def _fill_audio_positions(
-    position_ids: torch.Tensor,
-    rows: slice,
-    num_audio_latents: int,
-    rotary_time: float,
-    width_grid: torch.Tensor,
-) -> None:
-    r"""
-    Place one channel-major audio block.
-
-    Audio rows carry no height coordinate and are pinned to the two extremes of the width grid of *their own* block —
-    the target grid for a standalone audio reference, the video's grid for a soundtrack.
-    """
-    time = rotary_time + torch.arange(num_audio_latents, dtype=torch.float64)
-    position_ids[rows, 0] = time.repeat(MINIMAX_H3_AUDIO_CHANNELS)
-    position_ids[rows, 2] = torch.cat(
-        [
-            torch.full((num_audio_latents,), float(width_grid[0]), dtype=torch.float64),
-            torch.full((num_audio_latents,), float(width_grid[-1]), dtype=torch.float64),
-        ]
-    )
-
-
-def build_ref2va_packed_sequence(
-    text_token_tags: torch.Tensor,
-    references: list[MiniMaxH3Reference],
-    condition_latents: list[torch.Tensor],
-    audio_condition_latents: list[torch.Tensor],
-    num_latent_frames: int,
-    latent_height: int,
-    latent_width: int,
-    num_audio_latents: int,
-    patch_size: tuple[int, int, int],
-) -> tuple[torch.Tensor, torch.Tensor, torch.Tensor, torch.Tensor, torch.Tensor, int, int]:
-    r"""
-    Build the `[text | reference blocks | target audio | target video]` layout of the `ref2va` task.
-
-    Args:
-        text_token_tags (`torch.Tensor` of shape `(num_text_tokens,)`):
-            The modality tag of every text row. Text is tagged `1`, except for the rows of a reference's vision block,
-            which MiniMax-H3 tags `0` (video).
-        references (`list[MiniMaxH3Reference]`):
-            The references, in packed order. Only their modality is read here; the geometry comes from the latents.
-        condition_latents (`list[torch.Tensor]`):
-            One `(1, channels, num_latent_frames, latent_height, latent_width)` tensor per image and video reference,
-            in packed order, as [`MiniMaxH3Ref2VAReferenceEncoderStep`] produced them.
-        audio_condition_latents (`list[torch.Tensor]`):
-            One `(num_audio_latents * 2, audio_latent_channels)` tensor per audio-bearing reference, in packed order.
-        num_latent_frames (`int`): Number of target latent frames.
-        latent_height (`int`): Target latent height.
-        latent_width (`int`): Target latent width.
-        num_audio_latents (`int`): Number of target audio latents per channel.
-        patch_size (`tuple[int, int, int]`): The transformer's `(t, h, w)` patch.
-
-    Returns:
-        `tuple`: `position_ids`, `token_tags`, `video_indices`, `audio_indices`, `text_indices`, and the number of
-        leading video and audio rows that are references rather than generated.
-    """
-    _, patch_h, patch_w = patch_size
-    num_text_tokens = text_token_tags.shape[0]
-    num_target_video_rows = num_latent_frames * (latent_height // patch_h) * (latent_width // patch_w)
-    num_target_audio_rows = num_audio_latents * MINIMAX_H3_AUDIO_CHANNELS
-
-    # The geometry of every reference block is the shape of what the encoder produced for it, so the two can never
-    # disagree. Both lists are in packed order but skip the references they do not apply to, so they are consumed as
-    # iterators alongside the reference list rather than indexed by it.
-    visual_geometry = iter(tuple(latents.shape[2:5]) for latents in condition_latents)
-    audio_row_counts = iter(rows.shape[0] for rows in audio_condition_latents)
-    num_reference_video_rows = sum(
-        frames * (height // patch_h) * (width // patch_w)
-        for frames, height, width in (tuple(latents.shape[2:5]) for latents in condition_latents)
-    )
-    num_reference_audio_rows = sum(rows.shape[0] for rows in audio_condition_latents)
-    sequence_length = (
-        num_text_tokens
-        + num_reference_video_rows
-        + num_reference_audio_rows
-        + num_target_audio_rows
-        + num_target_video_rows
-    )
-
-    position_ids = torch.zeros(sequence_length, 3, dtype=torch.float64)
-    position_ids[:num_text_tokens, 0] = torch.arange(num_text_tokens, dtype=torch.float64)
-    target_frame_grid, target_width_grid = _frame_position_grid(latent_height, latent_width, patch_h, patch_w)
-
-    # Reference blocks, in request order. `rotary_time` is the shared audio/video clock: it starts where the text
-    # rows end and every block pushes it forward by the time that block occupies.
-    video_indices, audio_indices = [], []
-    cursor = num_text_tokens
-    rotary_time = float(num_text_tokens)
-    for reference in references:
-        if reference.kind == "image":
-            num_latent_frames_, reference_height, reference_width = next(visual_geometry)
-            num_video_rows = (
-                num_latent_frames_ * (reference_height // patch_h) * (reference_width // patch_w)
-            )
-            rows = slice(cursor, cursor + num_video_rows)
-            cursor = rows.stop
-            video_indices.append(torch.arange(rows.start, rows.stop))
-            frame_grid, _ = _frame_position_grid(reference_height, reference_width, patch_h, patch_w)
-            position_ids[rows, 0] = rotary_time
-            position_ids[rows, 1:] = frame_grid
-            # An image is a single frame and takes a single integer rotary slot, not a latent frame's 5/3 units.
-            rotary_time += 1.0
-        elif reference.kind == "audio":
-            num_audio_rows = next(audio_row_counts)
-            reference_audio_latents = num_audio_rows // MINIMAX_H3_AUDIO_CHANNELS
-            rows = slice(cursor, cursor + num_audio_rows)
-            cursor = rows.stop
-            audio_indices.append(torch.arange(rows.start, rows.stop))
-            _fill_audio_positions(position_ids, rows, reference_audio_latents, rotary_time, target_width_grid)
-            rotary_time += float(reference_audio_latents)
-        elif reference.kind == "video":
-            # A video reference's soundtrack rows are packed immediately before its video rows and share their
-            # origin, so the two are rotary-aligned exactly as the generated audio and video are.
-            num_audio_rows = next(audio_row_counts) if reference.has_audio else 0
-            reference_audio_latents = num_audio_rows // MINIMAX_H3_AUDIO_CHANNELS
-            num_latent_frames_, reference_height, reference_width = next(visual_geometry)
-            num_video_rows = (
-                num_latent_frames_ * (reference_height // patch_h) * (reference_width // patch_w)
-            )
-            audio_rows = slice(cursor, cursor + num_audio_rows)
-            video_rows = slice(audio_rows.stop, audio_rows.stop + num_video_rows)
-            cursor = video_rows.stop
-            audio_indices.append(torch.arange(audio_rows.start, audio_rows.stop))
-            video_indices.append(torch.arange(video_rows.start, video_rows.stop))
-
-            frame_grid, width_grid = _frame_position_grid(reference_height, reference_width, patch_h, patch_w)
-            _fill_audio_positions(position_ids, audio_rows, reference_audio_latents, rotary_time, width_grid)
-            frame_time = _temporal_position_grid(num_latent_frames_, rotary_time)
-            position_ids[video_rows, 0] = frame_time.repeat_interleave(frame_grid.shape[0])
-            position_ids[video_rows, 1:] = frame_grid.repeat(num_latent_frames_, 1)
-            rotary_time += max(float(reference_audio_latents), _temporal_position_span(num_latent_frames_))
-        else:
-            raise ValueError(f"A reference must be an 'image', a 'video' or an 'audio', got {reference.kind!r}.")
-
-    # The generated rows. Target audio and target video share the origin the reference blocks left behind.
-    audio_start = cursor
-    video_start = audio_start + num_target_audio_rows
-    _fill_audio_positions(
-        position_ids, slice(audio_start, video_start), num_audio_latents, rotary_time, target_width_grid
-    )
-    frame_time = _temporal_position_grid(num_latent_frames, rotary_time)
-    position_ids[video_start:, 0] = frame_time.repeat_interleave(target_frame_grid.shape[0])
-    position_ids[video_start:, 1:] = target_frame_grid.repeat(num_latent_frames, 1)
-
-    video_indices = torch.cat(video_indices + [torch.arange(video_start, sequence_length)])
-    audio_indices = torch.cat(audio_indices + [torch.arange(audio_start, video_start)])
-    text_indices = torch.arange(num_text_tokens)
-
-    token_tags = torch.empty(sequence_length, dtype=torch.long)
-    token_tags[text_indices] = text_token_tags.to(torch.long)
-    token_tags[audio_indices] = MINIMAX_H3_AUDIO_TAG
-    token_tags[video_indices] = MINIMAX_H3_VIDEO_TAG
-
-    return (
-        position_ids,
-        token_tags,
-        video_indices,
-        audio_indices,
-        text_indices,
-        num_reference_video_rows,
-        num_reference_audio_rows,
-    )
-
-
-def resolve_reference_image_size(width: int, height: int, canvas_multiple: int) -> tuple[int, int]:
-    r"""
-    Resolve the resolution a reference image is encoded at: a 2048 pixel short edge, both axes rounded to
-    `canvas_multiple`. Upscaling is intended, and unlike the target canvas there is no area cap.
-
-    Args:
-        width (`int`): Width of the source image.
-        height (`int`): Height of the source image.
-        canvas_multiple (`int`):
-            What both axes round to, i.e. `components.canvas_multiple` — 32 for the released checkpoint.
-
-    Returns:
-        `tuple[int, int]`: the `(height, width)` the reference is resized to.
-    """
-    if width <= 0 or height <= 0:
-        raise ValueError(f"A reference image must have a positive size, got {width}x{height}.")
-    if width > 4 * height or height > 4 * width:
-        raise ValueError(f"A reference image must be within 1:4 and 4:1, got {width}x{height}.")
-
-    scale = MINIMAX_H3_REFERENCE_IMAGE_SHORT_EDGE / min(width, height)
-    multiple = canvas_multiple
-    return (
-        max(multiple, round(height * scale / multiple) * multiple),
-        max(multiple, round(width * scale / multiple) * multiple),
-    )
-
-
-def reference_media_to_uint8(media) -> np.ndarray:
-    r"""
-    An in-memory reference image or video as channels-last `uint8` RGB.
-
-    Args:
-        media (`PIL.Image.Image`, `np.ndarray`, `torch.Tensor` or `list`):
-            One image, one video, or a list of either. A `torch.Tensor` is channels-first, as everywhere else in
-            diffusers, and a `np.ndarray` channels-last; floating point values are read over `[0, 1]`.
-
-    Returns:
-        `np.ndarray`: the `uint8` RGB pixels, `(height, width, 3)` for a single image and `(num_frames, height, width,
-        3)` for a video or a list.
-    """
-    if isinstance(media, list):
-        return np.stack([reference_media_to_uint8(item) for item in media])
-    if isinstance(media, Image.Image):
-        return np.asarray(media.convert("RGB"))
-    if isinstance(media, torch.Tensor):
-        media = media.movedim(-3, -1).cpu().numpy()
-    media = np.asarray(media)
-    if media.dtype != np.uint8:
-        media = (media * 255.0).round().clip(0, 255).astype(np.uint8)
-    return media
-
-
-def prepare_reference_image(image, height: int, width: int):
-    r"""
-    Resize a reference image onto its own resolution with LANCZOS. An image that already is that size is returned
-    untouched, without a resampling pass.
-
-    Args:
-        image (`PIL.Image.Image`): The reference, in RGB and already EXIF-transposed.
-        height (`int`): Target height, as resolved by [`resolve_reference_image_size`].
-        width (`int`): Target width.
-
-    Returns:
-        `PIL.Image.Image`: The prepared reference.
-    """
-    if image.size == (width, height):
-        return image
-    return image.resize((width, height), Image.Resampling.LANCZOS)
-
-
-def resample_reference_frames(frames: np.ndarray, fps: float) -> np.ndarray:
-    r"""
-    Resample a reference video onto MiniMax-H3's own 24 fps, dropping and duplicating whole frames.
-
-    The reference implementation decoded every video reference through `ffmpeg`'s `fps` filter, a constant frame rate
-    resampler: every source frame lands on the output slot its timestamp rounds to, `round(index * 24 / fps)`, and a
-    slot holds the last frame that landed on it, so a frame whose successor lands on the same slot is dropped and a
-    frame whose successor skips slots is repeated. The end of the stream is rounded onto the grid the very same way,
-    which is what fixes the length at `round(num_frames * 24 / fps)` slots and decides whether the last frame is
-    repeated to reach it or dropped for overshooting it.
-
-    Reproducing that selection is what makes a constant frame rate reference give the very frames the reference's
-    decode gave, and it is an exact identity — the same array, no copy — for frames already at 24 fps.
-
-    Args:
-        frames (`np.ndarray` of shape `(num_frames, height, width, 3)`): The reference video, `uint8` RGB.
-        fps (`float`): The frame rate `frames` was decoded at.
-
-    Returns:
-        `np.ndarray`: the frames on MiniMax-H3's 24 fps grid, `frames` itself when they already are.
-    """
-    if fps <= 0:
-        raise ValueError(f"A reference video must have a positive frame rate, got {fps}.")
-    if fps == MINIMAX_H3_FPS:
-        return frames
-
-    scale = MINIMAX_H3_FPS / fps
-    slots = np.floor(np.arange(frames.shape[0]) * scale + 0.5).astype(np.int64)
-    # Every frame is held until the slot of the next one, and the last one until the slot the stream's end rounds to.
-    return np.repeat(frames, np.diff(slots, append=math.floor(frames.shape[0] * scale + 0.5)), axis=0)
-
-
-def prepare_reference_frames(frames: np.ndarray, num_frames: int, canvas_multiple: int) -> np.ndarray:
-    r"""
-    Put a reference video onto the canvas its own aspect ratio resolves to, and cap it at the generated frame count.
-
-    Frames that already are that canvas flow through untouched, with no resampling pass and no copy, and that is the
-    parity-exact route: the reference implementation rescaled the frames with `ffmpeg`'s own LANCZOS scaler while
-    decoding them, so only frames decoded at the canvas reproduce its pixels bit for bit. Any other size is resized
-    frame by frame with PIL, the very path [`prepare_reference_image`] takes.
-
-    Args:
-        frames (`np.ndarray` of shape `(num_frames, height, width, 3)`):
-            The reference video, `uint8` RGB at 24 fps, as returned by [`resample_reference_frames`].
-        num_frames (`int`): The frame count the reference is truncated to, i.e. the target's own frame count.
-        canvas_multiple (`int`):
-            What both axes of its own canvas round to, i.e. `components.canvas_multiple`.
-
-    Returns:
-        `np.ndarray` of shape `(num_frames, height, width, 3)`: The prepared reference.
-    """
-    if frames.ndim != 4 or frames.shape[3] != 3:
-        raise ValueError(
-            f"A reference video must be `(num_frames, height, width, 3)` RGB frames, got {tuple(frames.shape)}."
-        )
-    frames = frames[:num_frames]
-    height, width = resolve_canvas_size(frames.shape[2], frames.shape[1], canvas_multiple)
-    if frames.shape[1:3] == (height, width):
-        return frames
-    return np.stack(
-        [np.asarray(Image.fromarray(frame).resize((width, height), Image.Resampling.LANCZOS)) for frame in frames]
-    )
-
-
-def sample_reference_video_frames(frames: np.ndarray) -> tuple[list[np.ndarray], list[float]]:
-    r"""
-    Sample the frames the conditioner sees from a prepared reference video, and label their vision blocks.
-
-    The conditioner reads a reference at 2 fps: every 12th of the 24 fps frames, deduplicated. Qwen3-VL then merges
-    the sampled frames in pairs — repeating the last one when there is an odd number of them — and a merged pair is
-    labelled with the mean of its two timestamps, which `"<{timestamp:.1f} seconds>"` renders with Python's
-    round-half-to-even, so the first block of a 2 fps pair is `"<0.2 seconds>"` rather than `"<0.3 seconds>"`.
-
-    Args:
-        frames (`np.ndarray` of shape `(num_frames, height, width, 3)`): The prepared reference video, at 24 fps.
-
-    Returns:
-        `tuple[list[np.ndarray], list[float]]`: the sampled frames and one timestamp per vision block.
-    """
-    stride = MINIMAX_H3_FPS / MINIMAX_H3_QWEN_VIDEO_SAMPLE_FPS
-    indices, cursor = [], 0.0
-    while round(cursor) < frames.shape[0]:
-        if not indices or round(cursor) > indices[-1]:
-            indices.append(round(cursor))
-        cursor += stride
-
-    timestamps = [index / MINIMAX_H3_QWEN_VIDEO_SAMPLE_FPS for index in range(len(indices))]
-    timestamps += [timestamps[-1]] * (-len(timestamps) % MINIMAX_H3_QWEN_TEMPORAL_PATCH)
-    block_timestamps = [
-        (timestamps[index] + timestamps[index + MINIMAX_H3_QWEN_TEMPORAL_PATCH - 1]) / 2
-        for index in range(0, len(timestamps), MINIMAX_H3_QWEN_TEMPORAL_PATCH)
-    ]
-    return [frames[index] for index in indices], block_timestamps
-
-
-def prepare_reference_waveform(
-    waveform: torch.Tensor, sample_rate: int, target_sample_rate: int, max_duration: float
-) -> torch.Tensor:
-    r"""
-    Put a reference soundtrack on the audio VAE's sample rate, as a stereo waveform.
-
-    The reference implementation extracts a soundtrack at a native rate, truncates it there and resamples it once, in
-    torch, which this mirrors: the truncation is applied at `sample_rate` and the resampling is a single `torchaudio`
-    pass. A mono waveform is upmixed by repeating its channel.
-
-    Args:
-        waveform (`torch.Tensor` of shape `(channels, num_samples)`): The soundtrack, mono or stereo.
-        sample_rate (`int`): The sample rate `waveform` carries its samples at.
-        target_sample_rate (`int`): The audio VAE's sample rate, i.e. what the waveform is resampled to.
-        max_duration (`float`): Truncate the reference to this many seconds.
-
-    Returns:
-        `torch.Tensor` of shape `(2, num_samples)`: the float32 waveform.
-    """
-    waveform = torch.as_tensor(waveform)
-    if waveform.ndim != 2 or waveform.shape[0] not in (1, MINIMAX_H3_AUDIO_CHANNELS):
-        raise ValueError(
-            "A reference soundtrack must be a `(channels, num_samples)` mono or stereo waveform, got "
-            f"{tuple(waveform.shape)}."
-        )
-    waveform = waveform.to(torch.float32)[:, : int(max_duration * sample_rate)]
-    if waveform.shape[0] != MINIMAX_H3_AUDIO_CHANNELS:
-        waveform = waveform.expand(MINIMAX_H3_AUDIO_CHANNELS, -1).contiguous()
-    if sample_rate == target_sample_rate:
-        return waveform
-
-    try:
-        import torchaudio
-    except ImportError as error:
-        raise ImportError(
-            f"Resampling a MiniMax-H3 reference soundtrack from {sample_rate} Hz to {target_sample_rate} Hz needs "
-            "`torchaudio`. Pass a waveform already at the audio VAE's sample rate to do without it."
-        ) from error
-    return torchaudio.transforms.Resample(sample_rate, target_sample_rate)(waveform)
-
-
-def build_ref2va_presentation(
-    tokenizer,
-    prompt: str,
-    references: list[MiniMaxH3Reference],
-    image_token_counts: list[int],
-    video_block_token_counts: list[int],
-    video_block_timestamps: list[list[float]],
-) -> tuple[list[int], list[int]]:
-    r"""
-    Tokenize MiniMax-H3's presentation of a `ref2va` request.
-
-    Every reference prepends a label, in packed order and numbered per modality: `"<Picture i>: "` plus a vision block
-    for an image, `"<Audio j>: "` alone for audio — a waveform never reaches the conditioner — and `"<Video k>: "`
-    plus one timestamped vision block per merged frame pair for a video. A video that carries sound is labelled
-    `"<Audio j>: "` *before* `"<Video k>: "`, mirroring the order its rows are packed in. The prompt follows verbatim,
-    with no chat template and no special tokens.
-
-    Args:
-        tokenizer (`Qwen2TokenizerFast`): Tokenizer of the conditioner.
-        prompt (`str`): The prompt, appended verbatim.
-        references (`list[MiniMaxH3Reference]`): The normalized references, in packed order.
-        image_token_counts (`list[int]`): Number of vision tokens of every image reference's block.
-        video_block_token_counts (`list[int]`): Number of vision tokens per block of every video reference.
-        video_block_timestamps (`list[list[float]]`): The timestamp of every vision block, per video reference.
-
-    Returns:
-        `tuple[list[int], list[int]]`: the token ids and their modality tags. A vision block is tagged `0` (video) and
-        everything else `1` (text).
-    """
-
-    def text(value: str) -> tuple[list[int], list[int]]:
-        token_ids = tokenizer(value, add_special_tokens=False)["input_ids"]
-        return token_ids, [MINIMAX_H3_TEXT_TAG] * len(token_ids)
-
-    def vision(pad_token: str, num_tokens: int) -> tuple[list[int], list[int]]:
-        token_ids = (
-            [tokenizer.convert_tokens_to_ids("<|vision_start|>")]
-            + [tokenizer.convert_tokens_to_ids(pad_token)] * num_tokens
-            + [tokenizer.convert_tokens_to_ids("<|vision_end|>")]
-        )
-        return token_ids, [MINIMAX_H3_VIDEO_TAG] * len(token_ids)
-
-    token_ids, token_tags = [], []
-
-    def emit(segment: tuple[list[int], list[int]]) -> None:
-        token_ids.extend(segment[0])
-        token_tags.extend(segment[1])
-
-    counts = {"image": 0, "video": 0, "audio": 0}
-    for reference in references:
-        if reference.has_audio:
-            counts["audio"] += 1
-            emit(text(f"<Audio {counts['audio']}>: "))
-        if reference.kind == "image":
-            counts["image"] += 1
-            emit(text(f"<Picture {counts['image']}>: "))
-            emit(vision("<|image_pad|>", image_token_counts[counts["image"] - 1]))
-        elif reference.kind == "video":
-            counts["video"] += 1
-            emit(text(f"<Video {counts['video']}>: "))
-            for timestamp in video_block_timestamps[counts["video"] - 1]:
-                # `"{:.1f}"` rounds half to even, so the mean of a 2 fps pair renders as "<0.2 seconds>".
-                emit(text(f"<{timestamp:.1f} seconds>"))
-                emit(vision("<|video_pad|>", video_block_token_counts[counts["video"] - 1]))
-    emit(text(prompt))
-    return token_ids, token_tags
-
-
-def trim_reference_num_frames(num_frames: int, frames_per_chunk: int, latents_per_chunk: int) -> int:
-    r"""
-    Snap a reference video's frame count *down* to a `17 * n + 5` the video VAE encodes without padding.
-
-    A reference is truncated to the target's own frame count, which already is of that form, so this only bites when
-    the reference is shorter than the video being generated.
-
-    Args:
-        num_frames (`int`): The number of frames the reference carries.
-
-    Returns:
-        `int`: The number of frames to encode.
-    """
-    if num_frames < 1:
-        raise ValueError(f"A reference video must have at least one frame, got {num_frames}.")
-    return max(1, (num_frames - latents_per_chunk) // frames_per_chunk) * frames_per_chunk + latents_per_chunk
diff --git a/src/diffusers/modular_pipelines/minimax_h3/reference_loading.py b/src/diffusers/modular_pipelines/minimax_h3/reference_loading.py
index d8adc58bf947..a61de5bc4a6e 100644
--- a/src/diffusers/modular_pipelines/minimax_h3/reference_loading.py
+++ b/src/diffusers/modular_pipelines/minimax_h3/reference_loading.py
@@ -22,7 +22,7 @@
 
 This module is the convenience for doing it: [`decode_reference_video`] and [`decode_reference_audio`] decode a file
 or a URL along with the rates it carries, and [`MiniMaxH3Ref2VALoadReferencesStep`] wraps them in a block that can be
-put in front of [`MiniMaxH3Ref2VABlocks`]. It is deliberately *not* one of that blockset's own steps — decoding media
+put in front of [`MiniMaxH3Blocks`]. It is deliberately *not* one of that blockset's own steps — decoding media
 is not part of generating video, and a request that already holds its media should not pay for the machinery.
 
 The rates are the reason to prefer these over a bare `load_video`: MiniMax-H3 resamples a reference onto its own 24
@@ -42,8 +42,8 @@
 from ...utils.constants import DIFFUSERS_REQUEST_TIMEOUT
 from ..modular_pipeline import ModularPipelineBlocks, PipelineState
 from ..modular_pipeline_utils import InputParam, OutputParam
-from .modular_pipeline import MiniMaxH3Ref2VAModularPipeline
-from .packing_ref2va import (
+from .modular_pipeline import MiniMaxH3ModularPipeline
+from .references import (
     MiniMaxH3AudioReference,
     MiniMaxH3ImageReference,
     MiniMaxH3Reference,
@@ -191,17 +191,17 @@ class MiniMaxH3Ref2VALoadReferencesStep(ModularPipelineBlocks):
     r"""
     Reads `ref2va` references off the filesystem, so that a request can name its media instead of decoding it.
 
-    Not one of [`MiniMaxH3Ref2VABlocks`]' own steps — put it in front of them when the request holds paths:
+    Not one of [`MiniMaxH3Blocks`]' own steps — put it in front of them when the request holds paths:
 
     ```py
     >>> from diffusers.modular_pipelines import SequentialPipelineBlocks
     >>> from diffusers.modular_pipelines.minimax_h3 import (
-    ...     MiniMaxH3Ref2VABlocks,
+    ...     MiniMaxH3Blocks,
     ...     MiniMaxH3Ref2VALoadReferencesStep,
     ... )
 
     >>> blocks = SequentialPipelineBlocks.from_blocks_dict(
-    ...     {"load_references": MiniMaxH3Ref2VALoadReferencesStep(), "ref2va": MiniMaxH3Ref2VABlocks()}
+    ...     {"load_references": MiniMaxH3Ref2VALoadReferencesStep(), "generate": MiniMaxH3Blocks()}
     ... )
     >>> pipe = blocks.init_pipeline("MiniMaxAI/MiniMax-H3-Ref2VA-Diffusers")
     >>> output = pipe(
@@ -211,7 +211,7 @@ class MiniMaxH3Ref2VALoadReferencesStep(ModularPipelineBlocks):
     ```
     """
 
-    model_name = "minimax-h3-ref2va"
+    model_name = "minimax-h3"
 
     @property
     def description(self) -> str:
@@ -249,7 +249,7 @@ def intermediate_outputs(self) -> list[OutputParam]:
         ]
 
     @torch.no_grad()
-    def __call__(self, components: MiniMaxH3Ref2VAModularPipeline, state: PipelineState) -> PipelineState:
+    def __call__(self, components: MiniMaxH3ModularPipeline, state: PipelineState) -> PipelineState:
         block_state = self.get_block_state(state)
 
         references = []
diff --git a/src/diffusers/modular_pipelines/minimax_h3/references.py b/src/diffusers/modular_pipelines/minimax_h3/references.py
new file mode 100644
index 000000000000..970ac82d0762
--- /dev/null
+++ b/src/diffusers/modular_pipelines/minimax_h3/references.py
@@ -0,0 +1,151 @@
+# Copyright 2026 The MiniMax and HuggingFace Teams. All rights reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+r"""
+The references of a MiniMax-H3 `ref2va` request: one public dataclass per modality.
+
+`ref2va` conditions on an ordered list of references — images, videos (with their soundtrack) and audio clips —
+packed one block per reference ahead of the generated rows. The order is semantic twice over: it fixes the
+`"<Picture i>"` / `"<Audio j>"` / `"<Video k>"` labels of the prompt presentation, and it advances the shared
+audio/video rotary clock, so a different order is a different request.
+
+Every reference holds in-memory media plus the rate that media carries. No block of this model opens a media file;
+decoding a path is the caller's job, and [`~modular_pipelines.minimax_h3.reference_loading`] is the convenience for
+doing it.
+"""
+
+from dataclasses import dataclass
+
+import numpy as np
+import torch
+from PIL import Image
+
+from .modular_pipeline import MINIMAX_H3_FPS
+
+
+@dataclass
+class MiniMaxH3Reference:
+    r"""
+    Base class of the three references a [`MiniMaxH3Ref2VABlocks`] request conditions on:
+    [`MiniMaxH3ImageReference`], [`MiniMaxH3VideoReference`] and [`MiniMaxH3AudioReference`].
+
+    References are passed to the blocks as a list, **in the order the model should read them**: the order labels them
+    in the prompt presentation and lays them out on the shared rotary clock, so a different order is a different
+    request.
+
+    Every reference holds in-memory media, and the rate that media carries where there is one — MiniMax-H3 resamples a
+    reference onto its own 24 fps and onto the audio VAE's sample rate, so a rate lost on the way in is a request
+    conditioned at the wrong speed. Decoding a file is the caller's job:
+    [`~modular_pipelines.minimax_h3.decode_reference_video`] and
+    [`~modular_pipelines.minimax_h3.decode_reference_audio`] do it along with the rates, and
+    [`MiniMaxH3Ref2VALoadReferencesStep`] wraps them in a block.
+
+    ```py
+    >>> import numpy as np
+    >>> from diffusers.utils import load_image
+    >>> from diffusers.modular_pipelines.minimax_h3 import (
+    ...     MiniMaxH3AudioReference,
+    ...     MiniMaxH3ImageReference,
+    ...     MiniMaxH3VideoReference,
+    ...     decode_reference_audio,
+    ...     decode_reference_video,
+    ... )
+
+    >>> references = [
+    ...     MiniMaxH3ImageReference(image=load_image("subject.png")),
+    ...     decode_reference_video("motion_ref.mp4"),  # frames, their `fps`, and the soundtrack
+    ...     decode_reference_audio("voice.wav"),  # waveform and its `sample_rate`
+    ... ]
+
+    >>> # Media a request produced itself declares the rate it was produced at.
+    >>> frames = np.zeros((30, 480, 854, 3), dtype="uint8")
+    >>> reference = MiniMaxH3VideoReference(frames=frames, fps=30.0)
+    ```
+    """
+
+
+@dataclass
+class MiniMaxH3ImageReference(MiniMaxH3Reference):
+    r"""
+    A subject, style or scene reference: at most 9 per request.
+
+    Attributes:
+        image (`PIL.Image.Image`):
+            The reference image. It never binds the generated geometry — it is encoded at a 2048 pixel short edge of
+            its own aspect ratio, whatever canvas the request generates at.
+    """
+
+    image: Image.Image
+
+    kind = "image"
+    has_audio = False
+
+
+@dataclass
+class MiniMaxH3VideoReference(MiniMaxH3Reference):
+    r"""
+    A motion and camera reference: at most 3 per request, conditioned on together with its own soundtrack.
+
+    Attributes:
+        frames (`list[PIL.Image.Image]`, `np.ndarray` or `torch.Tensor`):
+            The reference frames: a list of images, a `(num_frames, height, width, 3)` array or a `(num_frames, 3,
+            height, width)` tensor, `uint8` or floating point over `[0, 1]`.
+        fps (`float`, *optional*, defaults to 24.0):
+            The frame rate `frames` carries, which is what places the reference's vision blocks on the conditioner's 2
+            fps grid. MiniMax-H3's own clock is 24 fps, so any other rate is resampled onto it by dropping and
+            duplicating whole frames — which makes this the field to get right when the frames came from a file.
+        audio (`torch.Tensor` of shape `(channels, num_samples)`, *optional*):
+            This video's soundtrack, mono or stereo, conditioned on as the reference's own rather than as a reference
+            of its own. Left out, the reference conditions on motion alone.
+        sample_rate (`int`, *optional*):
+            The rate `audio` carries its samples at. Left out, it is the audio VAE's own, which leaves the samples
+            untouched; any other rate is resampled onto it.
+    """
+
+    frames: list[Image.Image] | np.ndarray | torch.Tensor
+    fps: float | None = None
+    audio: torch.Tensor | None = None
+    sample_rate: int | None = None
+
+    kind = "video"
+
+    def __post_init__(self):
+        if self.fps is None:
+            self.fps = float(MINIMAX_H3_FPS)
+
+    @property
+    def has_audio(self) -> bool:
+        r"""Whether this reference contributes audio rows, i.e. whether it carries a soundtrack."""
+        return self.audio is not None
+
+
+@dataclass
+class MiniMaxH3AudioReference(MiniMaxH3Reference):
+    r"""
+    A voice or music reference: at most 3 per request, and never on its own — an audio reference has to be paired with
+    at least one image or video reference. It never reaches the conditioner and is encoded by the audio VAE alone.
+
+    Attributes:
+        audio (`torch.Tensor` of shape `(channels, num_samples)`):
+            The reference waveform, mono or stereo.
+        sample_rate (`int`, *optional*):
+            The rate `audio` carries its samples at. Left out, it is the audio VAE's own, which leaves the samples
+            untouched; any other rate is resampled onto it.
+    """
+
+    audio: torch.Tensor
+    sample_rate: int | None = None
+
+    kind = "audio"
+    has_audio = True
diff --git a/src/diffusers/modular_pipelines/modular_pipeline.py b/src/diffusers/modular_pipelines/modular_pipeline.py
index 45d98775708b..cb0211d7ebff 100644
--- a/src/diffusers/modular_pipelines/modular_pipeline.py
+++ b/src/diffusers/modular_pipelines/modular_pipeline.py
@@ -150,7 +150,6 @@ def _helios_pyramid_map_fn(config_dict=None):
         ("hunyuan-video-1.5", _create_default_map_fn("HunyuanVideo15ModularPipeline")),
         ("ltx", _create_default_map_fn("LTXModularPipeline")),
         ("minimax-h3", _create_default_map_fn("MiniMaxH3ModularPipeline")),
-        ("minimax-h3-ref2va", _create_default_map_fn("MiniMaxH3Ref2VAModularPipeline")),
         ("ernie-image", _create_default_map_fn("ErnieImageModularPipeline")),
     ]
 )
diff --git a/src/diffusers/utils/dummy_torch_and_transformers_objects.py b/src/diffusers/utils/dummy_torch_and_transformers_objects.py
index d5abf9efa891..8058937aa2a8 100644
--- a/src/diffusers/utils/dummy_torch_and_transformers_objects.py
+++ b/src/diffusers/utils/dummy_torch_and_transformers_objects.py
@@ -542,36 +542,6 @@ def from_pretrained(cls, *args, **kwargs):
         requires_backends(cls, ["torch", "transformers"])
 
 
-class MiniMaxH3Ref2VABlocks(metaclass=DummyObject):
-    _backends = ["torch", "transformers"]
-
-    def __init__(self, *args, **kwargs):
-        requires_backends(self, ["torch", "transformers"])
-
-    @classmethod
-    def from_config(cls, *args, **kwargs):
-        requires_backends(cls, ["torch", "transformers"])
-
-    @classmethod
-    def from_pretrained(cls, *args, **kwargs):
-        requires_backends(cls, ["torch", "transformers"])
-
-
-class MiniMaxH3Ref2VAModularPipeline(metaclass=DummyObject):
-    _backends = ["torch", "transformers"]
-
-    def __init__(self, *args, **kwargs):
-        requires_backends(self, ["torch", "transformers"])
-
-    @classmethod
-    def from_config(cls, *args, **kwargs):
-        requires_backends(cls, ["torch", "transformers"])
-
-    @classmethod
-    def from_pretrained(cls, *args, **kwargs):
-        requires_backends(cls, ["torch", "transformers"])
-
-
 class QwenImageAutoBlocks(metaclass=DummyObject):
     _backends = ["torch", "transformers"]
 
diff --git a/tests/modular_pipelines/minimax_h3/test_modular_pipeline_minimax_h3.py b/tests/modular_pipelines/minimax_h3/test_modular_pipeline_minimax_h3.py
index 27344667e837..c0ff99ba9e05 100644
--- a/tests/modular_pipelines/minimax_h3/test_modular_pipeline_minimax_h3.py
+++ b/tests/modular_pipelines/minimax_h3/test_modular_pipeline_minimax_h3.py
@@ -20,8 +20,6 @@
 from diffusers.modular_pipelines import (
     MiniMaxH3Blocks,
     MiniMaxH3ModularPipeline,
-    MiniMaxH3Ref2VABlocks,
-    MiniMaxH3Ref2VAModularPipeline,
 )
 from diffusers.modular_pipelines.minimax_h3 import (
     MiniMaxH3AudioReference,
@@ -30,14 +28,13 @@
     MiniMaxH3VideoReference,
     decode_reference_audio,
     decode_reference_video,
-    packing,
-    packing_ref2va,
     reference_loading,
 )
+from diffusers.modular_pipelines.minimax_h3 import modular_pipeline as minimax_h3_geometry
 from diffusers.modular_pipelines.minimax_h3.before_encoder import MiniMaxH3Ref2VASetupStep
 from diffusers.modular_pipelines.minimax_h3.encoders import MiniMaxH3Ref2VATextEncoderStep, MiniMaxH3TextEncoderStep
+from diffusers.modular_pipelines.minimax_h3.modular_pipeline import MINIMAX_H3_FPS
 
-from ...testing_utils import torch_device
 from ..test_modular_pipelines_common import ModularPipelineTesterMixin, _get_specified_components
 
 
@@ -61,41 +58,48 @@
 TINY_MODULAR_REPO_ID = "hf-internal-testing/tiny-minimax-h3-modular-pipe"
 
 
-T2VA_WORKFLOW = [
-    ("resize", "MiniMaxH3AutoResizeStep"),
-    ("text_encoder", "MiniMaxH3TextEncoderStep"),
-    ("prepare_layout", "MiniMaxH3PrepareLayoutStep"),
-    ("prepare_latents", "MiniMaxH3PrepareLatentsStep"),
-    ("set_timesteps", "MiniMaxH3SetTimestepsStep"),
-    ("denoise", "MiniMaxH3DenoiseStep"),
+_CORE_DENOISE = [
+    ("denoise.prepare_latents", "MiniMaxH3PrepareLatentsStep"),
+    ("denoise.set_timesteps", "MiniMaxH3SetTimestepsStep"),
+]
+_TAIL = [
+    ("after_denoise", "MiniMaxH3AfterDenoiseStep"),
     ("decode.video", "MiniMaxH3VideoDecodeStep"),
     ("decode.audio", "MiniMaxH3AudioDecodeStep"),
 ]
-# A keyframe adds the one block that encodes it; whether it anchors the first or the last frame is a matter of the
-# packed layout, not of which blocks run.
+T2VA_WORKFLOW = [
+    ("text_encoder", "MiniMaxH3TextEncoderStep"),
+    ("denoise.prepare_layout", "MiniMaxH3PrepareLayoutStep"),
+    *_CORE_DENOISE,
+    ("denoise.denoise", "MiniMaxH3DenoiseStep"),
+    *_TAIL,
+]
+# A keyframe adds the canvas block and the one block that encodes it; whether it anchors the first or the last frame
+# is a matter of the packed layout, not of which blocks run.
 FL2VA_WORKFLOW = [
-    *T2VA_WORKFLOW[:2],
+    ("before_encode", "MiniMaxH3ResizeStep"),
+    ("text_encoder", "MiniMaxH3TextEncoderStep"),
     ("vae_encoder", "MiniMaxH3KeyframeVaeEncoderStep"),
-    *T2VA_WORKFLOW[2:],
+    ("denoise.prepare_layout", "MiniMaxH3PrepareLayoutStep"),
+    *_CORE_DENOISE,
+    ("denoise.denoise", "MiniMaxH3DenoiseStep"),
+    *_TAIL,
+]
+REF2VA_WORKFLOW = [
+    ("before_encode", "MiniMaxH3Ref2VASetupStep"),
+    ("text_encoder", "MiniMaxH3Ref2VATextEncoderStep"),
+    ("vae_encoder", "MiniMaxH3Ref2VAReferenceEncoderStep"),
+    ("denoise.prepare_layout", "MiniMaxH3Ref2VAPrepareLayoutStep"),
+    *_CORE_DENOISE,
+    ("denoise.denoise", "MiniMaxH3Ref2VADenoiseStep"),
+    *_TAIL,
 ]
 MINIMAX_H3_WORKFLOWS = {
     "t2va": T2VA_WORKFLOW,
     "fl2va": FL2VA_WORKFLOW,
     "fl2va_last_frame": FL2VA_WORKFLOW,
 }
-MINIMAX_H3_REF2VA_WORKFLOWS = {
-    "ref2va": [
-        ("setup", "MiniMaxH3Ref2VASetupStep"),
-        ("text_encoder", "MiniMaxH3Ref2VATextEncoderStep"),
-        ("reference_encoder", "MiniMaxH3Ref2VAReferenceEncoderStep"),
-        ("prepare_layout", "MiniMaxH3Ref2VAPrepareLayoutStep"),
-        ("prepare_latents", "MiniMaxH3PrepareLatentsStep"),
-        ("set_timesteps", "MiniMaxH3SetTimestepsStep"),
-        ("denoise", "MiniMaxH3Ref2VADenoiseStep"),
-        ("decode.video", "MiniMaxH3VideoDecodeStep"),
-        ("decode.audio", "MiniMaxH3AudioDecodeStep"),
-    ]
-}
+MINIMAX_H3_REF2VA_WORKFLOWS = {"ref2va": REF2VA_WORKFLOW}
 
 
 def _video_frames(num_frames: int, size: int) -> np.ndarray:
@@ -110,7 +114,7 @@ def _waveform(duration: float) -> torch.Tensor:
 
 def _reference_video(num_frames: int, size: int) -> MiniMaxH3VideoReference:
     """A silent video reference at MiniMax-H3's own 24 fps."""
-    return MiniMaxH3VideoReference(frames=_video_frames(num_frames, size), fps=float(packing.MINIMAX_H3_FPS))
+    return MiniMaxH3VideoReference(frames=_video_frames(num_frames, size), fps=float(MINIMAX_H3_FPS))
 
 
 def _reference_audio(duration: float) -> MiniMaxH3AudioReference:
@@ -192,10 +196,16 @@ def small_references():
     request of this module passes `height` and `width`, so the canvas of a generated video is never derived from
     these. `TestMiniMaxH3ReferenceGeometry` restores the released value where it pins it.
     """
+    original_init = MiniMaxH3Ref2VASetupStep.__init__
+
+    def small_reference_init(self, *args, **kwargs):
+        kwargs.setdefault("reference_image_short_edge", TEST_REFERENCE_IMAGE_SHORT_EDGE)
+        original_init(self, *args, **kwargs)
+
     with pytest.MonkeyPatch.context() as patch:
-        patch.setattr(packing_ref2va, "MINIMAX_H3_REFERENCE_IMAGE_SHORT_EDGE", TEST_REFERENCE_IMAGE_SHORT_EDGE)
-        patch.setattr(packing, "MINIMAX_H3_SHORT_EDGE", TEST_REFERENCE_IMAGE_SHORT_EDGE)
-        patch.setattr(packing, "MINIMAX_H3_MAX_PIXELS", TEST_REFERENCE_IMAGE_SHORT_EDGE**2 * 2)
+        patch.setattr(MiniMaxH3Ref2VASetupStep, "__init__", small_reference_init)
+        patch.setattr(minimax_h3_geometry, "MINIMAX_H3_SHORT_EDGE", TEST_REFERENCE_IMAGE_SHORT_EDGE)
+        patch.setattr(minimax_h3_geometry, "MINIMAX_H3_MAX_PIXELS", TEST_REFERENCE_IMAGE_SHORT_EDGE**2 * 2)
         yield
 
 
@@ -395,17 +405,13 @@ def test_encode_prompt(self, num_keyframes):
         pipe = self.get_pipeline()
         keyframe = Image.fromarray((np.random.default_rng(0).random((32, 32, 3)) * 255).astype("uint8"))
 
-        prompt_embeds, text_token_tags = MiniMaxH3TextEncoderStep.encode_prompt(
-            pipe.text_encoder,
-            pipe.tokenizer,
-            pipe.processor,
-            "a robot dancing",
-            [keyframe] * num_keyframes,
-            text_encoder_layer=pipe.text_encoder_layer,
-            text_tag=pipe.text_tag,
-            video_tag=pipe.video_tag,
-            device=torch_device,
-        )
+        inputs = self.get_dummy_inputs()
+        if num_keyframes:
+            inputs["image"] = keyframe
+        if num_keyframes == 2:
+            inputs["last_image"] = keyframe
+        state = pipe(**inputs)
+        prompt_embeds, text_token_tags = state.get("prompt_embeds"), state.get("text_token_tags")
 
         assert prompt_embeds.shape[0] == 1
         assert prompt_embeds.shape[-1] == pipe.transformer.config.text_dim
@@ -480,8 +486,8 @@ def test_check_inputs(self, overrides, message):
 
 
 class TestMiniMaxH3Ref2VAModularPipelineFast(MiniMaxH3ModularTesterBase):
-    pipeline_class = MiniMaxH3Ref2VAModularPipeline
-    pipeline_blocks_class = MiniMaxH3Ref2VABlocks
+    pipeline_class = MiniMaxH3ModularPipeline
+    pipeline_blocks_class = MiniMaxH3Blocks
 
     params = frozenset(["prompt", "references", "height", "width", "num_frames"])
     expected_workflow_blocks = MINIMAX_H3_REF2VA_WORKFLOWS
@@ -566,7 +572,7 @@ def run(seed, video_noise, audio_noise):
 
     @pytest.mark.parametrize(
         "kinds,num_frames",
-        [(("video",), NUM_FRAMES), (("image", "audio"), None), (("video", "image"), NUM_FRAMES)],
+        [(("video",), NUM_FRAMES), (("image", "audio"), NUM_FRAMES), (("video", "image"), NUM_FRAMES)],
         ids=["video", "image_audio", "video_image"],
     )
     def test_reference_combinations(self, kinds, num_frames):
@@ -575,9 +581,7 @@ def test_reference_combinations(self, kinds, num_frames):
 
         A video reference conditions on its motion *and*, when the request passes one with it, on its soundtrack, so
         it contributes both visual and audio rows; an audio reference contributes audio rows alone and never reaches
-        the conditioner. The `image_audio` case also leaves `num_frames` to the references, which is admissible
-        because exactly one of them carries audio: the duration is that soundtrack's, snapped up to the next
-        `17 * n + 5` the video VAE can decode.
+        the conditioner.
 
         The reference rows are pinned for the whole loop, which is what the denoised sequence is checked against: the
         visual anchors keep their noise-augmented values and the audio anchors stay exactly as the encoder produced
@@ -587,8 +591,8 @@ def test_reference_combinations(self, kinds, num_frames):
             "image": MiniMaxH3ImageReference(image=Image.new("RGB", (48, 80))),
             # A one-second video reference, soundtrack included, and a six-second standalone soundtrack.
             "video": MiniMaxH3VideoReference(
-                frames=_video_frames(packing.MINIMAX_H3_FPS, 64),
-                fps=float(packing.MINIMAX_H3_FPS),
+                frames=_video_frames(MINIMAX_H3_FPS, 64),
+                fps=float(MINIMAX_H3_FPS),
                 audio=_waveform(1.0),
                 sample_rate=AUDIO_SAMPLE_RATE,
             ),
@@ -627,19 +631,10 @@ def test_encode_prompt(self, kinds):
         """
         pipe = self.get_pipeline()
         media = {"image": MiniMaxH3ImageReference(image=Image.new("RGB", (48, 80))), "video": _reference_video(25, 32)}
-        references, _ = MiniMaxH3Ref2VASetupStep.prepare_references(pipe, [media[kind] for kind in kinds], NUM_FRAMES)
-
-        prompt_embeds, text_token_tags = MiniMaxH3Ref2VATextEncoderStep.encode_prompt(
-            pipe.text_encoder,
-            pipe.tokenizer,
-            pipe.processor,
-            "a robot dancing",
-            references,
-            text_encoder_layer=pipe.text_encoder_layer,
-            text_tag=pipe.text_tag,
-            video_tag=pipe.video_tag,
-            device=torch_device,
-        )
+        inputs = self.get_dummy_inputs()
+        inputs["references"] = [media[kind] for kind in kinds]
+        state = pipe(**inputs)
+        prompt_embeds, text_token_tags = state.get("prompt_embeds"), state.get("text_token_tags")
 
         assert prompt_embeds.shape[0] == 1
         assert prompt_embeds.shape[-1] == pipe.transformer_ref.config.text_dim
@@ -665,11 +660,13 @@ def test_reference_media_layouts(self, media_type):
         else:
             image, frames = torch.from_numpy(pixels[0]).permute(2, 0, 1), torch.from_numpy(pixels).permute(0, 3, 1, 2)
 
-        references, _ = MiniMaxH3Ref2VASetupStep.prepare_references(
-            pipe,
-            [MiniMaxH3ImageReference(image=image), MiniMaxH3VideoReference(frames=frames, fps=float(packing.MINIMAX_H3_FPS))],
-            NUM_FRAMES,
-        )
+        inputs = self.get_dummy_inputs()
+        inputs["references"] = [
+            MiniMaxH3ImageReference(image=image),
+            MiniMaxH3VideoReference(frames=frames, fps=float(MINIMAX_H3_FPS)),
+        ]
+        state = pipe(**inputs)
+        references = state.get("normalized_references")
 
         assert np.array_equal(np.asarray(references[0].image), pixels[0])
         assert np.array_equal(references[1].frames, pixels)
@@ -683,9 +680,10 @@ def test_reference_rates_default_to_the_model_rates(self):
         frames = _video_frames(NUM_FRAMES, TEST_REFERENCE_IMAGE_SHORT_EDGE)
         waveform = _waveform(2.0)
 
-        references, _ = MiniMaxH3Ref2VASetupStep.prepare_references(
-            pipe, [MiniMaxH3VideoReference(frames=frames), MiniMaxH3AudioReference(audio=waveform)], NUM_FRAMES
-        )
+        inputs = self.get_dummy_inputs()
+        inputs["references"] = [MiniMaxH3VideoReference(frames=frames), MiniMaxH3AudioReference(audio=waveform)]
+        state = pipe(**inputs)
+        references = state.get("normalized_references")
 
         assert np.shares_memory(references[0].frames, frames)
         assert torch.equal(references[1].audio, waveform)
@@ -695,58 +693,17 @@ def test_reference_sample_rate_override_resamples(self):
         pipe = self.get_pipeline()
         waveform = _waveform(2.0)
 
-        references, _ = MiniMaxH3Ref2VASetupStep.prepare_references(
-            pipe,
-            [
-                MiniMaxH3ImageReference(image=Image.new("RGB", (48, 80))),
-                MiniMaxH3AudioReference(audio=waveform, sample_rate=AUDIO_SAMPLE_RATE // 2),
-            ],
-            NUM_FRAMES,
-        )
+        inputs = self.get_dummy_inputs()
+        inputs["references"] = [
+            MiniMaxH3ImageReference(image=Image.new("RGB", (48, 80))),
+            MiniMaxH3AudioReference(audio=waveform, sample_rate=AUDIO_SAMPLE_RATE // 2),
+        ]
+        state = pipe(**inputs)
+        references = state.get("normalized_references")
 
         # Half the audio VAE's rate, so the same samples span twice as many of the VAE's own.
         assert references[1].audio.shape == (2, 2 * waveform.shape[-1])
 
-    def test_num_frames_left_open_needs_exactly_one_audio_reference(self):
-        r"""Leaving `num_frames` out is ambiguous unless exactly one reference carries audio."""
-        pipe = self.get_pipeline()
-
-        inputs = self.get_dummy_inputs()
-        inputs["num_frames"] = None
-
-        with pytest.raises(ValueError, match="may only be left to the references"):
-            pipe(**inputs)
-
-    def test_num_frames_left_open_holds_the_ceiling_for_the_aligned_count(self):
-        r"""
-        A soundtrack just under 15 seconds is rejected rather than silently stretched past the ceiling.
-
-        14.99 seconds round to 360 frames, which the video VAE's `17 * n + 5` grid rounds up to 362, i.e. 15.083
-        seconds. The duration the request generates is the aligned one, so that is what the bound holds for.
-        """
-        pipe = self.get_pipeline()
-
-        inputs = self.get_dummy_inputs()
-        inputs["num_frames"] = None
-        inputs["references"] = [MiniMaxH3ImageReference(image=Image.new("RGB", (48, 80))), _reference_audio(14.99)]
-
-        with pytest.raises(ValueError, match="rounds up to 362 frames"):
-            pipe(**inputs)
-
-    @pytest.mark.parametrize(
-        "references,message",
-        [
-            ([], "at least one reference"),
-            ([_reference_audio(6.0)], "cannot be used"),
-            ([MiniMaxH3ImageReference(image=Image.new("RGB", (32, 32)))] * 10, "at most 9 image references"),
-            (
-                [MiniMaxH3ImageReference(image=Image.new("RGB", (32, 32)))] + [_reference_video(2, 32)] * 4,
-                "at most 3 video references",
-            ),
-            ([{"image": Image.new("RGB", (32, 32))}], "must be a \\[`MiniMaxH3ImageReference`\\]"),
-        ],
-        ids=["no_references", "audio_alone", "too_many_images", "too_many_videos", "dict_entry"],
-    )
     def test_check_inputs_references(self, references, message):
         pipe = self.get_pipeline()
 
@@ -767,7 +724,7 @@ class TestMiniMaxH3Reference:
 
     def test_reference_defaults(self):
         r"""A reference knows its own modality, and defaults to MiniMax-H3's own frame rate for its frames."""
-        assert MiniMaxH3VideoReference(frames=_video_frames(2, 32)).fps == float(packing.MINIMAX_H3_FPS)
+        assert MiniMaxH3VideoReference(frames=_video_frames(2, 32)).fps == float(MINIMAX_H3_FPS)
         assert MiniMaxH3ImageReference(image=Image.new("RGB", (32, 32))).kind == "image"
         assert not MiniMaxH3ImageReference(image=Image.new("RGB", (32, 32))).has_audio
         assert _reference_video(2, 32).kind == "video"
@@ -901,7 +858,7 @@ def test_load_references_block_rejects(self, entry, message):
 
 class TestMiniMaxH3ReferenceGeometry:
     """
-    How a reference is prepared, which is pure geometry over the packing module and needs no components.
+    How a reference is prepared, which is pure geometry and needs no checkpoint.
 
     These are the passes `MiniMaxH3Ref2VASetupStep` runs a reference through before any VAE sees it.
     """
@@ -913,20 +870,28 @@ def test_video_reference_vision_blocks(self):
 
         A 25 frame reference at 24 fps samples three frames, which merge into two blocks at 0.25 and 1.0 seconds.
         """
-        frames, timestamps = packing_ref2va.sample_reference_video_frames(_video_frames(25, 32))
+        frames, timestamps = MiniMaxH3Ref2VATextEncoderStep._sample_video_condition_frames(
+            _video_frames(25, 32), fps=24.0, sample_fps=2.0, temporal_patch=2
+        )
 
         assert len(frames) == 3
         assert timestamps == [0.25, 1.0]
 
-    def test_reference_image_geometry(self, monkeypatch):
+    def test_reference_image_geometry(self):
         r"""
         A reference image is encoded at a 2048 pixel short edge, both axes rounded to a multiple of 32, with no area
-        cap. The `small_references` fixture shrinks that short edge for every other test, so restore it here.
+        cap — the released geometry, so the setup step is constructed explicitly rather than through the
+        `small_references` fixture's shrunken default.
         """
-        monkeypatch.setattr(packing_ref2va, "MINIMAX_H3_REFERENCE_IMAGE_SHORT_EDGE", 2048)
+        pipe = MiniMaxH3Ref2VASetupStep(reference_image_short_edge=2048).init_pipeline()
+
+        references = pipe(
+            references=[MiniMaxH3ImageReference(image=Image.new("RGB", (80, 48)))],
+            num_frames=124,
+            output="normalized_references",
+        )
 
-        assert packing_ref2va.resolve_reference_image_size(80, 48, 32) == (2048, 3424)
-        assert packing_ref2va.resolve_reference_image_size(48, 80, 32) == (3424, 2048)
+        assert references[0].image.size == (3424, 2048)
 
     def test_video_reference_resampled_to_the_model_frame_rate(self):
         r"""
@@ -935,12 +900,20 @@ def test_video_reference_resampled_to_the_model_frame_rate(self):
         output slot is dropped, so a 30 fps reference loses one frame in five, the later of the two that tie for a
         slot. Frames already at 24 fps are returned as they are, without a copy.
         """
-        # Every frame carries its own index as its pixel value, so the resampled frames name the ones that survived.
-        frames = np.arange(30, dtype="uint8").reshape(-1, 1, 1, 1) * np.ones((1, 2, 2, 3), dtype="uint8")
-
-        resampled = packing_ref2va.resample_reference_frames(frames, 30.0)
+        # Every frame carries its own index as its pixel value, so the resampled frames name the ones that
+        # survived. The frames sit at the canvas their aspect resolves to under the `small_references` fixture, so
+        # the resize pass is a no-op and the 24 fps route returns the input without a copy.
+        size = TEST_REFERENCE_IMAGE_SHORT_EDGE
+        frames = np.arange(30, dtype="uint8").reshape(-1, 1, 1, 1) * np.ones((1, size, size, 3), dtype="uint8")
+
+        resampled = MiniMaxH3Ref2VASetupStep._normalize_video_condition(
+            frames, fps=30.0, num_frames=NUM_FRAMES, canvas_multiple=32
+        )
 
         assert [int(frame[0, 0, 0]) for frame in resampled] == [
             index for index in range(30) if index not in (2, 7, 12, 17, 22, 27)
         ]
-        assert packing_ref2va.resample_reference_frames(frames, float(packing.MINIMAX_H3_FPS)) is frames
+        untouched = MiniMaxH3Ref2VASetupStep._normalize_video_condition(
+            frames, fps=float(MINIMAX_H3_FPS), num_frames=NUM_FRAMES, canvas_multiple=32
+        )
+        assert np.shares_memory(untouched, frames)

From 81107806a7ee388aa5d97bdc94131f9bb3896c30 Mon Sep 17 00:00:00 2001
From: yiyixuxu <yixu310@gmail.com>
Date: Mon, 3 Aug 2026 19:41:14 +0000
Subject: [PATCH 09/16] Let a modular pipeline load one workflow at a time
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Blocks already declare their workflows (`_workflow_map`, `get_workflow`), but
loading could not use them: selecting a workflow meant pruning the blocks by
hand and calling `init_pipeline` yourself. Both loading entry points now take
the name directly.

`ModularPipeline.from_pretrained(repo, workflow="ref2va")` prunes the blocks
before the component specs are derived, so the pipeline only expects — and a
plain `load_components()` only loads — the components that workflow uses. For
MiniMax-H3 that is the difference between pulling one 61.7GB transformer
partition and pulling both. `load_components(workflow=...)` does the same
restriction at load time for a pipeline that kept the full blocks, which is
the shape for switching workflows under one ComponentsManager; passing it
together with `names` raises. An unknown workflow name now lists the
available ones.

`unload_components(names)` is the explicit counterpart for taking a component
back out: the attribute returns to `None` while the spec survives, so
`load_components` can restore it, and an attached ComponentsManager drops it
too. The method releases its own reference before the manager's removal runs,
and ends with an unconditional `gc.collect()` + `empty_device_cache()` —
the manager's cleanup is skipped on its auto-offload path, so relying on it
would leave hooked modules cycling in memory. Unloading is removal, not
offloading: parking a component in cheaper memory is what the manager's
offloading already does.

The mixin tests pin the new arguments to the route that already existed:
`from_pretrained(workflow=...)` must produce the same component names and
byte-equal specs as `get_workflow(...).init_pipeline(repo)`, and
`load_components(workflow=...)` on full blocks must load exactly what the
pruned pipeline loads. The unload test checks the spec object survives the
round trip and the ComponentsManager forgets the component.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 .../modular_pipelines/modular_pipeline.py     | 71 ++++++++++++++++++-
 .../test_modular_pipelines_common.py          | 68 ++++++++++++++++++
 2 files changed, 136 insertions(+), 3 deletions(-)

diff --git a/src/diffusers/modular_pipelines/modular_pipeline.py b/src/diffusers/modular_pipelines/modular_pipeline.py
index cb0211d7ebff..05315c7a2630 100644
--- a/src/diffusers/modular_pipelines/modular_pipeline.py
+++ b/src/diffusers/modular_pipelines/modular_pipeline.py
@@ -11,6 +11,7 @@
 # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 # See the License for the specific language governing permissions and
 # limitations under the License.
+import gc
 import importlib
 import inspect
 import os
@@ -38,7 +39,7 @@
 from ..utils import PushToHubMixin, is_accelerate_available, logging
 from ..utils.dynamic_modules_utils import get_class_from_dynamic_module, resolve_trust_remote_code
 from ..utils.hub_utils import load_or_create_model_card, populate_model_card
-from ..utils.torch_utils import is_compiled_module
+from ..utils.torch_utils import empty_device_cache, is_compiled_module
 from .components_manager import ComponentsManager
 from .modular_pipeline_utils import (
     MODULAR_MODEL_CARD_TEMPLATE,
@@ -1012,7 +1013,10 @@ def get_workflow(self, workflow_name: str):
             )
 
         if workflow_name not in self._workflow_map:
-            raise ValueError(f"Workflow {workflow_name} not found in {self.__class__.__name__}")
+            raise ValueError(
+                f"Workflow {workflow_name!r} not found in {self.__class__.__name__}. "
+                f"Available workflows: {list(self._workflow_map)}"
+            )
 
         trigger_inputs = self._workflow_map[workflow_name]
         workflow_blocks = self.get_execution_blocks(**trigger_inputs)
@@ -1626,6 +1630,7 @@ def __init__(
         pretrained_model_name_or_path: str | os.PathLike | None = None,
         components_manager: ComponentsManager | None = None,
         collection: str | None = None,
+        workflow: str | None = None,
         modular_config_dict: dict[str, Any] | None = None,
         config_dict: dict[str, Any] | None = None,
         **kwargs,
@@ -1652,6 +1657,9 @@ def __init__(
                 Optional ComponentsManager for managing multiple component cross different pipelines and apply
                 offloading strategies.
             collection: Optional collection name for organizing components in the ComponentsManager.
+            workflow: Optional workflow name. If provided, the blocks are pruned to that workflow's execution
+                    blocks (see `ModularPipelineBlocks.get_workflow`), so the pipeline only expects — and
+                    `load_components()` only loads — the components that workflow uses.
             **kwargs: Additional arguments passed to `load_config()` when loading pretrained configuration.
 
         Examples:
@@ -1720,6 +1728,11 @@ def __init__(
             else:
                 logger.warning(f"`blocks` is `None`, no default blocks class found for {self.__class__.__name__}")
 
+        if workflow is not None:
+            if blocks is None:
+                raise ValueError(f"`workflow={workflow!r}` requires pipeline blocks, but none could be resolved.")
+            blocks = blocks.get_workflow(workflow)
+
         self._blocks = blocks
         self._components_manager = components_manager
         self._collection = collection
@@ -1825,6 +1838,7 @@ def from_pretrained(
         trust_remote_code: bool | None = None,
         components_manager: ComponentsManager | None = None,
         collection: str | None = None,
+        workflow: str | None = None,
         **kwargs,
     ):
         """
@@ -1844,6 +1858,10 @@ def from_pretrained(
                 offloading strategies.
             collection (`str`, optional):`
                 Collection name for organizing components in the ComponentsManager.
+            workflow (`str`, optional):
+                Name of a workflow declared by the pipeline blocks. If provided, the blocks are pruned to that
+                workflow's execution blocks, so the pipeline only expects — and `load_components()` only loads —
+                the components that workflow uses.
         """
         from ..pipelines.pipeline_loading_utils import _get_pipeline_class
 
@@ -1897,6 +1915,7 @@ def from_pretrained(
             pretrained_model_name_or_path=pretrained_model_name_or_path,
             components_manager=components_manager,
             collection=collection,
+            workflow=workflow,
             modular_config_dict=modular_config_dict,
             config_dict=config_dict,
             **kwargs,
@@ -2360,7 +2379,7 @@ def update_components(self, **kwargs):
             config_to_register[name] = new_value
         self.register_to_config(**config_to_register)
 
-    def load_components(self, names: list[str] | str | None = None, **kwargs):
+    def load_components(self, names: list[str] | str | None = None, workflow: str | None = None, **kwargs):
         """
         Load selected components from specs.
 
@@ -2368,6 +2387,8 @@ def load_components(self, names: list[str] | str | None = None, **kwargs):
             names: list of component names to load. If None, will load all components with
                    default_creation_method == "from_pretrained". If provided as a list or string, will load only the
                    specified components.
+            workflow: name of a workflow declared by the pipeline blocks. If provided, only the components that
+                   workflow's execution blocks use are loaded. Cannot be combined with `names`.
             **kwargs: additional kwargs to be passed to `from_pretrained()`.Can be:
              - a single value to be applied to all components to be loaded, e.g. dtype=torch.bfloat16
              - a dict, e.g. dtype={"unet": torch.bfloat16, "default": torch.float32}
@@ -2377,6 +2398,9 @@ def load_components(self, names: list[str] | str | None = None, **kwargs):
                `pretrained_model_name_or_path`, `variant`, `revision`, etc.
         """
 
+        if workflow is not None and names is not None:
+            raise ValueError("Pass either `names` or `workflow`, not both.")
+
         if names is None:
             names = [
                 name
@@ -2390,6 +2414,10 @@ def load_components(self, names: list[str] | str | None = None, **kwargs):
         elif not isinstance(names, list):
             raise ValueError(f"Invalid type for names: {type(names)}")
 
+        if workflow is not None:
+            workflow_component_names = {spec.name for spec in self.blocks.get_workflow(workflow).expected_components}
+            names = [name for name in names if name in workflow_component_names]
+
         components_to_load = {name for name in names if name in self._component_specs}
         unknown_names = {name for name in names if name not in self._component_specs}
         if len(unknown_names) > 0:
@@ -2457,6 +2485,43 @@ def load_components(self, names: list[str] | str | None = None, **kwargs):
         # Register all components at once
         self.register_components(**components_to_register)
 
+    def unload_components(self, names: list[str] | str):
+        """
+        Unload selected components, freeing their memory.
+
+        The component attribute is set back to `None` and, if a ComponentsManager is attached, the component is
+        removed from it. The component spec is untouched, so the component can be loaded again later with
+        `load_components()`.
+
+        Args:
+            names: component name or list of component names to unload.
+        """
+        if isinstance(names, str):
+            names = [names]
+        elif not isinstance(names, list):
+            raise ValueError(f"Invalid type for names: {type(names)}")
+
+        unknown_names = {name for name in names if name not in self._component_specs}
+        if len(unknown_names) > 0:
+            logger.warning(f"Unknown components will be ignored: {unknown_names}")
+
+        for name in names:
+            if name in unknown_names:
+                continue
+            # not holding the full `components` dict across iterations: a lingering reference would keep the
+            # unloaded component alive through the gc pass below
+            component = self.components.get(name)
+            if component is None:
+                continue
+            component_id = f"{name}_{id(component)}"
+            self.register_components(**{name: None})
+            del component
+            if self._components_manager is not None and component_id in self._components_manager.components:
+                self._components_manager.remove(component_id)
+
+        gc.collect()
+        empty_device_cache()
+
     # Copied from diffusers.pipelines.pipeline_utils.DiffusionPipeline._maybe_raise_error_if_group_offload_active
     def _maybe_raise_error_if_group_offload_active(
         self, raise_error: bool = False, module: torch.nn.Module | None = None
diff --git a/tests/modular_pipelines/test_modular_pipelines_common.py b/tests/modular_pipelines/test_modular_pipelines_common.py
index 70e30b753693..073eb70fa2fe 100644
--- a/tests/modular_pipelines/test_modular_pipelines_common.py
+++ b/tests/modular_pipelines/test_modular_pipelines_common.py
@@ -505,6 +505,74 @@ def test_workflow_map(self):
                     f"{actual_block.__class__.__name__}, expected {expected_class_name}"
                 )
 
+    def test_from_pretrained_workflow(self):
+        blocks = self.pipeline_blocks_class()
+        if blocks._workflow_map is None:
+            pytest.skip("Skipping test as _workflow_map is not set")
+
+        for workflow_name in blocks.available_workflows:
+            # the workflow argument should be equivalent to pruning the blocks by hand
+            pipe = ModularPipeline.from_pretrained(self.pretrained_model_name_or_path, workflow=workflow_name)
+            ref_pipe = blocks.get_workflow(workflow_name).init_pipeline(self.pretrained_model_name_or_path)
+            assert set(pipe.component_names) == set(ref_pipe.component_names), (
+                f"Workflow '{workflow_name}': pipeline expects components {sorted(pipe.component_names)}, "
+                f"the workflow blocks expect {sorted(ref_pipe.component_names)}"
+            )
+            for name in pipe.pretrained_component_names:
+                assert pipe.get_component_spec(name) == ref_pipe.get_component_spec(name), (
+                    f"Workflow '{workflow_name}': component '{name}' has a different spec than the one "
+                    f"created from the workflow blocks"
+                )
+
+        with pytest.raises(ValueError, match="Available workflows"):
+            ModularPipeline.from_pretrained(self.pretrained_model_name_or_path, workflow="not_a_workflow")
+
+    def test_load_components_workflow(self):
+        blocks = self.pipeline_blocks_class()
+        if blocks._workflow_map is None:
+            pytest.skip("Skipping test as _workflow_map is not set")
+
+        workflow_name = blocks.available_workflows[0]
+
+        # a full pipeline restricted at load time should load the same components as a pipeline
+        # created from the pruned workflow blocks
+        pipe = ModularPipeline.from_pretrained(self.pretrained_model_name_or_path)
+        pipe.load_components(workflow=workflow_name)
+        ref_pipe = blocks.get_workflow(workflow_name).init_pipeline(self.pretrained_model_name_or_path)
+        ref_pipe.load_components()
+
+        loaded = {name for name in pipe.pretrained_component_names if pipe.components[name] is not None}
+        ref_loaded = {name for name in ref_pipe.pretrained_component_names if ref_pipe.components[name] is not None}
+        assert loaded == ref_loaded, (
+            f"Workflow '{workflow_name}': load_components(workflow=...) loaded {sorted(loaded)}, "
+            f"the pipeline created from the workflow blocks loaded {sorted(ref_loaded)}"
+        )
+
+        with pytest.raises(ValueError, match="not both"):
+            pipe.load_components(names="unet", workflow=workflow_name)
+
+    def test_unload_components(self):
+        pipe = ModularPipeline.from_pretrained(self.pretrained_model_name_or_path)
+        pipe.load_components()
+        name = next(name for name in pipe.pretrained_component_names if pipe.components.get(name) is not None)
+        spec_before = pipe._component_specs[name]
+
+        pipe.unload_components(name)
+        assert getattr(pipe, name) is None
+        # the spec survives, so the component can be loaded again
+        assert pipe._component_specs[name] is spec_before
+        pipe.load_components(names=name)
+        assert getattr(pipe, name) is not None
+
+        # with a ComponentsManager attached, unloading also removes the component from the manager
+        manager = ComponentsManager()
+        pipe = ModularPipeline.from_pretrained(self.pretrained_model_name_or_path, components_manager=manager)
+        pipe.load_components(names=name)
+        assert len(manager._lookup_ids(name=name)) == 1
+        pipe.unload_components(name)
+        assert getattr(pipe, name) is None
+        assert len(manager._lookup_ids(name=name)) == 0
+
 
 class ModularGuiderTesterMixin:
     def test_guider_cfg(self, expected_max_diff=1e-2):

From 665f578278365ea4a3318cb8c9b66ce6c01204b9 Mon Sep 17 00:00:00 2001
From: yiyixuxu <yixu310@gmail.com>
Date: Mon, 3 Aug 2026 21:45:28 +0000
Subject: [PATCH 10/16] Let each MiniMax-H3 reference decode its own file
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

`decode_reference_video` and `decode_reference_audio` were module-level helpers
a user had to know existed next to the classes they construct. They become
`from_file` classmethods on the references themselves — the type names the
modality, so the loader no longer has to: `MiniMaxH3VideoReference.from_file`
returns the frames with the container's true frame rate and its soundtrack,
`MiniMaxH3AudioReference.from_file` a waveform with its sample rate (from an
audio file or a video's soundtrack), and `MiniMaxH3ImageReference.from_file`
goes through `load_image`. The rates riding along is still the point: a rate
lost on the way in — which is what a bare `load_video` does — is a request
conditioned at the wrong speed, with nothing to raise about it.

`MiniMaxH3Ref2VALoadReferencesStep` is deleted. It earned its place when the
dataclasses could not take paths and there was no ergonomic loader; with
`from_file` it was a worse spelling of the same thing, naming the modality in
a `{"video": path}` string key where the classmethod names it in a type. It
was never part of `MiniMaxH3Blocks` and nothing shipped. With the block gone,
`reference_loading.py` held only the machinery behind `from_file`, so it
merges into `references.py` — one module owns the reference story, and only
the PyAV import stays lazy.

The docs build the ref2va example with `from_file`, and a new section feeds a
`t2va` generation straight back as a `ref2va` reference: one pipeline, a
`load_components(workflow=...)` call per task, and an in-memory
`MiniMaxH3VideoReference` built from the generated frames and soundtrack —
already at the model's own rates, so no rate arguments and no lossy container
round-trip.

Parity is untouched: the decode code path is the same, only its packaging
moved.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 docs/source/en/api/pipelines/minimax_h3.md    |  58 +++-
 .../modular_pipelines/minimax_h3/__init__.py  |  10 -
 .../minimax_h3/before_encoder.py              |  11 +-
 .../minimax_h3/modular_blocks_minimax_h3.py   |  12 +-
 .../minimax_h3/reference_loading.py           | 272 ------------------
 .../minimax_h3/references.py                  | 190 +++++++++++-
 .../test_modular_pipeline_minimax_h3.py       |  70 ++---
 7 files changed, 251 insertions(+), 372 deletions(-)
 delete mode 100644 src/diffusers/modular_pipelines/minimax_h3/reference_loading.py

diff --git a/docs/source/en/api/pipelines/minimax_h3.md b/docs/source/en/api/pipelines/minimax_h3.md
index 860d961c4e96..8bf1a3060dfa 100644
--- a/docs/source/en/api/pipelines/minimax_h3.md
+++ b/docs/source/en/api/pipelines/minimax_h3.md
@@ -204,18 +204,17 @@ There is one reference class per modality, each holding in-memory media and the
 
 The rates are what everything is resampled from: frames onto MiniMax-H3's own 24 fps by dropping and duplicating whole frames, a waveform onto the audio VAE's sample rate. Media at MiniMax-H3's own rates flows through untouched, so only data produced at another rate has to say so.
 
-The blocks never open a media file — decoding a path is the caller's job, as it is everywhere else in the library. [`~modular_pipelines.minimax_h3.decode_reference_video`] and [`~modular_pipelines.minimax_h3.decode_reference_audio`] do it with [PyAV](https://github.com/PyAV-Org/PyAV) and return a reference carrying the rates the container reports — a video brings its frame rate and its soundtrack along. Prefer them over [`~utils.load_video`], which drops the frame rate: a reference built from frames whose real rate was lost is conditioned on at the wrong speed, and nothing raises. For a whole request, [`~modular_pipelines.minimax_h3.MiniMaxH3Ref2VALoadReferencesStep`] is the same thing as a block you can put in front of [`MiniMaxH3Blocks`].
+The blocks never open a media file — decoding a path is the caller's job, as it is everywhere else in the library. Each reference class does it through its `from_file` classmethod, which takes a path or a URL (video and audio through [PyAV](https://github.com/PyAV-Org/PyAV)) and returns a reference carrying the rates the container reports — a video brings its frame rate and its soundtrack along. Prefer `from_file` over [`~utils.load_video`], which drops the frame rate: a reference built from frames whose real rate was lost is conditioned on at the wrong speed, and nothing raises.
 
 ```py
 import torch
 from diffusers import ModularPipeline
 from diffusers.modular_pipelines.minimax_h3 import (
+    MiniMaxH3AudioReference,
     MiniMaxH3ImageReference,
     MiniMaxH3VideoReference,
-    decode_reference_audio,
-    decode_reference_video,
 )
-from diffusers.utils import load_image, load_video
+from diffusers.utils import load_video
 from diffusers.utils.export_utils import encode_video
 
 # `ref2va` is a workflow of the one MiniMax-H3 pipeline; selecting it loads only the `transformer_ref/`
@@ -224,7 +223,7 @@ pipe = ModularPipeline.from_pretrained("MiniMaxAI/MiniMax-H3", workflow="ref2va"
 pipe.load_components(dtype=torch.bfloat16)
 pipe.to("cuda")
 
-subject = load_image(
+subject = MiniMaxH3ImageReference.from_file(
     "https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/diffusers/astronaut.jpg"
 )
 
@@ -232,11 +231,11 @@ subject = load_image(
 state = pipe(
     prompt="The character speaks in time with the reference recording, natural lip movement",
     references=[
-        MiniMaxH3ImageReference(image=subject),
-        decode_reference_video(
+        subject,
+        MiniMaxH3VideoReference.from_file(
             "https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/diffusers/hiker.mp4"
         ),
-        decode_reference_audio("voice.wav"),
+        MiniMaxH3AudioReference.from_file("voice.wav"),
     ],
     num_frames=124,
 )
@@ -245,7 +244,7 @@ state = pipe(
 motion = load_video("motion_ref.mp4")
 state = pipe(
     prompt="The subject walks toward camera, matching the reference video's shot rhythm",
-    references=[MiniMaxH3ImageReference(image=subject), MiniMaxH3VideoReference(frames=motion, fps=30.0)],
+    references=[subject, MiniMaxH3VideoReference(frames=motion, fps=30.0)],
     num_frames=124,
 )
 
@@ -260,6 +259,40 @@ encode_video(
 
 `num_frames` is required for `ref2va`. To generate a video exactly as long as a reference soundtrack, compute it from the clip — `round(samples / sample_rate * 24)` — and it is snapped up to the next `17 * n + 5` the video VAE can decode; the resulting duration must stay between the 5 and 15 seconds MiniMax-H3 generates.
 
+### A generation as a reference
+
+Because the workflows share one pipeline, a `t2va` generation can be fed straight back as a `ref2va` reference — and the in-memory constructor is built for exactly this hand-off. The generated media is already at MiniMax-H3's own rates (frames at 24 fps, the soundtrack at the audio VAE's sample rate), so the reference needs no rate arguments and nothing is re-encoded through a lossy container on the way:
+
+```py
+import torch
+from diffusers import ComponentsManager, ModularPipeline
+from diffusers.modular_pipelines.minimax_h3 import MiniMaxH3VideoReference
+
+manager = ComponentsManager()
+manager.enable_auto_cpu_offload(device="cuda")
+
+# The full pipeline holds every workflow and picks one per call from the inputs. Each
+# `load_components(workflow=...)` loads only what that workflow still misses — the second call adds just
+# the `transformer_ref/` partition, everything else is already there.
+pipe = ModularPipeline.from_pretrained("MiniMaxAI/MiniMax-H3", components_manager=manager)
+pipe.load_components(workflow="t2va", dtype=torch.bfloat16)
+
+state = pipe(prompt="An astronaut hiking through the mountains, humming a tune", num_frames=124)
+
+reference = MiniMaxH3VideoReference(
+    frames=state.get("videos")[0],
+    audio=state.get("audio")[0],
+    sample_rate=state.get("sampling_rate"),
+)
+
+pipe.load_components(workflow="ref2va", dtype=torch.bfloat16)
+state = pipe(
+    prompt="The same astronaut now walks along a beach at sunset, humming the same tune",
+    references=[reference],
+    num_frames=124,
+)
+```
+
 ## MiniMaxH3ModularPipeline
 
 [[autodoc]] MiniMaxH3ModularPipeline
@@ -271,15 +304,14 @@ encode_video(
 ## MiniMaxH3ImageReference
 
 [[autodoc]] modular_pipelines.minimax_h3.MiniMaxH3ImageReference
+    - from_file
 
 ## MiniMaxH3VideoReference
 
 [[autodoc]] modular_pipelines.minimax_h3.MiniMaxH3VideoReference
+    - from_file
 
 ## MiniMaxH3AudioReference
 
 [[autodoc]] modular_pipelines.minimax_h3.MiniMaxH3AudioReference
-
-## MiniMaxH3Ref2VALoadReferencesStep
-
-[[autodoc]] modular_pipelines.minimax_h3.MiniMaxH3Ref2VALoadReferencesStep
+    - from_file
diff --git a/src/diffusers/modular_pipelines/minimax_h3/__init__.py b/src/diffusers/modular_pipelines/minimax_h3/__init__.py
index 0b8b32de4312..04e06a1e156b 100644
--- a/src/diffusers/modular_pipelines/minimax_h3/__init__.py
+++ b/src/diffusers/modular_pipelines/minimax_h3/__init__.py
@@ -29,11 +29,6 @@
         "MiniMaxH3Reference",
         "MiniMaxH3VideoReference",
     ]
-    _import_structure["reference_loading"] = [
-        "MiniMaxH3Ref2VALoadReferencesStep",
-        "decode_reference_audio",
-        "decode_reference_video",
-    ]
 
 if TYPE_CHECKING or DIFFUSERS_SLOW_IMPORT:
     try:
@@ -44,11 +39,6 @@
     else:
         from .modular_blocks_minimax_h3 import MiniMaxH3Blocks
         from .modular_pipeline import MiniMaxH3ModularPipeline
-        from .reference_loading import (
-            MiniMaxH3Ref2VALoadReferencesStep,
-            decode_reference_audio,
-            decode_reference_video,
-        )
         from .references import (
             MiniMaxH3AudioReference,
             MiniMaxH3ImageReference,
diff --git a/src/diffusers/modular_pipelines/minimax_h3/before_encoder.py b/src/diffusers/modular_pipelines/minimax_h3/before_encoder.py
index d1f4690daf12..7cefedc8b95a 100644
--- a/src/diffusers/modular_pipelines/minimax_h3/before_encoder.py
+++ b/src/diffusers/modular_pipelines/minimax_h3/before_encoder.py
@@ -215,10 +215,8 @@ def inputs(self) -> list[InputParam]:
                     "[`MiniMaxH3ImageReference`] (at most 9), a [`MiniMaxH3VideoReference`] at its own `fps` (at most "
                     "3, whose `audio` soundtrack is conditioned on as well), or a [`MiniMaxH3AudioReference`] at its "
                     "own `sample_rate` (at most 3) — for at most 12 references in total, and audio references cannot "
-                    "be the only ones. These blocks never open a media file: decode with "
-                    "[`~modular_pipelines.minimax_h3.decode_reference_video`] and "
-                    "[`~modular_pipelines.minimax_h3.decode_reference_audio`], which bring the rates along, or put a "
-                    "[`MiniMaxH3Ref2VALoadReferencesStep`] in front of these blocks."
+                    "be the only ones. These blocks never open a media file: decode with each class's `from_file` "
+                    "classmethod, which brings the rates along."
                 ),
             ),
             InputParam.template("height", description="Height of the generated video in pixels, a multiple of 32."),
@@ -370,10 +368,7 @@ def __call__(self, components: MiniMaxH3ModularPipeline, state: PipelineState) -
                 raise ValueError(
                     f"`references[{index}]` must be a [`MiniMaxH3ImageReference`], [`MiniMaxH3VideoReference`] or "
                     f"[`MiniMaxH3AudioReference`], got {type(entry)}. MiniMax-H3 blocks never open media files, so a "
-                    "request that holds paths decodes them first — with "
-                    "[`~modular_pipelines.minimax_h3.decode_reference_video`] and "
-                    "[`~modular_pipelines.minimax_h3.decode_reference_audio`], or by putting a "
-                    "[`MiniMaxH3Ref2VALoadReferencesStep`] in front of these blocks."
+                    "request that holds paths decodes them first, with each class's `from_file` classmethod."
                 )
         kinds = [entry.kind for entry in block_state.references]
         for kind, limit in (("image", self.max_images), ("video", self.max_videos), ("audio", self.max_audios)):
diff --git a/src/diffusers/modular_pipelines/minimax_h3/modular_blocks_minimax_h3.py b/src/diffusers/modular_pipelines/minimax_h3/modular_blocks_minimax_h3.py
index ec15f540400a..e6f4d2affd80 100644
--- a/src/diffusers/modular_pipelines/minimax_h3/modular_blocks_minimax_h3.py
+++ b/src/diffusers/modular_pipelines/minimax_h3/modular_blocks_minimax_h3.py
@@ -159,10 +159,8 @@ class MiniMaxH3AutoBeforeEncodeStep(AutoPipelineBlocks):
               dataclass per modality, all holding in-memory media — a [`MiniMaxH3ImageReference`] (at most 9), a
               [`MiniMaxH3VideoReference`] at its own `fps` (at most 3, whose `audio` soundtrack is conditioned on as well), or a
               [`MiniMaxH3AudioReference`] at its own `sample_rate` (at most 3) — for at most 12 references in total, and audio
-              references cannot be the only ones. These blocks never open a media file: decode with
-              [`~modular_pipelines.minimax_h3.decode_reference_video`] and
-              [`~modular_pipelines.minimax_h3.decode_reference_audio`], which bring the rates along, or put a
-              [`MiniMaxH3Ref2VALoadReferencesStep`] in front of these blocks.
+              references cannot be the only ones. These blocks never open a media file: decode with each class's `from_file`
+              classmethod, which brings the rates along.
           height (`int`, *optional*):
               Height of the generated video in pixels, a multiple of 32.
           width (`int`, *optional*):
@@ -694,10 +692,8 @@ class MiniMaxH3Blocks(SequentialPipelineBlocks):
               dataclass per modality, all holding in-memory media — a [`MiniMaxH3ImageReference`] (at most 9), a
               [`MiniMaxH3VideoReference`] at its own `fps` (at most 3, whose `audio` soundtrack is conditioned on as well), or a
               [`MiniMaxH3AudioReference`] at its own `sample_rate` (at most 3) — for at most 12 references in total, and audio
-              references cannot be the only ones. These blocks never open a media file: decode with
-              [`~modular_pipelines.minimax_h3.decode_reference_video`] and
-              [`~modular_pipelines.minimax_h3.decode_reference_audio`], which bring the rates along, or put a
-              [`MiniMaxH3Ref2VALoadReferencesStep`] in front of these blocks.
+              references cannot be the only ones. These blocks never open a media file: decode with each class's `from_file`
+              classmethod, which brings the rates along.
           height (`int`, *optional*):
               Height of the generated video in pixels, a multiple of 32.
           width (`int`, *optional*):
diff --git a/src/diffusers/modular_pipelines/minimax_h3/reference_loading.py b/src/diffusers/modular_pipelines/minimax_h3/reference_loading.py
deleted file mode 100644
index a61de5bc4a6e..000000000000
--- a/src/diffusers/modular_pipelines/minimax_h3/reference_loading.py
+++ /dev/null
@@ -1,272 +0,0 @@
-# Copyright 2026 The MiniMax and HuggingFace Teams. All rights reserved.
-#
-# Licensed under the Apache License, Version 2.0 (the "License");
-# you may not use this file except in compliance with the License.
-# You may obtain a copy of the License at
-#
-#     http://www.apache.org/licenses/LICENSE-2.0
-#
-# Unless required by applicable law or agreed to in writing, software
-# distributed under the License is distributed on an "AS IS" BASIS,
-# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-# See the License for the specific language governing permissions and
-# limitations under the License.
-
-r"""
-Reading `ref2va` references off the filesystem.
-
-MiniMax-H3's blocks take references as in-memory media, and the three reference dataclasses take nothing else: a
-[`MiniMaxH3VideoReference`] carries decoded frames and the `fps` they were decoded at, a [`MiniMaxH3AudioReference`] a
-waveform and its sample rate. Turning a path into one of those is the caller's job, the same way it is for every other
-pipeline in the library.
-
-This module is the convenience for doing it: [`decode_reference_video`] and [`decode_reference_audio`] decode a file
-or a URL along with the rates it carries, and [`MiniMaxH3Ref2VALoadReferencesStep`] wraps them in a block that can be
-put in front of [`MiniMaxH3Blocks`]. It is deliberately *not* one of that blockset's own steps — decoding media
-is not part of generating video, and a request that already holds its media should not pay for the machinery.
-
-The rates are the reason to prefer these over a bare `load_video`: MiniMax-H3 resamples a reference onto its own 24
-fps, so a video whose real rate is lost on the way in is conditioned on at the wrong speed, silently.
-"""
-
-import contextlib
-import os
-import tempfile
-from urllib.parse import unquote, urlparse
-
-import numpy as np
-import requests
-import torch
-
-from ...utils import is_av_available, load_image, logging
-from ...utils.constants import DIFFUSERS_REQUEST_TIMEOUT
-from ..modular_pipeline import ModularPipelineBlocks, PipelineState
-from ..modular_pipeline_utils import InputParam, OutputParam
-from .modular_pipeline import MiniMaxH3ModularPipeline
-from .references import (
-    MiniMaxH3AudioReference,
-    MiniMaxH3ImageReference,
-    MiniMaxH3Reference,
-    MiniMaxH3VideoReference,
-)
-
-
-logger = logging.get_logger(__name__)  # pylint: disable=invalid-name
-
-
-@contextlib.contextmanager
-def _local_media_file(media):
-    r"""The reference media as a local file: a URL is downloaded to a temporary file, removed on the way out."""
-    path = str(media)
-    if not path.startswith(("http://", "https://")):
-        if not os.path.isfile(path):
-            raise ValueError(
-                f"Incorrect path or URL. URLs must start with `http://` or `https://`, and {path} is not a valid path."
-            )
-        yield path
-        return
-
-    response = requests.get(path, stream=True, timeout=DIFFUSERS_REQUEST_TIMEOUT)
-    if response.status_code != 200:
-        raise ValueError(f"Failed to download {path}. Status code: {response.status_code}")
-    suffix = os.path.splitext(os.path.basename(unquote(urlparse(path).path)))[1]
-    download = tempfile.NamedTemporaryFile(suffix=suffix, delete=False)
-    try:
-        with download as file:
-            for chunk in response.iter_content(chunk_size=8192):
-                file.write(chunk)
-        yield download.name
-    finally:
-        os.remove(download.name)
-
-
-def _import_av():
-    r"""PyAV, the soft dependency a media file is decoded with."""
-    if not is_av_available():
-        raise ImportError(
-            "Decoding a MiniMax-H3 reference from a file needs PyAV. You can install it with `pip install av`, or "
-            "build the reference from decoded media itself: frames and the `fps` they carry for a video, a "
-            "`(channels, num_samples)` waveform and its `sample_rate` for audio."
-        )
-
-    import av
-
-    return av
-
-
-def _decode_reference_soundtrack(av, container, stream) -> tuple[torch.Tensor, int]:
-    r"""
-    An audio stream's samples as a `(channels, num_samples)` float32 waveform, at the rate the container carries them.
-
-    Args:
-        av (`module`): PyAV.
-        container (`av.container.InputContainer`): The open container.
-        stream (`av.audio.stream.AudioStream`): The stream to decode.
-
-    Returns:
-        `tuple[torch.Tensor, int]`: the waveform and its sample rate.
-    """
-    sample_rate = int(stream.codec_context.sample_rate)
-    # Planar float is a format conversion only: the sample rate and the channel layout stay the container's own, and a
-    # mono soundtrack is upmixed later, by `prepare_reference_waveform`.
-    resampler = av.audio.resampler.AudioResampler(format="fltp", layout=stream.layout, rate=sample_rate)
-    chunks = []
-    for frame in container.decode(stream):
-        chunks += [torch.from_numpy(resampled.to_ndarray()) for resampled in resampler.resample(frame)]
-    # Whatever the resampler is still holding.
-    chunks += [torch.from_numpy(resampled.to_ndarray()) for resampled in resampler.resample(None)]
-    return torch.cat(chunks, dim=-1).to(torch.float32), sample_rate
-
-
-def decode_reference_video(media) -> MiniMaxH3VideoReference:
-    r"""
-    Decode a video file into a [`MiniMaxH3VideoReference`], at the resolution, the frame rate and the soundtrack it
-    carries.
-
-    The rates land on the reference, which is the point of decoding this way rather than with [`~utils.load_video`]:
-    MiniMax-H3 resamples a reference onto its own 24 fps, so a frame rate lost on the way in is a request conditioned
-    at the wrong speed, with nothing to raise about it. A container whose metadata is wrong is corrected by overriding
-    `fps` or `sample_rate` on the returned reference.
-
-    Needs [PyAV](https://github.com/PyAV-Org/PyAV).
-
-    Args:
-        media (`str` or `os.PathLike`): Path or URL of the video.
-
-    Returns:
-        [`MiniMaxH3VideoReference`]: the `(num_frames, height, width, 3)` `uint8` frames at the frame rate the
-        container reports, carrying its soundtrack and that soundtrack's own sample rate when it has an audio stream.
-    """
-    av = _import_av()
-    with _local_media_file(media) as path, av.open(path) as container:
-        stream = container.streams.video[0]
-        frames, rotation = [], 0.0
-        for frame in container.decode(stream):
-            # The display matrix rotation belongs to the stream, and PyAV surfaces it on every frame of it.
-            rotation = frame.rotation
-            frames.append(frame.to_ndarray(format="rgb24"))
-        frame_rate = float(stream.average_rate or stream.guessed_rate)
-        soundtrack = None
-        if container.streams.audio:
-            # Decoding the frames drained the container, so the soundtrack is read in a second pass over it.
-            container.seek(0)
-            soundtrack = _decode_reference_soundtrack(av, container, container.streams.audio[0])
-
-    if not frames:
-        raise ValueError(f"No video frames to decode in {media}.")
-    frames = np.stack(frames)
-    # `ffmpeg` displays a frame upright by undoing the counterclockwise rotation the display matrix carries, which is
-    # what this reproduces, snapped to the nearest quarter turn. A non-square pixel aspect ratio is left alone: the
-    # reference implementation resolved a reference's canvas from its *display* geometry, so a stream that carries a
-    # sample aspect ratio is conditioned on at the wrong shape, and correcting it is untested guesswork here.
-    turns = round(rotation / 90.0) % 4
-    if turns:
-        frames = np.ascontiguousarray(np.rot90(frames, k=-turns, axes=(1, 2)))
-    waveform, sample_rate = soundtrack if soundtrack is not None else (None, None)
-    return MiniMaxH3VideoReference(frames=frames, fps=frame_rate, audio=waveform, sample_rate=sample_rate)
-
-
-def decode_reference_audio(media) -> MiniMaxH3AudioReference:
-    r"""
-    Decode an audio file into a [`MiniMaxH3AudioReference`], at the sample rate it carries.
-
-    Needs [PyAV](https://github.com/PyAV-Org/PyAV).
-
-    Args:
-        media (`str` or `os.PathLike`): Path or URL of the audio, or of a video whose soundtrack is taken.
-
-    Returns:
-        [`MiniMaxH3AudioReference`]: the `(channels, num_samples)` float32 waveform at the sample rate the container
-        reports.
-    """
-    av = _import_av()
-    with _local_media_file(media) as path, av.open(path) as container:
-        if not container.streams.audio:
-            raise ValueError(f"No audio stream to decode in {media}.")
-        waveform, sample_rate = _decode_reference_soundtrack(av, container, container.streams.audio[0])
-    return MiniMaxH3AudioReference(audio=waveform, sample_rate=sample_rate)
-
-
-class MiniMaxH3Ref2VALoadReferencesStep(ModularPipelineBlocks):
-    r"""
-    Reads `ref2va` references off the filesystem, so that a request can name its media instead of decoding it.
-
-    Not one of [`MiniMaxH3Blocks`]' own steps — put it in front of them when the request holds paths:
-
-    ```py
-    >>> from diffusers.modular_pipelines import SequentialPipelineBlocks
-    >>> from diffusers.modular_pipelines.minimax_h3 import (
-    ...     MiniMaxH3Blocks,
-    ...     MiniMaxH3Ref2VALoadReferencesStep,
-    ... )
-
-    >>> blocks = SequentialPipelineBlocks.from_blocks_dict(
-    ...     {"load_references": MiniMaxH3Ref2VALoadReferencesStep(), "generate": MiniMaxH3Blocks()}
-    ... )
-    >>> pipe = blocks.init_pipeline("MiniMaxAI/MiniMax-H3-Ref2VA-Diffusers")
-    >>> output = pipe(
-    ...     prompt="the subject walks through the frame",
-    ...     reference_media=[{"image": "subject.png"}, {"video": "motion_ref.mp4"}, {"audio": "voice.wav"}],
-    ... )
-    ```
-    """
-
-    model_name = "minimax-h3"
-
-    @property
-    def description(self) -> str:
-        return (
-            "Decodes `ref2va` references from paths or URLs, along with the rates they carry — a video's frame rate "
-            "and its soundtrack, an audio clip's sample rate. A convenience in front of the `ref2va` blocks, which "
-            "themselves only ever see in-memory media."
-        )
-
-    @property
-    def inputs(self) -> list[InputParam]:
-        return [
-            InputParam(
-                name="reference_media",
-                type_hint=list[dict],
-                required=True,
-                description=(
-                    "The media to condition on, **in the order the model should read them**, one `{medium: path}` "
-                    "mapping each: `{'image': ...}`, `{'video': ...}` or `{'audio': ...}`, where the value is a path "
-                    "or a URL. The medium is named rather than guessed from the file. A video brings its soundtrack "
-                    "along, so conditioning on a file's motion alone means building a "
-                    "[`MiniMaxH3VideoReference`] without one."
-                ),
-            ),
-        ]
-
-    @property
-    def intermediate_outputs(self) -> list[OutputParam]:
-        return [
-            OutputParam(
-                "references",
-                type_hint=list[MiniMaxH3Reference],
-                description="The decoded references, in packed order, carrying the rates their containers report.",
-            ),
-        ]
-
-    @torch.no_grad()
-    def __call__(self, components: MiniMaxH3ModularPipeline, state: PipelineState) -> PipelineState:
-        block_state = self.get_block_state(state)
-
-        references = []
-        for index, entry in enumerate(block_state.reference_media):
-            if not isinstance(entry, dict) or len(entry) != 1 or next(iter(entry)) not in ("image", "video", "audio"):
-                raise ValueError(
-                    f"`reference_media[{index}]` must name exactly one medium, as `{{'image': path}}`, "
-                    f"`{{'video': path}}` or `{{'audio': path}}`, got {entry}."
-                )
-            [(medium, media)] = entry.items()
-            if medium == "image":
-                references.append(MiniMaxH3ImageReference(image=load_image(str(media))))
-            elif medium == "video":
-                references.append(decode_reference_video(media))
-            else:
-                references.append(decode_reference_audio(media))
-        block_state.references = references
-
-        self.set_block_state(state, block_state)
-        return components, state
diff --git a/src/diffusers/modular_pipelines/minimax_h3/references.py b/src/diffusers/modular_pipelines/minimax_h3/references.py
index 970ac82d0762..2b0ab4a057a7 100644
--- a/src/diffusers/modular_pipelines/minimax_h3/references.py
+++ b/src/diffusers/modular_pipelines/minimax_h3/references.py
@@ -21,16 +21,24 @@
 audio/video rotary clock, so a different order is a different request.
 
 Every reference holds in-memory media plus the rate that media carries. No block of this model opens a media file;
-decoding a path is the caller's job, and [`~modular_pipelines.minimax_h3.reference_loading`] is the convenience for
-doing it.
+each class decodes a path or a URL through its `from_file` classmethod, which brings the rates along. That is the
+reason to prefer `from_file` over a bare `load_video`: MiniMax-H3 resamples a reference onto its own 24 fps, so a
+video whose real rate is lost on the way in is conditioned on at the wrong speed, silently.
 """
 
+import contextlib
+import os
+import tempfile
 from dataclasses import dataclass
+from urllib.parse import unquote, urlparse
 
 import numpy as np
+import requests
 import torch
 from PIL import Image
 
+from ...utils import is_av_available, load_image
+from ...utils.constants import DIFFUSERS_REQUEST_TIMEOUT
 from .modular_pipeline import MINIMAX_H3_FPS
 
 
@@ -46,26 +54,21 @@ class MiniMaxH3Reference:
 
     Every reference holds in-memory media, and the rate that media carries where there is one — MiniMax-H3 resamples a
     reference onto its own 24 fps and onto the audio VAE's sample rate, so a rate lost on the way in is a request
-    conditioned at the wrong speed. Decoding a file is the caller's job:
-    [`~modular_pipelines.minimax_h3.decode_reference_video`] and
-    [`~modular_pipelines.minimax_h3.decode_reference_audio`] do it along with the rates, and
-    [`MiniMaxH3Ref2VALoadReferencesStep`] wraps them in a block.
+    conditioned at the wrong speed. Each class decodes a file through its `from_file` classmethod, along with the
+    rates.
 
     ```py
     >>> import numpy as np
-    >>> from diffusers.utils import load_image
     >>> from diffusers.modular_pipelines.minimax_h3 import (
     ...     MiniMaxH3AudioReference,
     ...     MiniMaxH3ImageReference,
     ...     MiniMaxH3VideoReference,
-    ...     decode_reference_audio,
-    ...     decode_reference_video,
     ... )
 
     >>> references = [
-    ...     MiniMaxH3ImageReference(image=load_image("subject.png")),
-    ...     decode_reference_video("motion_ref.mp4"),  # frames, their `fps`, and the soundtrack
-    ...     decode_reference_audio("voice.wav"),  # waveform and its `sample_rate`
+    ...     MiniMaxH3ImageReference.from_file("subject.png"),
+    ...     MiniMaxH3VideoReference.from_file("motion_ref.mp4"),  # frames, their `fps`, and the soundtrack
+    ...     MiniMaxH3AudioReference.from_file("voice.wav"),  # waveform and its `sample_rate`
     ... ]
 
     >>> # Media a request produced itself declares the rate it was produced at.
@@ -91,6 +94,16 @@ class MiniMaxH3ImageReference(MiniMaxH3Reference):
     kind = "image"
     has_audio = False
 
+    @classmethod
+    def from_file(cls, media) -> "MiniMaxH3ImageReference":
+        r"""
+        Load an image file into a [`MiniMaxH3ImageReference`], through [`~utils.load_image`].
+
+        Args:
+            media (`str` or `os.PathLike`): Path or URL of the image.
+        """
+        return cls(image=load_image(str(media)))
+
 
 @dataclass
 class MiniMaxH3VideoReference(MiniMaxH3Reference):
@@ -129,6 +142,30 @@ def has_audio(self) -> bool:
         r"""Whether this reference contributes audio rows, i.e. whether it carries a soundtrack."""
         return self.audio is not None
 
+    @classmethod
+    def from_file(cls, media) -> "MiniMaxH3VideoReference":
+        r"""
+        Decode a video file into a [`MiniMaxH3VideoReference`], at the resolution, the frame rate and the soundtrack
+        it carries.
+
+        The rates land on the reference, which is the point of decoding this way rather than with
+        [`~utils.load_video`]: MiniMax-H3 resamples a reference onto its own 24 fps, so a frame rate lost on the way
+        in is a request conditioned at the wrong speed, with nothing to raise about it. A container whose metadata is
+        wrong is corrected by overriding `fps` or `sample_rate` on the returned reference.
+
+        Needs [PyAV](https://github.com/PyAV-Org/PyAV).
+
+        Args:
+            media (`str` or `os.PathLike`): Path or URL of the video.
+
+        Returns:
+            [`MiniMaxH3VideoReference`]: the `(num_frames, height, width, 3)` `uint8` frames at the frame rate the
+            container reports, carrying its soundtrack and that soundtrack's own sample rate when it has an audio
+            stream.
+        """
+        frames, fps, audio, sample_rate = _decode_video_file(media)
+        return cls(frames=frames, fps=fps, audio=audio, sample_rate=sample_rate)
+
 
 @dataclass
 class MiniMaxH3AudioReference(MiniMaxH3Reference):
@@ -149,3 +186,132 @@ class MiniMaxH3AudioReference(MiniMaxH3Reference):
 
     kind = "audio"
     has_audio = True
+
+    @classmethod
+    def from_file(cls, media) -> "MiniMaxH3AudioReference":
+        r"""
+        Decode an audio file into a [`MiniMaxH3AudioReference`], at the sample rate it carries.
+
+        Needs [PyAV](https://github.com/PyAV-Org/PyAV).
+
+        Args:
+            media (`str` or `os.PathLike`): Path or URL of the audio, or of a video whose soundtrack is taken.
+
+        Returns:
+            [`MiniMaxH3AudioReference`]: the `(channels, num_samples)` float32 waveform at the sample rate the
+            container reports.
+        """
+        audio, sample_rate = _decode_audio_file(media)
+        return cls(audio=audio, sample_rate=sample_rate)
+
+
+@contextlib.contextmanager
+def _local_media_file(media):
+    r"""The reference media as a local file: a URL is downloaded to a temporary file, removed on the way out."""
+    path = str(media)
+    if not path.startswith(("http://", "https://")):
+        if not os.path.isfile(path):
+            raise ValueError(
+                f"Incorrect path or URL. URLs must start with `http://` or `https://`, and {path} is not a valid path."
+            )
+        yield path
+        return
+
+    response = requests.get(path, stream=True, timeout=DIFFUSERS_REQUEST_TIMEOUT)
+    if response.status_code != 200:
+        raise ValueError(f"Failed to download {path}. Status code: {response.status_code}")
+    suffix = os.path.splitext(os.path.basename(unquote(urlparse(path).path)))[1]
+    download = tempfile.NamedTemporaryFile(suffix=suffix, delete=False)
+    try:
+        with download as file:
+            for chunk in response.iter_content(chunk_size=8192):
+                file.write(chunk)
+        yield download.name
+    finally:
+        os.remove(download.name)
+
+
+def _import_av():
+    r"""PyAV, the soft dependency a media file is decoded with."""
+    if not is_av_available():
+        raise ImportError(
+            "Decoding a MiniMax-H3 reference from a file needs PyAV. You can install it with `pip install av`, or "
+            "build the reference from decoded media itself: frames and the `fps` they carry for a video, a "
+            "`(channels, num_samples)` waveform and its `sample_rate` for audio."
+        )
+
+    import av
+
+    return av
+
+
+def _decode_reference_soundtrack(av, container, stream) -> tuple[torch.Tensor, int]:
+    r"""
+    An audio stream's samples as a `(channels, num_samples)` float32 waveform, at the rate the container carries them.
+
+    Args:
+        av (`module`): PyAV.
+        container (`av.container.InputContainer`): The open container.
+        stream (`av.audio.stream.AudioStream`): The stream to decode.
+
+    Returns:
+        `tuple[torch.Tensor, int]`: the waveform and its sample rate.
+    """
+    sample_rate = int(stream.codec_context.sample_rate)
+    # Planar float is a format conversion only: the sample rate and the channel layout stay the container's own, and a
+    # mono soundtrack is upmixed later, by the setup step's audio normalization.
+    resampler = av.audio.resampler.AudioResampler(format="fltp", layout=stream.layout, rate=sample_rate)
+    chunks = []
+    for frame in container.decode(stream):
+        chunks += [torch.from_numpy(resampled.to_ndarray()) for resampled in resampler.resample(frame)]
+    # Whatever the resampler is still holding.
+    chunks += [torch.from_numpy(resampled.to_ndarray()) for resampled in resampler.resample(None)]
+    return torch.cat(chunks, dim=-1).to(torch.float32), sample_rate
+
+
+def _decode_video_file(media) -> tuple[np.ndarray, float, torch.Tensor | None, int | None]:
+    r"""
+    A video file's frames as `(num_frames, height, width, 3)` `uint8`, the frame rate the container reports, and its
+    soundtrack with that soundtrack's sample rate (`None, None` without an audio stream). The machinery behind
+    [`MiniMaxH3VideoReference.from_file`].
+    """
+    av = _import_av()
+    with _local_media_file(media) as path, av.open(path) as container:
+        stream = container.streams.video[0]
+        frames, rotation = [], 0.0
+        for frame in container.decode(stream):
+            # The display matrix rotation belongs to the stream, and PyAV surfaces it on every frame of it.
+            rotation = frame.rotation
+            frames.append(frame.to_ndarray(format="rgb24"))
+        frame_rate = float(stream.average_rate or stream.guessed_rate)
+        soundtrack = None
+        if container.streams.audio:
+            # Decoding the frames drained the container, so the soundtrack is read in a second pass over it.
+            container.seek(0)
+            soundtrack = _decode_reference_soundtrack(av, container, container.streams.audio[0])
+
+    if not frames:
+        raise ValueError(f"No video frames to decode in {media}.")
+    frames = np.stack(frames)
+    # `ffmpeg` displays a frame upright by undoing the counterclockwise rotation the display matrix carries, which is
+    # what this reproduces, snapped to the nearest quarter turn. A non-square pixel aspect ratio is left alone: the
+    # reference implementation resolved a reference's canvas from its *display* geometry, so a stream that carries a
+    # sample aspect ratio is conditioned on at the wrong shape, and correcting it is untested guesswork here.
+    turns = round(rotation / 90.0) % 4
+    if turns:
+        frames = np.ascontiguousarray(np.rot90(frames, k=-turns, axes=(1, 2)))
+    waveform, sample_rate = soundtrack if soundtrack is not None else (None, None)
+    return frames, frame_rate, waveform, sample_rate
+
+
+def _decode_audio_file(media) -> tuple[torch.Tensor, int]:
+    r"""
+    An audio file's `(channels, num_samples)` float32 waveform, at the sample rate the container reports. The
+    machinery behind [`MiniMaxH3AudioReference.from_file`].
+    """
+    av = _import_av()
+    with _local_media_file(media) as path, av.open(path) as container:
+        if not container.streams.audio:
+            raise ValueError(f"No audio stream to decode in {media}.")
+        waveform, sample_rate = _decode_reference_soundtrack(av, container, container.streams.audio[0])
+    return waveform, sample_rate
diff --git a/tests/modular_pipelines/minimax_h3/test_modular_pipeline_minimax_h3.py b/tests/modular_pipelines/minimax_h3/test_modular_pipeline_minimax_h3.py
index c0ff99ba9e05..eccc50a30a76 100644
--- a/tests/modular_pipelines/minimax_h3/test_modular_pipeline_minimax_h3.py
+++ b/tests/modular_pipelines/minimax_h3/test_modular_pipeline_minimax_h3.py
@@ -24,13 +24,12 @@
 from diffusers.modular_pipelines.minimax_h3 import (
     MiniMaxH3AudioReference,
     MiniMaxH3ImageReference,
-    MiniMaxH3Ref2VALoadReferencesStep,
     MiniMaxH3VideoReference,
-    decode_reference_audio,
-    decode_reference_video,
-    reference_loading,
 )
 from diffusers.modular_pipelines.minimax_h3 import modular_pipeline as minimax_h3_geometry
+from diffusers.modular_pipelines.minimax_h3 import (
+    references as minimax_h3_references,
+)
 from diffusers.modular_pipelines.minimax_h3.before_encoder import MiniMaxH3Ref2VASetupStep
 from diffusers.modular_pipelines.minimax_h3.encoders import MiniMaxH3Ref2VATextEncoderStep, MiniMaxH3TextEncoderStep
 from diffusers.modular_pipelines.minimax_h3.modular_pipeline import MINIMAX_H3_FPS
@@ -757,9 +756,8 @@ class TestMiniMaxH3ReferenceLoading:
     """
     Decoding references off the filesystem, which is the caller's job rather than the blocks'.
 
-    None of this needs a checkpoint: [`decode_reference_video`] and [`decode_reference_audio`] read a container with
-    PyAV and return a reference carrying the rates it reports, and [`MiniMaxH3Ref2VALoadReferencesStep`] is the block
-    that does the same for a whole ordered request.
+    None of this needs a checkpoint: [`MiniMaxH3VideoReference.from_file`] and [`MiniMaxH3AudioReference.from_file`]
+    read a container with PyAV and return a reference carrying the rates it reports.
     """
 
     def test_decode_video_carries_frames_rate_and_soundtrack(self, tmp_path):
@@ -769,7 +767,7 @@ def test_decode_video_carries_frames_rate_and_soundtrack(self, tmp_path):
         """
         video_path, _, _ = _media_fixtures(tmp_path)
 
-        video = decode_reference_video(video_path)
+        video = MiniMaxH3VideoReference.from_file(video_path)
 
         assert isinstance(video, MiniMaxH3VideoReference) and video.kind == "video"
         assert video.frames.shape == (FIXTURE_NUM_FRAMES, 32, 64, 3) and video.frames.dtype == np.uint8
@@ -780,7 +778,7 @@ def test_decode_audio_carries_the_sample_rate(self, tmp_path):
         r"""A decoded audio file brings the rate its samples are at, which is what they are resampled from."""
         _, _, audio_path = _media_fixtures(tmp_path)
 
-        audio = decode_reference_audio(audio_path)
+        audio = MiniMaxH3AudioReference.from_file(audio_path)
 
         assert isinstance(audio, MiniMaxH3AudioReference) and audio.kind == "audio"
         assert audio.audio.shape[0] == 2 and audio.audio.dtype == torch.float32
@@ -790,7 +788,7 @@ def test_decoded_rates_can_be_corrected(self, tmp_path):
         r"""A container whose metadata is wrong is corrected on the reference the decode returned."""
         video_path, _, _ = _media_fixtures(tmp_path)
 
-        video = decode_reference_video(video_path)
+        video = MiniMaxH3VideoReference.from_file(video_path)
         video.fps = 12.0
 
         assert video.fps == 12.0 and video.sample_rate == FIXTURE_SAMPLE_RATE
@@ -800,7 +798,7 @@ def test_decode_silent_video_carries_no_soundtrack(self, tmp_path):
         silent_path = tmp_path / "silent.mp4"
         _write_video(silent_path, with_audio=False)
 
-        reference = decode_reference_video(silent_path)
+        reference = MiniMaxH3VideoReference.from_file(silent_path)
 
         assert not reference.has_audio and reference.sample_rate is None
         assert reference.fps == FIXTURE_FPS
@@ -808,52 +806,26 @@ def test_decode_silent_video_carries_no_soundtrack(self, tmp_path):
     def test_decoding_needs_pyav(self, tmp_path, monkeypatch):
         r"""Decoding a video or an audio file is a PyAV job, and says so when PyAV is not installed."""
         video_path, _, audio_path = _media_fixtures(tmp_path)
-        monkeypatch.setattr(reference_loading, "is_av_available", lambda: False)
+        monkeypatch.setattr(minimax_h3_references, "is_av_available", lambda: False)
 
         with pytest.raises(ImportError, match="pip install av"):
-            decode_reference_video(video_path)
+            MiniMaxH3VideoReference.from_file(video_path)
         with pytest.raises(ImportError, match="pip install av"):
-            decode_reference_audio(audio_path)
-
-    def test_load_references_block_decodes_a_request_in_order(self, tmp_path):
-        r"""
-        The block turns an ordered list of named media into the references the `ref2va` blocks take.
-
-        Order is preserved because it is semantic: it labels the references in the prompt presentation and lays them
-        out on the shared rotary clock.
-        """
-        video_path, image_path, audio_path = _media_fixtures(tmp_path)
-        pipe = MiniMaxH3Ref2VALoadReferencesStep().init_pipeline()
-
-        references = pipe(
-            reference_media=[{"image": image_path}, {"video": video_path}, {"audio": audio_path}],
-            output="references",
-        )
-
-        assert [reference.kind for reference in references] == ["image", "video", "audio"]
-        assert references[0].image.size == (64, 32)
-        assert references[1].fps == FIXTURE_FPS and references[1].sample_rate == FIXTURE_SAMPLE_RATE
-        assert references[2].sample_rate == FIXTURE_SAMPLE_RATE
+            MiniMaxH3AudioReference.from_file(audio_path)
 
     @pytest.mark.parametrize(
-        "entry,message",
+        "loader,path",
         [
-            ({}, "must name exactly one medium"),
-            ({"image": "a.png", "video": "b.mp4"}, "must name exactly one medium"),
-            ({"picture": "a.png"}, "must name exactly one medium"),
-            ("a.png", "must name exactly one medium"),
-            ({"image": "missing.png"}, "not a valid path"),
-            ({"video": "missing.mp4"}, "not a valid path"),
-            ({"audio": "missing.wav"}, "not a valid path"),
+            (MiniMaxH3ImageReference.from_file, "missing.png"),
+            (MiniMaxH3VideoReference.from_file, "missing.mp4"),
+            (MiniMaxH3AudioReference.from_file, "missing.wav"),
         ],
-        ids=["empty", "two_media", "unknown_medium", "bare_path", "missing_image", "missing_video", "missing_audio"],
+        ids=["image", "video", "audio"],
     )
-    def test_load_references_block_rejects(self, entry, message):
-        r"""The medium is named rather than guessed from the file, and the path has to name a file it can open."""
-        pipe = MiniMaxH3Ref2VALoadReferencesStep().init_pipeline()
-
-        with pytest.raises(ValueError, match=message):
-            pipe(reference_media=[entry])
+    def test_from_file_needs_a_real_path(self, loader, path):
+        r"""The path has to name a file it can open, or a URL."""
+        with pytest.raises(ValueError, match="not a valid path"):
+            loader(path)
 
 
 class TestMiniMaxH3ReferenceGeometry:

From 1d7a514f73ce6317b930058d869b20353814ae66 Mon Sep 17 00:00:00 2001
From: yiyixuxu <yixu310@gmail.com>
Date: Tue, 4 Aug 2026 04:04:38 +0000
Subject: [PATCH 11/16] Let a tester spell out what every workflow expects
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

`test_workflow_defaults` joins the modular tester mixin: a test class lists,
per workflow, the exact component set (with any config fields worth pinning)
and the exact input set with each default — requiredness spelled with a
`REQUIRED` sentinel, since a required input and an optional one both read
`default=None` off the param. Both sides are exact-set equality, so a
component or an input appearing in or disappearing from a workflow fails
loudly instead of drifting silently. Testers that set no expectations skip.

The modular guide gains the `workflow=` argument in both places it lives:
`from_pretrained(workflow=...)` prunes the blocks to one workflow so the
pipeline documents and declares exactly that task, and
`load_components(workflow=...)` restricts loading on a full pipeline — the
convenient form for running one pipeline across workflows, each call adding
only what the new workflow still misses.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 .../en/modular_diffusers/modular_pipeline.md  | 12 +++++
 .../test_modular_pipelines_common.py          | 50 +++++++++++++++++++
 2 files changed, 62 insertions(+)

diff --git a/docs/source/en/modular_diffusers/modular_pipeline.md b/docs/source/en/modular_diffusers/modular_pipeline.md
index caa3b2e5a361..68177c7e7fb8 100644
--- a/docs/source/en/modular_diffusers/modular_pipeline.md
+++ b/docs/source/en/modular_diffusers/modular_pipeline.md
@@ -234,6 +234,12 @@ pipeline = ModularPipeline.from_pretrained(
 )
 ```
 
+When the pipeline blocks define workflows (check `pipeline.blocks.available_workflows`), pass `workflow=` to keep only that workflow's blocks — the same pruning as [`~ModularPipelineBlocks.get_workflow`]. The pipeline then only declares the components that workflow uses, and its docstring describes exactly that workflow's inputs.
+
+```py
+pipeline = ModularPipeline.from_pretrained("Qwen/Qwen-Image", workflow="inpainting")
+```
+
 ## Loading components
 
 A [`ModularPipeline`] doesn't automatically instantiate with components. It only loads the configuration and component specifications. You can load components with [`~ModularPipeline.load_components`].
@@ -252,6 +258,12 @@ You can also load specific components by name. The example below only loads the
 pipeline.load_components(names=["text_encoder"], dtype=torch.float16)
 ```
 
+On a pipeline whose blocks define workflows, `workflow=` loads only the components that workflow uses. The pipeline keeps all its blocks, so this is the convenient way to run one pipeline across workflows: each call adds just what the new workflow still misses.
+
+```py
+pipeline.load_components(workflow="inpainting", dtype=torch.float16)
+```
+
 After loading, printing the pipeline shows which components are loaded — the first two fields change from `null` to the component's library and class.
 
 ```py
diff --git a/tests/modular_pipelines/test_modular_pipelines_common.py b/tests/modular_pipelines/test_modular_pipelines_common.py
index 073eb70fa2fe..3cc0d2e5b7d7 100644
--- a/tests/modular_pipelines/test_modular_pipelines_common.py
+++ b/tests/modular_pipelines/test_modular_pipelines_common.py
@@ -54,6 +54,16 @@ def _get_specified_components(path_or_repo_id, cache_dir=None):
     return components
 
 
+class _RequiredInput:
+    """Sentinel for `expected_workflow_defaults`: the input has no default and must be passed."""
+
+    def __repr__(self):
+        return "REQUIRED"
+
+
+REQUIRED = _RequiredInput()
+
+
 class ModularPipelineTesterMixin:
     """
     It provides a set of common tests for each modular pipeline,
@@ -505,6 +515,46 @@ def test_workflow_map(self):
                     f"{actual_block.__class__.__name__}, expected {expected_class_name}"
                 )
 
+    def test_workflow_defaults(self):
+        if not getattr(self, "expected_workflow_defaults", None):
+            pytest.skip("Skipping test as expected_workflow_defaults is not set")
+
+        blocks = self.pipeline_blocks_class()
+        for workflow_name, expected_defaults in self.expected_workflow_defaults.items():
+            workflow_blocks = blocks.get_workflow(workflow_name)
+
+            # every component of the workflow is named, so one appearing or disappearing fails loudly
+            component_specs = {spec.name: spec for spec in workflow_blocks.expected_components}
+            expected_components = expected_defaults["components"]
+            assert set(component_specs) == set(expected_components), (
+                f"Workflow '{workflow_name}' expects components {sorted(component_specs)}, "
+                f"the test expects {sorted(expected_components)}"
+            )
+            for component_name, expected_config in expected_components.items():
+                config = component_specs[component_name].config or {}
+                for field, expected_value in expected_config.items():
+                    assert config.get(field) == expected_value, (
+                        f"Workflow '{workflow_name}': component '{component_name}' config '{field}' is "
+                        f"{config.get(field)}, expected {expected_value}"
+                    )
+
+            # kwargs-style inputs (e.g. **denoiser_input_fields) have no name and no default to pin
+            input_params = {param.name: param for param in workflow_blocks.inputs if param.name is not None}
+            expected_inputs = expected_defaults["inputs"]
+            assert set(input_params) == set(expected_inputs), (
+                f"Workflow '{workflow_name}' takes inputs {sorted(input_params)}, "
+                f"the test expects {sorted(expected_inputs)}"
+            )
+            for input_name, expected_default in expected_inputs.items():
+                param = input_params[input_name]
+                if expected_default is REQUIRED:
+                    assert param.required, f"Workflow '{workflow_name}': input '{input_name}' should be required"
+                else:
+                    assert not param.required and param.default == expected_default, (
+                        f"Workflow '{workflow_name}': input '{input_name}' default is "
+                        f"{param.default!r} (required={param.required}), expected {expected_default!r}"
+                    )
+
     def test_from_pretrained_workflow(self):
         blocks = self.pipeline_blocks_class()
         if blocks._workflow_map is None:

From df56f8235f55cc4b4fc4b6c5c37efd12a398947d Mon Sep 17 00:00:00 2001
From: yiyixuxu <yixu310@gmail.com>
Date: Tue, 4 Aug 2026 04:04:38 +0000
Subject: [PATCH 12/16] Give each MiniMax-H3 workflow its own text encoder
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

One text encoder served both t2va and fl2va, so the pruned t2va signature
carried a `keyframes` input that is no business of a text-only request. It
splits: `MiniMaxH3TextEncoderStep` presents the prompt alone,
`MiniMaxH3FL2VATextEncoderStep` takes over the keyframe-aware presentation
unchanged, and ref2va's already was its own. The selector routes
`references` / either keyframe / default across the three.

The nested self-skipping conditionals around the resize and keyframe-VAE
steps flatten into their parents: one conditional each, `references` to the
ref2va step, either keyframe to the keyframe step, skipped for text-only.
Beyond deleting two wrapper classes, the flat form closes a real hole: the
input accounting counts a defaulted branch's outputs as always produced
without looking inside a nested skippable conditional, while a skipped
conditional writes nothing — so the full blockset hid `keyframe_anchors`,
never seeded it, and a full-blockset t2va run reached the layout step with
None and died on `len(None)`. Flat and skippable, those names surface as
optional inputs of the full blockset and are seeded with their declared
defaults; no block needs to defend against the gap.

`fl2va_last_frame` merges into `fl2va` — same pruned route, and the resize
step handles first, last or both keyframes at runtime. The after-denoise
step folds into the two core denoise steps, which now declare `outputs` as
what the decoders actually consume: the generated video and audio latents,
not the union of every intermediate. `_generation_outputs()` is inlined at
its two call sites.

Docs follow: the single-task `from_pretrained(workflow=...)` example leads,
the `load_components(workflow=...)` switching example follows, loading
everything under a ComponentsManager is documented as the deliberate third
way, examples fetch exactly what they need with `output=` instead of the
whole state, a reference is documented as built two ways (`from_file` or
in memory), and guidance distillation is stated for both partitions.

The executed sequences are unchanged apart from provably dead branches
(t2va's text encoder loses two never-taken `if keyframes:` blocks); the
parity sweep re-run is pending.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 docs/source/en/api/pipelines/minimax_h3.md    |  73 ++--
 .../modular_pipelines/minimax_h3/encoders.py  |  76 +++-
 .../minimax_h3/modular_blocks_minimax_h3.py   | 398 ++++++------------
 .../test_modular_pipeline_minimax_h3.py       |  67 ++-
 4 files changed, 315 insertions(+), 299 deletions(-)

diff --git a/docs/source/en/api/pipelines/minimax_h3.md b/docs/source/en/api/pipelines/minimax_h3.md
index 8bf1a3060dfa..d2440fa09680 100644
--- a/docs/source/en/api/pipelines/minimax_h3.md
+++ b/docs/source/en/api/pipelines/minimax_h3.md
@@ -29,35 +29,39 @@ MiniMax-H3 was released as two checkpoint partitions that share every component
 
 | Subfolder | Workflows |
 |---|---|
-| `transformer/` | `t2va` (text only), `fl2va` and `fl2va_last_frame` (first and/or last keyframe) |
+| `transformer/` | `t2va` (text only), `fl2va` (first and/or last keyframe) |
 | `transformer_ref/` | `ref2va` (an ordered mix of image, video and audio references) |
 
 Everything but the transformer, i.e. the video VAE, the audio VAE, the Qwen3-VL conditioner, its tokenizer and processor, and the two schedulers, is shared and stored once.
 
-All four tasks are workflows of the one [`MiniMaxH3Blocks`], and the repository carries one `modular_model_index.json` naming every component with its own loading spec. Selecting a workflow prunes the blocks to that task's own, and `load_components` then fetches exactly the subfolders they declare: a `t2va` / `fl2va` request never touches `transformer_ref/`, a `ref2va` request never touches `transformer/`.
+All three tasks are workflows of the one [`MiniMaxH3Blocks`], and the repository carries one `modular_model_index.json` naming every component with its own loading spec. To serve a single task, pass the workflow to `from_pretrained`: it keeps only that workflow's blocks, so the pipeline's signature (`pipe.blocks.doc`) documents exactly that task's inputs, only that task's components are declared, and `load_components` fetches exactly their subfolders — a `t2va` / `fl2va` pipeline never touches `transformer_ref/`, a `ref2va` one never touches `transformer/`.
 
 ```py
 import torch
 from diffusers import ModularPipeline
 
-# `t2va` / `fl2va`: loads `transformer/`, and never `transformer_ref/`.
-pipe = ModularPipeline.from_pretrained("MiniMaxAI/MiniMax-H3", workflow="t2va")
-
-# `ref2va`: loads `transformer_ref/`, and never `transformer/`, out of the same repository.
 pipe = ModularPipeline.from_pretrained("MiniMaxAI/MiniMax-H3", workflow="ref2va")
-
 pipe.load_components(dtype=torch.bfloat16)
 ```
 
-Without a `workflow=`, the blocks keep every branch and `load_components` pulls **both** 61.7GB transformer partitions — pass one to load only what the task needs.
+To keep every workflow available on one pipeline instead, load the full blockset — it picks the workflow per call from the inputs it is passed — and restrict the *loading* per workflow with `load_components(workflow=...)`:
+
+```py
+pipe = ModularPipeline.from_pretrained("MiniMaxAI/MiniMax-H3")
+
+# loads `transformer/` and every shared component — this one call serves `t2va` and `fl2va`
+pipe.load_components(workflow="t2va", dtype=torch.bfloat16)
+```
+
+A plain `load_components()` with no `workflow=` pulls **both** 61.7GB transformer partitions. That is a deliberate choice when a [`ComponentsManager`] with auto offloading manages the memory: the weights live in host RAM, the manager moves onto the accelerator just what each step needs, and switching workflows takes no extra call — when the `ref2va` denoiser wants the device, the strategy offloads the smallest set of components that frees enough room, which tends to be the idle `transformer/` partition rather than the (slightly larger) conditioner. See [Memory](#memory) for the recipes.
 
 The conditioner is a `Qwen3VLForConditionalGeneration`, and MiniMax-H3 reads the *unnormalized* hidden state after its 50th decoder layer rather than the last one, so the full released checkpoint is used with its language-model head unused.
 
 ## Two schedulers
 
-Video and audio latents step down two different schedules inside a single transformer call per step, which is why both blocksets expect two [`MiniMaxH3Scheduler`] instances: `scheduler` for the video latents (`shift=12.0` in the released checkpoints) and `audio_scheduler` for the audio latents (`shift=3.0`).
+Video and audio latents step down two different schedules inside a single transformer call per step, which is why the blocks expect two [`MiniMaxH3Scheduler`] instances: `scheduler` for the video latents (`shift=12.0` in the released checkpoints) and `audio_scheduler` for the audio latents (`shift=3.0`).
 
-The checkpoint is guidance-distilled: guidance is baked into the weights, so there is no guider, no `negative_prompt` and no `guidance_scale`, and every step runs exactly one forward pass.
+Both transformer partitions are guidance-distilled, so this holds for every workflow: guidance is baked into the weights, there is no guider, no `negative_prompt` and no `guidance_scale`, and every step runs exactly one forward pass.
 
 ## Generation constraints
 
@@ -78,7 +82,7 @@ from diffusers import ComponentsManager, ModularPipeline
 
 manager = ComponentsManager()
 pipe = ModularPipeline.from_pretrained("MiniMaxAI/MiniMax-H3", components_manager=manager)
-pipe.load_components(dtype=torch.bfloat16)
+pipe.load_components(workflow="t2va", dtype=torch.bfloat16)
 manager.enable_auto_cpu_offload(device="cuda", memory_reserve_margin="12GB")
 pipe.transformer.set_attention_backend("_flash_3_hub")  # Hopper, roughly 3x faster; kernels fetched from the Hub
 ```
@@ -114,7 +118,7 @@ pipe.update_components(
         ),
     ),
 )
-pipe.load_components(dtype=torch.bfloat16)
+pipe.load_components(workflow="t2va", dtype=torch.bfloat16)
 
 # version=2 int8 tensors are pinnable, which streamed offload needs, and freezing removes the one autograd
 # path the quantized tensors cannot serve.
@@ -144,7 +148,7 @@ pipe.update_components(
         "MiniMaxAI/MiniMax-H3", subfolder="text_encoder", dtype=torch.bfloat16, device_map={"": "cuda:1"}
     ),
 )
-pipe.load_components(dtype=torch.bfloat16)
+pipe.load_components(workflow="t2va", dtype=torch.bfloat16)
 pipe.transformer.to("cuda:0")
 pipe.vae.to("cuda:0")
 pipe.audio_vae.to("cuda:0")
@@ -163,26 +167,28 @@ from diffusers.utils import load_image
 from diffusers.utils.export_utils import encode_video
 
 pipe = ModularPipeline.from_pretrained("MiniMaxAI/MiniMax-H3")
-pipe.load_components(dtype=torch.bfloat16)
+pipe.load_components(workflow="fl2va", dtype=torch.bfloat16)
 pipe.to("cuda")
 
 prompt = "A red fox trotting through a snowy pine forest, snow crunching underfoot"
+# `output=` returns exactly the named outputs instead of the whole pipeline state.
+outputs = ["videos", "audio", "sampling_rate"]
 
 # Text to video + audio.
-state = pipe(prompt=prompt, generator=torch.Generator().manual_seed(42))
+results = pipe(prompt=prompt, generator=torch.Generator().manual_seed(42), output=outputs)
 
 # First frame (and optionally last frame) to video + audio. The canvas follows the first keyframe.
 image = load_image(
     "https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/diffusers/astronaut.jpg"
 )
-state = pipe(prompt=prompt, image=image, generator=torch.Generator().manual_seed(42))
+results = pipe(prompt=prompt, image=image, generator=torch.Generator().manual_seed(42), output=outputs)
 
 encode_video(
-    state.get("videos")[0],
+    results["videos"][0],
     fps=24,
     output_path="minimax_h3_fl2va.mp4",
-    audio=state.get("audio")[0],
-    audio_sample_rate=state.get("sampling_rate"),
+    audio=results["audio"][0],
+    audio_sample_rate=results["sampling_rate"],
 )
 ```
 
@@ -204,6 +210,8 @@ There is one reference class per modality, each holding in-memory media and the
 
 The rates are what everything is resampled from: frames onto MiniMax-H3's own 24 fps by dropping and duplicating whole frames, a waveform onto the audio VAE's sample rate. Media at MiniMax-H3's own rates flows through untouched, so only data produced at another rate has to say so.
 
+A reference is built one of two ways: decoded from a media file with the class's `from_file` classmethod, or constructed directly from media the request already holds in memory — which is how a previous generation feeds back in (see [A generation as a reference](#a-generation-as-a-reference)).
+
 The blocks never open a media file — decoding a path is the caller's job, as it is everywhere else in the library. Each reference class does it through its `from_file` classmethod, which takes a path or a URL (video and audio through [PyAV](https://github.com/PyAV-Org/PyAV)) and returns a reference carrying the rates the container reports — a video brings its frame rate and its soundtrack along. Prefer `from_file` over [`~utils.load_video`], which drops the frame rate: a reference built from frames whose real rate was lost is conditioned on at the wrong speed, and nothing raises.
 
 ```py
@@ -228,7 +236,7 @@ subject = MiniMaxH3ImageReference.from_file(
 )
 
 # Decoding a file brings its rates along: the video its own frame rate and its soundtrack, the clip its sample rate.
-state = pipe(
+results = pipe(
     prompt="The character speaks in time with the reference recording, natural lip movement",
     references=[
         subject,
@@ -238,22 +246,24 @@ state = pipe(
         MiniMaxH3AudioReference.from_file("voice.wav"),
     ],
     num_frames=124,
+    output=["videos", "audio", "sampling_rate"],
 )
 
 # Frames a request already holds declare the rate they carry — `load_video` does not preserve it.
 motion = load_video("motion_ref.mp4")
-state = pipe(
+results = pipe(
     prompt="The subject walks toward camera, matching the reference video's shot rhythm",
     references=[subject, MiniMaxH3VideoReference(frames=motion, fps=30.0)],
     num_frames=124,
+    output=["videos", "audio", "sampling_rate"],
 )
 
 encode_video(
-    state.get("videos")[0],
+    results["videos"][0],
     fps=24,
     output_path="minimax_h3_ref2va.mp4",
-    audio=state.get("audio")[0],
-    audio_sample_rate=state.get("sampling_rate"),
+    audio=results["audio"][0],
+    audio_sample_rate=results["sampling_rate"],
 )
 ```
 
@@ -277,19 +287,24 @@ manager.enable_auto_cpu_offload(device="cuda")
 pipe = ModularPipeline.from_pretrained("MiniMaxAI/MiniMax-H3", components_manager=manager)
 pipe.load_components(workflow="t2va", dtype=torch.bfloat16)
 
-state = pipe(prompt="An astronaut hiking through the mountains, humming a tune", num_frames=124)
+results = pipe(
+    prompt="An astronaut hiking through the mountains, humming a tune",
+    num_frames=124,
+    output=["videos", "audio", "sampling_rate"],
+)
 
 reference = MiniMaxH3VideoReference(
-    frames=state.get("videos")[0],
-    audio=state.get("audio")[0],
-    sample_rate=state.get("sampling_rate"),
+    frames=results["videos"][0],
+    audio=results["audio"][0],
+    sample_rate=results["sampling_rate"],
 )
 
 pipe.load_components(workflow="ref2va", dtype=torch.bfloat16)
-state = pipe(
+results = pipe(
     prompt="The same astronaut now walks along a beach at sunset, humming the same tune",
     references=[reference],
     num_frames=124,
+    output=["videos", "audio", "sampling_rate"],
 )
 ```
 
diff --git a/src/diffusers/modular_pipelines/minimax_h3/encoders.py b/src/diffusers/modular_pipelines/minimax_h3/encoders.py
index 122fd0812ffc..bfd73ff1e93f 100644
--- a/src/diffusers/modular_pipelines/minimax_h3/encoders.py
+++ b/src/diffusers/modular_pipelines/minimax_h3/encoders.py
@@ -143,7 +143,79 @@ class MiniMaxH3TextEncoderStep(ModularPipelineBlocks):
     @property
     def description(self) -> str:
         return (
-            "Encodes MiniMax-H3's presentation of a `t2va` / `fl2va` request: the prompt verbatim, preceded by a "
+            "Encodes MiniMax-H3's presentation of a `t2va` request: the prompt verbatim, with no chat template and "
+            "no special tokens. The checkpoint is guidance-distilled, so there is no negative prompt and no "
+            "unconditional branch."
+        )
+
+    @property
+    def expected_components(self) -> list[ComponentSpec]:
+        return [
+            ComponentSpec("text_encoder", Qwen3VLForConditionalGeneration),
+            ComponentSpec("tokenizer", Qwen2TokenizerFast),
+            ComponentSpec("processor", Qwen3VLProcessor),
+        ]
+
+    @property
+    def inputs(self) -> list[InputParam]:
+        return [
+            InputParam.template("prompt", description="The prompt to guide generation, a single string."),
+        ]
+
+    @property
+    def intermediate_outputs(self) -> list[OutputParam]:
+        return [
+            OutputParam.template(
+                "prompt_embeds",
+                description=(
+                    "The hidden state MiniMax-H3 conditions on, of shape `(1, num_text_tokens, 5120)`, read after the "
+                    "50th decoder layer of the Qwen3-VL conditioner."
+                ),
+            ),
+            OutputParam(
+                "text_token_tags",
+                type_hint=torch.Tensor,
+                description=(
+                    "The per-row modality tag of every row of `prompt_embeds` — all text for this presentation."
+                ),
+            ),
+        ]
+
+    @torch.no_grad()
+    def __call__(self, components: MiniMaxH3ModularPipeline, state: PipelineState) -> PipelineState:
+        block_state = self.get_block_state(state)
+        if not isinstance(block_state.prompt, str):
+            raise ValueError(
+                "MiniMax-H3 packs one request into one sequence, so `prompt` must be a single string, got "
+                f"{type(block_state.prompt)}."
+            )
+
+        token_ids = components.tokenizer(block_state.prompt, add_special_tokens=False)["input_ids"]
+
+        # One conditioner call. The block emits the conditioner's dtype, as every other model does — it has no
+        # denoiser of its own, since it is meant to run on its own.
+        block_state.prompt_embeds = get_qwen3vl_prompt_embeds(
+            components.text_encoder,
+            components.processor,
+            token_ids,
+            {},
+            text_encoder_layer=components.text_encoder_layer,
+            device=components._execution_device,
+            dtype=components.text_encoder.dtype,
+        )
+        block_state.text_token_tags = torch.full((len(token_ids),), components.text_tag, dtype=torch.long)
+
+        self.set_block_state(state, block_state)
+        return components, state
+
+
+class MiniMaxH3FL2VATextEncoderStep(ModularPipelineBlocks):
+    model_name = "minimax-h3"
+
+    @property
+    def description(self) -> str:
+        return (
+            "Encodes MiniMax-H3's presentation of a `fl2va` request: the prompt verbatim, preceded by a "
             '`"<Picture i>: "` label and a vision block per keyframe, with no chat template and no special tokens. '
             "The checkpoint is guidance-distilled, so there is no negative prompt and no unconditional branch."
         )
@@ -163,7 +235,7 @@ def inputs(self) -> list[InputParam]:
             InputParam(
                 name="keyframes",
                 type_hint=list,
-                description="The keyframes put onto the target canvas, in packed order (empty or None for `t2va`).",
+                description="The keyframes put onto the target canvas, in packed order.",
             ),
         ]
 
diff --git a/src/diffusers/modular_pipelines/minimax_h3/modular_blocks_minimax_h3.py b/src/diffusers/modular_pipelines/minimax_h3/modular_blocks_minimax_h3.py
index e6f4d2affd80..ba50fd126b62 100644
--- a/src/diffusers/modular_pipelines/minimax_h3/modular_blocks_minimax_h3.py
+++ b/src/diffusers/modular_pipelines/minimax_h3/modular_blocks_minimax_h3.py
@@ -26,6 +26,7 @@
 from .decoders import MiniMaxH3AfterDenoiseStep, MiniMaxH3AudioDecodeStep, MiniMaxH3VideoDecodeStep
 from .denoise import MiniMaxH3DenoiseStep, MiniMaxH3Ref2VADenoiseStep
 from .encoders import (
+    MiniMaxH3FL2VATextEncoderStep,
     MiniMaxH3KeyframeVaeEncoderStep,
     MiniMaxH3Ref2VAReferenceEncoderStep,
     MiniMaxH3Ref2VATextEncoderStep,
@@ -33,121 +34,13 @@
 )
 
 
-def _generation_outputs() -> list[OutputParam]:
-    r"""Video and audio are generated jointly; muxing them into one file is up to the caller."""
-    return [
-        OutputParam.template("videos", description="The generated video."),
-        OutputParam(
-            "audio",
-            type_hint=torch.Tensor,
-            description="The generated soundtrack, of shape `(1, 2, num_samples)`.",
-        ),
-        OutputParam("sampling_rate", type_hint=int, description="Sample rate of the generated soundtrack in Hz."),
-    ]
-
-
 # auto_docstring
-class MiniMaxH3AutoResizeStep(ConditionalPipelineBlocks):
-    """
-    Keyframe canvas block.
-       - MiniMaxH3ResizeStep runs for the `fl2va` workflow, whichever of the two keyframes is given.
-       - when neither `image` nor `last_image` is provided (`t2va`), this block is skipped and the layout step falls back to MiniMax-H3's own 16:9 canvas.
-
-      Components:
-          image_processor (`VaeImageProcessor`)
-
-      Inputs:
-          image (`Image`, *optional*):
-              Keyframe the video starts from. It is *stretched* onto the target canvas, which by default is derived from its own
-              aspect ratio.
-          last_image (`Image`, *optional*):
-              Keyframe the video ends on. Can be passed on its own to generate *up to* a frame. Combined with `image` it is the
-              follower of the two and is cover-cropped onto the canvas.
-          height (`int`, *optional*):
-              Height of the generated video in pixels, a multiple of 32.
-          width (`int`, *optional*):
-              Width of the generated video in pixels, a multiple of 32.
-
-      Outputs:
-          height (`int`):
-              Resolved height of the generated video in pixels.
-          width (`int`):
-              Resolved width of the generated video in pixels.
-          keyframes (`list`):
-              The keyframes put onto the target canvas, in packed order.
-          keyframe_anchors (`tuple`):
-              Which end of the video every keyframe is anchored to, in packed order. Positional with `keyframes`, so both are
-              resolved here.
-    """
-
-    model_name = "minimax-h3"
-    block_classes = [MiniMaxH3ResizeStep]
-    block_names = ["keyframes"]
-    block_trigger_inputs = ["image", "last_image"]
-    default_block_name = None
-
-    def select_block(self, **kwargs) -> str | None:
-        if kwargs.get("image") is not None or kwargs.get("last_image") is not None:
-            return "keyframes"
-        return None
-
-    @property
-    def description(self):
-        return (
-            "Keyframe canvas block.\n"
-            + " - MiniMaxH3ResizeStep runs for the `fl2va` workflow, whichever of the two keyframes is given.\n"
-            + " - when neither `image` nor `last_image` is provided (`t2va`), this block is skipped and the layout "
-            "step falls back to MiniMax-H3's own 16:9 canvas."
-        )
-
-
-# auto_docstring
-class MiniMaxH3AutoKeyframeVaeEncoderStep(ConditionalPipelineBlocks):
-    """
-    Keyframe conditioning block.
-       - MiniMaxH3KeyframeVaeEncoderStep runs for the `fl2va` workflow, whichever of the two keyframes is given.
-       - when neither `image` nor `last_image` is provided (`t2va`), this block is skipped.
-
-      Components:
-          vae (`AutoencoderKLMiniMaxH3`)
-
-      Inputs:
-          keyframes (`list`, *optional*):
-              The keyframes put onto the target canvas, in packed order.
-
-      Outputs:
-          condition_latents (`list`):
-              The normalized video conditioning latents, one `(1, latent_channels, 1, latent_height, latent_width)` tensor per
-              keyframe, in packed order. One entry per condition is what the prepare-latents step draws its noise against, so the
-              list is the unit the request's generator is consumed in.
-    """
-
-    model_name = "minimax-h3"
-    block_classes = [MiniMaxH3KeyframeVaeEncoderStep]
-    block_names = ["keyframes"]
-    block_trigger_inputs = ["image", "last_image"]
-    default_block_name = None
-
-    def select_block(self, **kwargs) -> str | None:
-        if kwargs.get("image") is not None or kwargs.get("last_image") is not None:
-            return "keyframes"
-        return None
-
-    @property
-    def description(self):
-        return (
-            "Keyframe conditioning block.\n"
-            + " - MiniMaxH3KeyframeVaeEncoderStep runs for the `fl2va` workflow, whichever of the two keyframes is "
-            "given.\n" + " - when neither `image` nor `last_image` is provided (`t2va`), this block is skipped."
-        )
-
-
-# auto_docstring
-class MiniMaxH3AutoBeforeEncodeStep(AutoPipelineBlocks):
+class MiniMaxH3AutoBeforeEncodeStep(ConditionalPipelineBlocks):
     """
     Media preparation block.
        - `MiniMaxH3Ref2VASetupStep` runs when `references` is provided (`ref2va`): it resolves the plan and normalizes every reference onto MiniMax-H3's own rates and resolutions.
-       - otherwise the keyframe canvas block runs, which itself is skipped for a text-only request.
+       - `MiniMaxH3ResizeStep` runs when a keyframe is provided (`fl2va`), putting the keyframes onto the target canvas.
+       - a text-only request (`t2va`) skips this block, and the layout step falls back to MiniMax-H3's own 16:9 canvas.
 
       Components:
           image_processor (`VaeImageProcessor`)
@@ -196,9 +89,17 @@ class MiniMaxH3AutoBeforeEncodeStep(AutoPipelineBlocks):
     """
 
     model_name = "minimax-h3"
-    block_classes = [MiniMaxH3Ref2VASetupStep, MiniMaxH3AutoResizeStep]
+    block_classes = [MiniMaxH3Ref2VASetupStep, MiniMaxH3ResizeStep]
     block_names = ["ref2va", "keyframes"]
-    block_trigger_inputs = ["references", None]
+    block_trigger_inputs = ["references", "image", "last_image"]
+    default_block_name = None
+
+    def select_block(self, **kwargs) -> str | None:
+        if kwargs.get("references") is not None:
+            return "ref2va"
+        if kwargs.get("image") is not None or kwargs.get("last_image") is not None:
+            return "keyframes"
+        return None
 
     @property
     def description(self):
@@ -206,16 +107,20 @@ def description(self):
             "Media preparation block.\n"
             + " - `MiniMaxH3Ref2VASetupStep` runs when `references` is provided (`ref2va`): it resolves the plan and "
             "normalizes every reference onto MiniMax-H3's own rates and resolutions.\n"
-            + " - otherwise the keyframe canvas block runs, which itself is skipped for a text-only request."
+            + " - `MiniMaxH3ResizeStep` runs when a keyframe is provided (`fl2va`), putting the keyframes onto the "
+            "target canvas.\n"
+            + " - a text-only request (`t2va`) skips this block, and the layout step falls back to MiniMax-H3's own "
+            "16:9 canvas."
         )
 
 
 # auto_docstring
-class MiniMaxH3AutoTextEncoderStep(AutoPipelineBlocks):
+class MiniMaxH3AutoTextEncoderStep(ConditionalPipelineBlocks):
     """
-    Text encoder block. Both branches encode MiniMax-H3's presentation of the request with the Qwen3-VL conditioner.
+    Text encoder block. Every branch encodes MiniMax-H3's presentation of the request with the Qwen3-VL conditioner.
        - `MiniMaxH3Ref2VATextEncoderStep` runs when `references` is provided (`ref2va`), labelling every reference in the presentation.
-       - `MiniMaxH3TextEncoderStep` runs otherwise, labelling the keyframes when there are any.
+       - `MiniMaxH3FL2VATextEncoderStep` runs when a keyframe is provided (`fl2va`), labelling every keyframe in the presentation.
+       - `MiniMaxH3TextEncoderStep` runs otherwise (`t2va`), presenting the prompt alone.
 
       Components:
           text_encoder (`Qwen3VLForConditionalGeneration`)
@@ -228,7 +133,7 @@ class MiniMaxH3AutoTextEncoderStep(AutoPipelineBlocks):
           normalized_references (`list`, *optional*):
               The references normalized by the setup step, in packed order.
           keyframes (`list`, *optional*):
-              The keyframes put onto the target canvas, in packed order (empty or None for `t2va`).
+              The keyframes put onto the target canvas, in packed order.
 
       Outputs:
           prompt_embeds (`Tensor`):
@@ -239,27 +144,38 @@ class MiniMaxH3AutoTextEncoderStep(AutoPipelineBlocks):
     """
 
     model_name = "minimax-h3"
-    block_classes = [MiniMaxH3Ref2VATextEncoderStep, MiniMaxH3TextEncoderStep]
-    block_names = ["ref2va", "t2va"]
-    block_trigger_inputs = ["references", None]
+    block_classes = [MiniMaxH3Ref2VATextEncoderStep, MiniMaxH3FL2VATextEncoderStep, MiniMaxH3TextEncoderStep]
+    block_names = ["ref2va", "fl2va", "t2va"]
+    block_trigger_inputs = ["references", "image", "last_image"]
+    default_block_name = "t2va"
+
+    def select_block(self, **kwargs) -> str | None:
+        if kwargs.get("references") is not None:
+            return "ref2va"
+        if kwargs.get("image") is not None or kwargs.get("last_image") is not None:
+            return "fl2va"
+        return None
 
     @property
     def description(self):
         return (
-            "Text encoder block. Both branches encode MiniMax-H3's presentation of the request with the Qwen3-VL "
+            "Text encoder block. Every branch encodes MiniMax-H3's presentation of the request with the Qwen3-VL "
             "conditioner.\n"
             + " - `MiniMaxH3Ref2VATextEncoderStep` runs when `references` is provided (`ref2va`), labelling every "
             "reference in the presentation.\n"
-            + " - `MiniMaxH3TextEncoderStep` runs otherwise, labelling the keyframes when there are any."
+            + " - `MiniMaxH3FL2VATextEncoderStep` runs when a keyframe is provided (`fl2va`), labelling every "
+            "keyframe in the presentation.\n"
+            + " - `MiniMaxH3TextEncoderStep` runs otherwise (`t2va`), presenting the prompt alone."
         )
 
 
 # auto_docstring
-class MiniMaxH3AutoVaeEncoderStep(AutoPipelineBlocks):
+class MiniMaxH3AutoVaeEncoderStep(ConditionalPipelineBlocks):
     """
     VAE encoder block.
        - `MiniMaxH3Ref2VAReferenceEncoderStep` runs when `references` is provided (`ref2va`).
-       - otherwise the keyframe conditioning block runs, which itself is skipped for a text-only request.
+       - `MiniMaxH3KeyframeVaeEncoderStep` runs when a keyframe is provided (`fl2va`).
+       - a text-only request (`t2va`) skips this block.
 
       Components:
           vae (`AutoencoderKLMiniMaxH3`)
@@ -283,23 +199,32 @@ class MiniMaxH3AutoVaeEncoderStep(AutoPipelineBlocks):
     """
 
     model_name = "minimax-h3"
-    block_classes = [MiniMaxH3Ref2VAReferenceEncoderStep, MiniMaxH3AutoKeyframeVaeEncoderStep]
+    block_classes = [MiniMaxH3Ref2VAReferenceEncoderStep, MiniMaxH3KeyframeVaeEncoderStep]
     block_names = ["ref2va", "keyframes"]
-    block_trigger_inputs = ["references", None]
+    block_trigger_inputs = ["references", "image", "last_image"]
+    default_block_name = None
+
+    def select_block(self, **kwargs) -> str | None:
+        if kwargs.get("references") is not None:
+            return "ref2va"
+        if kwargs.get("image") is not None or kwargs.get("last_image") is not None:
+            return "keyframes"
+        return None
 
     @property
     def description(self):
         return (
             "VAE encoder block.\n"
             + " - `MiniMaxH3Ref2VAReferenceEncoderStep` runs when `references` is provided (`ref2va`).\n"
-            + " - otherwise the keyframe conditioning block runs, which itself is skipped for a text-only request."
+            + " - `MiniMaxH3KeyframeVaeEncoderStep` runs when a keyframe is provided (`fl2va`).\n"
+            + " - a text-only request (`t2va`) skips this block."
         )
 
 
 # auto_docstring
 class MiniMaxH3CoreDenoiseStep(SequentialPipelineBlocks):
     """
-    Core denoising workflow for `t2va` / `fl2va`: builds the packed layout, draws and packs the noise, plans the per-row timesteps and runs the denoising loop against the `transformer` partition.
+    Core denoising workflow for `t2va` / `fl2va`: builds the packed layout, draws and packs the noise, plans the per-row timesteps, runs the denoising loop against the `transformer` partition and unpacks the denoised rows back into latents.
 
       Components:
           scheduler (`MiniMaxH3Scheduler`)
@@ -342,49 +267,10 @@ class MiniMaxH3CoreDenoiseStep(SequentialPipelineBlocks):
               Additional kwargs for attention processors.
 
       Outputs:
-          height (`int`):
-              Resolved height of the generated video in pixels.
-          width (`int`):
-              Resolved width of the generated video in pixels.
-          num_frames (`int`):
-              Resolved number of frames, of the form 17 * n + 5.
-          num_latent_frames (`int`):
-              Number of generated video latent frames.
-          latent_height (`int`):
-              Height of the generated video latents.
-          latent_width (`int`):
-              Width of the generated video latents.
-          num_audio_latents (`int`):
-              Number of generated audio latents per channel.
-          position_ids (`Tensor`):
-              The `(t, h, w)` rotary coordinate of every row, in float64.
-          token_tags (`Tensor`):
-              The modality tag of every row.
-          video_indices (`Tensor`):
-              Sequence positions of the video rows, conditioning rows first.
-          audio_indices (`Tensor`):
-              Sequence positions of the audio rows, reference rows first.
-          text_indices (`Tensor`):
-              Sequence positions of the text rows.
-          num_condition_video_rows (`int`):
-              How many leading video rows are conditioning rows rather than generated rows.
-          num_condition_audio_rows (`int`):
-              How many leading audio rows are reference rows rather than generated rows.
           latents (`Tensor`):
-              The video rows of the packed sequence, conditioning rows first.
+              The generated video latents, of shape `(1, latent_channels, num_latent_frames, latent_height, latent_width)`.
           audio_latents (`Tensor`):
-              The channel-major audio rows of the packed sequence, reference rows first.
-          timesteps (`Tensor`):
-              Timesteps of the video schedule.
-          audio_timesteps (`Tensor`):
-              Timesteps of the audio schedule.
-          row_timestep_plan (`list`):
-              One `(timestep, timestep_indices)` pair per step: the distinct timesteps of the sequence and the index of every row
-              into them.
-          noise_pred (`Tensor`):
-              Predicted velocity of the video rows of the sequence.
-          audio_noise_pred (`Tensor`):
-              Predicted velocity of the audio rows of the sequence.
+              The generated audio latents, one batch item per stereo channel.
     """
 
     model_name = "minimax-h3"
@@ -393,21 +279,40 @@ class MiniMaxH3CoreDenoiseStep(SequentialPipelineBlocks):
         MiniMaxH3PrepareLatentsStep,
         MiniMaxH3SetTimestepsStep,
         MiniMaxH3DenoiseStep,
+        MiniMaxH3AfterDenoiseStep,
     ]
-    block_names = ["prepare_layout", "prepare_latents", "set_timesteps", "denoise"]
+    block_names = ["prepare_layout", "prepare_latents", "set_timesteps", "denoise", "after_denoise"]
 
     @property
     def description(self):
         return (
             "Core denoising workflow for `t2va` / `fl2va`: builds the packed layout, draws and packs the noise, "
-            "plans the per-row timesteps and runs the denoising loop against the `transformer` partition."
+            "plans the per-row timesteps, runs the denoising loop against the `transformer` partition and unpacks "
+            "the denoised rows back into latents."
         )
 
+    @property
+    def outputs(self):
+        # What the decode steps consume: the generated latents of either modality.
+        return [
+            OutputParam(
+                "latents",
+                type_hint=torch.Tensor,
+                description="The generated video latents, of shape `(1, latent_channels, num_latent_frames, "
+                "latent_height, latent_width)`.",
+            ),
+            OutputParam(
+                "audio_latents",
+                type_hint=torch.Tensor,
+                description="The generated audio latents, one batch item per stereo channel.",
+            ),
+        ]
+
 
 # auto_docstring
 class MiniMaxH3Ref2VACoreDenoiseStep(SequentialPipelineBlocks):
     """
-    Core denoising workflow for `ref2va`: builds the packed layout with one block per reference, draws and packs the noise, plans the per-row timesteps and runs the denoising loop against the `transformer_ref` partition.
+    Core denoising workflow for `ref2va`: builds the packed layout with one block per reference, draws and packs the noise, plans the per-row timesteps, runs the denoising loop against the `transformer_ref` partition and unpacks the denoised rows back into latents.
 
       Components:
           scheduler (`MiniMaxH3Scheduler`)
@@ -448,49 +353,10 @@ class MiniMaxH3Ref2VACoreDenoiseStep(SequentialPipelineBlocks):
               Additional kwargs for attention processors.
 
       Outputs:
-          height (`int`):
-              Resolved height of the generated video in pixels.
-          width (`int`):
-              Resolved width of the generated video in pixels.
-          num_frames (`int`):
-              Resolved number of frames, of the form 17 * n + 5.
-          num_latent_frames (`int`):
-              Number of generated video latent frames.
-          latent_height (`int`):
-              Height of the generated video latents.
-          latent_width (`int`):
-              Width of the generated video latents.
-          num_audio_latents (`int`):
-              Number of generated audio latents per channel.
-          position_ids (`Tensor`):
-              The `(t, h, w)` rotary coordinate of every row, in float64.
-          token_tags (`Tensor`):
-              The modality tag of every row.
-          video_indices (`Tensor`):
-              Sequence positions of the video rows, conditioning rows first.
-          audio_indices (`Tensor`):
-              Sequence positions of the audio rows, reference rows first.
-          text_indices (`Tensor`):
-              Sequence positions of the text rows.
-          num_condition_video_rows (`int`):
-              How many leading video rows are conditioning rows rather than generated rows.
-          num_condition_audio_rows (`int`):
-              How many leading audio rows are reference rows rather than generated rows.
           latents (`Tensor`):
-              The video rows of the packed sequence, conditioning rows first.
+              The generated video latents, of shape `(1, latent_channels, num_latent_frames, latent_height, latent_width)`.
           audio_latents (`Tensor`):
-              The channel-major audio rows of the packed sequence, reference rows first.
-          timesteps (`Tensor`):
-              Timesteps of the video schedule.
-          audio_timesteps (`Tensor`):
-              Timesteps of the audio schedule.
-          row_timestep_plan (`list`):
-              One `(timestep, timestep_indices)` pair per step: the distinct timesteps of the sequence and the index of every row
-              into them.
-          noise_pred (`Tensor`):
-              Predicted velocity of the video rows of the sequence.
-          audio_noise_pred (`Tensor`):
-              Predicted velocity of the audio rows of the sequence.
+              The generated audio latents, one batch item per stereo channel.
     """
 
     model_name = "minimax-h3"
@@ -499,17 +365,35 @@ class MiniMaxH3Ref2VACoreDenoiseStep(SequentialPipelineBlocks):
         MiniMaxH3PrepareLatentsStep,
         MiniMaxH3SetTimestepsStep,
         MiniMaxH3Ref2VADenoiseStep,
+        MiniMaxH3AfterDenoiseStep,
     ]
-    block_names = ["prepare_layout", "prepare_latents", "set_timesteps", "denoise"]
+    block_names = ["prepare_layout", "prepare_latents", "set_timesteps", "denoise", "after_denoise"]
 
     @property
     def description(self):
         return (
             "Core denoising workflow for `ref2va`: builds the packed layout with one block per reference, draws and "
-            "packs the noise, plans the per-row timesteps and runs the denoising loop against the `transformer_ref` "
-            "partition."
+            "packs the noise, plans the per-row timesteps, runs the denoising loop against the `transformer_ref` "
+            "partition and unpacks the denoised rows back into latents."
         )
 
+    @property
+    def outputs(self):
+        # What the decode steps consume: the generated latents of either modality.
+        return [
+            OutputParam(
+                "latents",
+                type_hint=torch.Tensor,
+                description="The generated video latents, of shape `(1, latent_channels, num_latent_frames, "
+                "latent_height, latent_width)`.",
+            ),
+            OutputParam(
+                "audio_latents",
+                type_hint=torch.Tensor,
+                description="The generated audio latents, one batch item per stereo channel.",
+            ),
+        ]
+
 
 # auto_docstring
 class MiniMaxH3AutoDenoiseStep(AutoPipelineBlocks):
@@ -561,49 +445,10 @@ class MiniMaxH3AutoDenoiseStep(AutoPipelineBlocks):
               Which end of the video every keyframe is anchored to, in packed order.
 
       Outputs:
-          height (`int`):
-              Resolved height of the generated video in pixels.
-          width (`int`):
-              Resolved width of the generated video in pixels.
-          num_frames (`int`):
-              Resolved number of frames, of the form 17 * n + 5.
-          num_latent_frames (`int`):
-              Number of generated video latent frames.
-          latent_height (`int`):
-              Height of the generated video latents.
-          latent_width (`int`):
-              Width of the generated video latents.
-          num_audio_latents (`int`):
-              Number of generated audio latents per channel.
-          position_ids (`Tensor`):
-              The `(t, h, w)` rotary coordinate of every row, in float64.
-          token_tags (`Tensor`):
-              The modality tag of every row.
-          video_indices (`Tensor`):
-              Sequence positions of the video rows, conditioning rows first.
-          audio_indices (`Tensor`):
-              Sequence positions of the audio rows, reference rows first.
-          text_indices (`Tensor`):
-              Sequence positions of the text rows.
-          num_condition_video_rows (`int`):
-              How many leading video rows are conditioning rows rather than generated rows.
-          num_condition_audio_rows (`int`):
-              How many leading audio rows are reference rows rather than generated rows.
           latents (`Tensor`):
-              The video rows of the packed sequence, conditioning rows first.
+              The generated video latents, of shape `(1, latent_channels, num_latent_frames, latent_height, latent_width)`.
           audio_latents (`Tensor`):
-              The channel-major audio rows of the packed sequence, reference rows first.
-          timesteps (`Tensor`):
-              Timesteps of the video schedule.
-          audio_timesteps (`Tensor`):
-              Timesteps of the audio schedule.
-          row_timestep_plan (`list`):
-              One `(timestep, timestep_indices)` pair per step: the distinct timesteps of the sequence and the index of every row
-              into them.
-          noise_pred (`Tensor`):
-              Predicted velocity of the video rows of the sequence.
-          audio_noise_pred (`Tensor`):
-              Predicted velocity of the audio rows of the sequence.
+              The generated audio latents, one batch item per stereo channel.
     """
 
     model_name = "minimax-h3"
@@ -658,7 +503,15 @@ def description(self):
 
     @property
     def outputs(self):
-        return _generation_outputs()
+        return [
+            OutputParam.template("videos", description="The generated video."),
+            OutputParam(
+                "audio",
+                type_hint=torch.Tensor,
+                description="The generated soundtrack, of shape `(1, 2, num_samples)`.",
+            ),
+            OutputParam("sampling_rate", type_hint=int, description="Sample rate of the generated soundtrack in Hz."),
+        ]
 
 
 # auto_docstring
@@ -669,7 +522,6 @@ class MiniMaxH3Blocks(SequentialPipelineBlocks):
       Supported workflows:
         - `t2va`: requires `prompt`
         - `fl2va`: requires `prompt`, `image`
-        - `fl2va_last_frame`: requires `prompt`, `last_image`
         - `ref2va`: requires `prompt`, `references`
 
       Components:
@@ -710,6 +562,15 @@ class MiniMaxH3Blocks(SequentialPipelineBlocks):
               follower of the two and is cover-cropped onto the canvas.
           prompt (`str`):
               The prompt to guide generation, a single string.
+          normalized_references (`list`, *optional*):
+              The references normalized by the setup step, in packed order.
+          keyframes (`list`, *optional*):
+              The keyframes put onto the target canvas, in packed order.
+          condition_latents (`list`, *optional*):
+              The encoded video conditioning latents, one per image and video reference in packed order. Their shape is where
+              every reference block's geometry comes from.
+          audio_condition_latents (`list`, *optional*):
+              The encoded audio conditioning rows, one per audio-bearing reference in packed order.
           generator (`Generator`, *optional*):
               The generator of the request. The video noise is drawn from it first, then the audio noise.
           latents (`Tensor`):
@@ -724,6 +585,8 @@ class MiniMaxH3Blocks(SequentialPipelineBlocks):
               the three row-index tensors.
           attention_kwargs (`dict`, *optional*):
               Additional kwargs for attention processors.
+          keyframe_anchors (`tuple`, *optional*, defaults to ()):
+              Which end of the video every keyframe is anchored to, in packed order.
           output_type (`str`, *optional*, defaults to pil):
               Output format: 'pil', 'np' or 'pt'.
 
@@ -742,7 +605,6 @@ class MiniMaxH3Blocks(SequentialPipelineBlocks):
         MiniMaxH3AutoTextEncoderStep,
         MiniMaxH3AutoVaeEncoderStep,
         MiniMaxH3AutoDenoiseStep,
-        MiniMaxH3AfterDenoiseStep,
         MiniMaxH3DecodeStep,
     ]
     block_names = [
@@ -750,7 +612,6 @@ class MiniMaxH3Blocks(SequentialPipelineBlocks):
         "text_encoder",
         "vae_encoder",
         "denoise",
-        "after_denoise",
         "decode",
     ]
     # One repository holds both checkpoint partitions (`transformer/` for `t2va`/`fl2va`, `transformer_ref/` for
@@ -760,8 +621,9 @@ class MiniMaxH3Blocks(SequentialPipelineBlocks):
     # without instantiating the blocks first.
     _workflow_map = {
         "t2va": {"prompt": True},
+        # either keyframe trigger selects the same blocks, and the pruned route serves first, last or both because
+        # the resize step handles any combination at runtime
         "fl2va": {"prompt": True, "image": True},
-        "fl2va_last_frame": {"prompt": True, "last_image": True},
         "ref2va": {"prompt": True, "references": True},
     }
 
@@ -776,4 +638,12 @@ def description(self):
 
     @property
     def outputs(self):
-        return _generation_outputs()
+        return [
+            OutputParam.template("videos", description="The generated video."),
+            OutputParam(
+                "audio",
+                type_hint=torch.Tensor,
+                description="The generated soundtrack, of shape `(1, 2, num_samples)`.",
+            ),
+            OutputParam("sampling_rate", type_hint=int, description="Sample rate of the generated soundtrack in Hz."),
+        ]
diff --git a/tests/modular_pipelines/minimax_h3/test_modular_pipeline_minimax_h3.py b/tests/modular_pipelines/minimax_h3/test_modular_pipeline_minimax_h3.py
index eccc50a30a76..e2fa82d758d9 100644
--- a/tests/modular_pipelines/minimax_h3/test_modular_pipeline_minimax_h3.py
+++ b/tests/modular_pipelines/minimax_h3/test_modular_pipeline_minimax_h3.py
@@ -34,7 +34,7 @@
 from diffusers.modular_pipelines.minimax_h3.encoders import MiniMaxH3Ref2VATextEncoderStep, MiniMaxH3TextEncoderStep
 from diffusers.modular_pipelines.minimax_h3.modular_pipeline import MINIMAX_H3_FPS
 
-from ..test_modular_pipelines_common import ModularPipelineTesterMixin, _get_specified_components
+from ..test_modular_pipelines_common import REQUIRED, ModularPipelineTesterMixin, _get_specified_components
 
 
 # MiniMax-H3 generates 5 to 15 seconds at a fixed 24 fps, so the shortest admissible request is 124 frames
@@ -62,7 +62,7 @@
     ("denoise.set_timesteps", "MiniMaxH3SetTimestepsStep"),
 ]
 _TAIL = [
-    ("after_denoise", "MiniMaxH3AfterDenoiseStep"),
+    ("denoise.after_denoise", "MiniMaxH3AfterDenoiseStep"),
     ("decode.video", "MiniMaxH3VideoDecodeStep"),
     ("decode.audio", "MiniMaxH3AudioDecodeStep"),
 ]
@@ -77,7 +77,7 @@
 # is a matter of the packed layout, not of which blocks run.
 FL2VA_WORKFLOW = [
     ("before_encode", "MiniMaxH3ResizeStep"),
-    ("text_encoder", "MiniMaxH3TextEncoderStep"),
+    ("text_encoder", "MiniMaxH3FL2VATextEncoderStep"),
     ("vae_encoder", "MiniMaxH3KeyframeVaeEncoderStep"),
     ("denoise.prepare_layout", "MiniMaxH3PrepareLayoutStep"),
     *_CORE_DENOISE,
@@ -96,10 +96,67 @@
 MINIMAX_H3_WORKFLOWS = {
     "t2va": T2VA_WORKFLOW,
     "fl2va": FL2VA_WORKFLOW,
-    "fl2va_last_frame": FL2VA_WORKFLOW,
 }
 MINIMAX_H3_REF2VA_WORKFLOWS = {"ref2va": REF2VA_WORKFLOW}
 
+# What each pruned workflow asks for, pinned explicitly: every component (each half loads its own transformer
+# partition, nothing else differs) and every input with its default.
+_SHARED_COMPONENTS = {
+    "text_encoder": {},
+    "tokenizer": {},
+    "processor": {},
+    "scheduler": {},
+    "audio_scheduler": {},
+    "vae": {},
+    "audio_vae": {},
+    # the video decode block reverts the ImageNet normalization itself, so the processor must not denormalize again
+    "video_processor": {"vae_scale_factor": 16, "do_normalize": False},
+}
+_SHARED_INPUTS = {
+    "prompt": REQUIRED,
+    "height": None,
+    "width": None,
+    "generator": None,
+    "latents": None,
+    "audio_latents": None,
+    "num_inference_steps": REQUIRED,
+    "attention_kwargs": None,
+    "output_type": "pil",
+}
+T2VA_DEFAULTS = {
+    "components": {**_SHARED_COMPONENTS, "transformer": {}},
+    "inputs": {
+        **_SHARED_INPUTS,
+        "num_frames": 124,
+        # the standalone surface of the shared layout and latents steps: with the keyframe blocks pruned, precomputed
+        # anchors and condition latents can still be fed to them directly
+        "keyframe_anchors": (),
+        "condition_latents": None,
+        "audio_condition_latents": None,
+    },
+}
+FL2VA_DEFAULTS = {
+    "components": {**_SHARED_COMPONENTS, "transformer": {}, "image_processor": {"vae_scale_factor": 16}},
+    "inputs": {
+        **_SHARED_INPUTS,
+        "num_frames": 124,
+        "image": None,
+        "last_image": None,
+        "audio_condition_latents": None,
+    },
+}
+REF2VA_DEFAULTS = {
+    "components": {**_SHARED_COMPONENTS, "transformer_ref": {}, "image_processor": {"vae_scale_factor": 16}},
+    # `num_frames` cannot default on ref2va: reference soundtracks are truncated to the generated duration, so a
+    # silent 124-frame default would cut them short. It is required instead.
+    "inputs": {**_SHARED_INPUTS, "references": REQUIRED, "num_frames": REQUIRED},
+}
+MINIMAX_H3_WORKFLOW_DEFAULTS = {
+    "t2va": T2VA_DEFAULTS,
+    "fl2va": FL2VA_DEFAULTS,
+}
+MINIMAX_H3_REF2VA_WORKFLOW_DEFAULTS = {"ref2va": REF2VA_DEFAULTS}
+
 
 def _video_frames(num_frames: int, size: int) -> np.ndarray:
     """Synthesized video reference frames: `uint8` RGB at MiniMax-H3's own 24 fps."""
@@ -287,6 +344,7 @@ class TestMiniMaxH3ModularPipelineFast(MiniMaxH3ModularTesterBase):
 
     params = frozenset(["prompt", "image", "last_image", "height", "width", "num_frames"])
     expected_workflow_blocks = MINIMAX_H3_WORKFLOWS
+    expected_workflow_defaults = MINIMAX_H3_WORKFLOW_DEFAULTS
 
     def get_dummy_inputs(self, seed=0):
         return {
@@ -490,6 +548,7 @@ class TestMiniMaxH3Ref2VAModularPipelineFast(MiniMaxH3ModularTesterBase):
 
     params = frozenset(["prompt", "references", "height", "width", "num_frames"])
     expected_workflow_blocks = MINIMAX_H3_REF2VA_WORKFLOWS
+    expected_workflow_defaults = MINIMAX_H3_REF2VA_WORKFLOW_DEFAULTS
 
     def get_dummy_inputs(self, seed=0):
         return {

From b6cf073ea9bd02a66fcc66e843061c6851a843a5 Mon Sep 17 00:00:00 2001
From: yiyixuxu <yixu310@gmail.com>
Date: Tue, 4 Aug 2026 05:17:45 +0000
Subject: [PATCH 13/16] Let a workflow spell its triggers more than one way
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

A `_workflow_map` value could only be one trigger dict, so MiniMax-H3's
`fl2va` read as "requires `prompt`, `image`" in the generated docstring —
misleading, since `last_image` alone is a valid fl2va request, and listing
both keys would have read as requiring both. A value may now also be a
tuple of trigger dicts, alternative spellings of the same workflow:

    "fl2va": ({"prompt": True, "image": True}, {"prompt": True, "last_image": True})

Every spelling resolves the same blocks — `get_workflow` prunes with the
first, and `test_workflow_map` now asserts both the shape (a dict or a
tuple of dicts) and that each spelling's `get_execution_blocks` route is
identical. `format_workflow` renders the alternatives joined, so the
docstring reads "requires `prompt`, `image` or `prompt`, `last_image`".

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 .../minimax_h3/modular_blocks_minimax_h3.py    |  6 ++----
 .../modular_pipelines/modular_pipeline.py      |  4 ++++
 .../modular_pipeline_utils.py                  | 14 +++++++++-----
 .../test_modular_pipelines_common.py           | 18 ++++++++++++++++++
 4 files changed, 33 insertions(+), 9 deletions(-)

diff --git a/src/diffusers/modular_pipelines/minimax_h3/modular_blocks_minimax_h3.py b/src/diffusers/modular_pipelines/minimax_h3/modular_blocks_minimax_h3.py
index ba50fd126b62..adb0cd2af7b1 100644
--- a/src/diffusers/modular_pipelines/minimax_h3/modular_blocks_minimax_h3.py
+++ b/src/diffusers/modular_pipelines/minimax_h3/modular_blocks_minimax_h3.py
@@ -521,7 +521,7 @@ class MiniMaxH3Blocks(SequentialPipelineBlocks):
 
       Supported workflows:
         - `t2va`: requires `prompt`
-        - `fl2va`: requires `prompt`, `image`
+        - `fl2va`: requires `prompt`, `image` or `prompt`, `last_image`
         - `ref2va`: requires `prompt`, `references`
 
       Components:
@@ -621,9 +621,7 @@ class MiniMaxH3Blocks(SequentialPipelineBlocks):
     # without instantiating the blocks first.
     _workflow_map = {
         "t2va": {"prompt": True},
-        # either keyframe trigger selects the same blocks, and the pruned route serves first, last or both because
-        # the resize step handles any combination at runtime
-        "fl2va": {"prompt": True, "image": True},
+        "fl2va": ({"prompt": True, "image": True}, {"prompt": True, "last_image": True}),
         "ref2va": {"prompt": True, "references": True},
     }
 
diff --git a/src/diffusers/modular_pipelines/modular_pipeline.py b/src/diffusers/modular_pipelines/modular_pipeline.py
index 05315c7a2630..e3029e25bcfc 100644
--- a/src/diffusers/modular_pipelines/modular_pipeline.py
+++ b/src/diffusers/modular_pipelines/modular_pipeline.py
@@ -1019,6 +1019,10 @@ def get_workflow(self, workflow_name: str):
             )
 
         trigger_inputs = self._workflow_map[workflow_name]
+        if isinstance(trigger_inputs, tuple):
+            # a tuple of trigger dicts lists alternative spellings of the same workflow (e.g. `image` or
+            # `last_image`); every spelling resolves the same blocks, so pruning uses the first
+            trigger_inputs = trigger_inputs[0]
         workflow_blocks = self.get_execution_blocks(**trigger_inputs)
 
         return workflow_blocks
diff --git a/src/diffusers/modular_pipelines/modular_pipeline_utils.py b/src/diffusers/modular_pipelines/modular_pipeline_utils.py
index 6ab38e1ed385..e24047fe0909 100644
--- a/src/diffusers/modular_pipelines/modular_pipeline_utils.py
+++ b/src/diffusers/modular_pipelines/modular_pipeline_utils.py
@@ -902,7 +902,10 @@ def format_workflow(workflow_map):
     """Format a workflow map into a readable string representation.
 
     Args:
-        workflow_map: Dictionary mapping workflow names to trigger inputs
+        workflow_map:
+            Dictionary mapping workflow names to trigger inputs. A value is either one trigger dict, or a tuple of
+            trigger dicts listing alternative spellings of the same workflow (e.g. `image` or `last_image`), rendered
+            joined with "or".
 
     Returns:
         A formatted string representing all workflows
@@ -912,10 +915,11 @@ def format_workflow(workflow_map):
 
     lines = ["Supported workflows:"]
     for workflow_name, trigger_inputs in workflow_map.items():
-        required_inputs = [k for k, v in trigger_inputs.items() if v]
-        if required_inputs:
-            inputs_str = ", ".join(f"`{t}`" for t in required_inputs)
-            lines.append(f"  - `{workflow_name}`: requires {inputs_str}")
+        alternatives = trigger_inputs if isinstance(trigger_inputs, tuple) else (trigger_inputs,)
+        requires = [", ".join(f"`{t}`" for t, v in alternative.items() if v) for alternative in alternatives]
+        requires = [fragment for fragment in requires if fragment]
+        if requires:
+            lines.append(f"  - `{workflow_name}`: requires {' or '.join(requires)}")
         else:
             lines.append(f"  - `{workflow_name}`: default (no additional inputs required)")
 
diff --git a/tests/modular_pipelines/test_modular_pipelines_common.py b/tests/modular_pipelines/test_modular_pipelines_common.py
index 3cc0d2e5b7d7..125258aa2b6d 100644
--- a/tests/modular_pipelines/test_modular_pipelines_common.py
+++ b/tests/modular_pipelines/test_modular_pipelines_common.py
@@ -515,6 +515,24 @@ def test_workflow_map(self):
                     f"{actual_block.__class__.__name__}, expected {expected_class_name}"
                 )
 
+        # a `_workflow_map` value is either one trigger dict or a tuple of trigger dicts — alternative spellings
+        # of the same workflow, which must all resolve the same blocks since `get_workflow` prunes with the first
+        for workflow_name, trigger_inputs in blocks._workflow_map.items():
+            if isinstance(trigger_inputs, dict):
+                continue
+            assert isinstance(trigger_inputs, tuple) and all(
+                isinstance(alternative, dict) for alternative in trigger_inputs
+            ), (
+                f"Workflow '{workflow_name}': a `_workflow_map` value must be a trigger dict or a tuple of "
+                f"trigger dicts, got {trigger_inputs!r}"
+            )
+            resolved = [list(blocks.get_execution_blocks(**alternative).sub_blocks) for alternative in trigger_inputs]
+            for alternative_blocks in resolved[1:]:
+                assert alternative_blocks == resolved[0], (
+                    f"Workflow '{workflow_name}': its trigger spellings resolve different blocks: "
+                    f"{resolved[0]} vs {alternative_blocks}"
+                )
+
     def test_workflow_defaults(self):
         if not getattr(self, "expected_workflow_defaults", None):
             pytest.skip("Skipping test as expected_workflow_defaults is not set")

From af3662d58a60c57b0a60bed9878b274520e27e58 Mon Sep 17 00:00:00 2001
From: yiyixuxu <yixu310@gmail.com>
Date: Tue, 4 Aug 2026 08:34:22 +0000
Subject: [PATCH 14/16] Let every MiniMax-H3 workflow declare only its own
 inputs
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

A block that serves several workflows declares the union of what they need,
and pruning a workflow surfaces whatever no block on that route produces —
so `t2va` asked for `keyframe_anchors`, `condition_latents` and
`audio_condition_latents`, none of which a text-only request has. The
layout and prepare-latents steps split along the same seam the text encoder
did, but by composition rather than by copies.

`MiniMaxH3PrepareLatentsStep` is now the same block everywhere: it draws
the video noise and the audio noise and packs them, nothing else. What a
request conditions on is prepared around it — `MiniMaxH3PrepareConditionLatentsStep`
noises and packs the conditioning *before* it, and `MiniMaxH3FL2VAPrepareLatentsStep`
/ `MiniMaxH3Ref2VAPrepareLatentsStep` put those rows in front *after* it,
the ref2va one also prepending the reference soundtracks. The split is not
stylistic: all three streams come off the one generator the request is
passed and it is consumed in order — conditioning, then video, then audio —
so the conditioning noise has to be drawn before the generated noise or the
same seed produces a different video, while the concatenation can only
happen once the generated rows exist.

The layout stays one block for `t2va` and `fl2va`, with `keyframe_anchors`
as its input; a `t2va` route resolves none, and `MiniMaxH3NoKeyframeAnchorsStep`
says so, which is also what keeps the name off that signature. The denoise
selector gains the third branch this needs, so `fl2va` no longer borrows the
`t2va` core.

`test_workflow_defaults` grows teeth to match: a tester now names every
component of a workflow with its class, the pipeline-level configs it
declares with their defaults, its required inputs, and every optional input
with its default — all as exact sets, so a name appearing or disappearing
on a workflow fails rather than drifts. The `t2va` expectations losing three
inputs is what this commit is for.

Verified equivalent rather than assumed: reproducing the pre-split
prepare-latents body verbatim and running the composed chain off a
generator at the same seed gives bit-identical video and audio rows, so
both the draw order and the packing survive. The parity sweep is still
pending.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 .../minimax_h3/before_denoise.py              | 323 ++++++++++++++----
 .../minimax_h3/modular_blocks_minimax_h3.py   | 170 +++++++--
 .../test_modular_pipeline_minimax_h3.py       |  79 +++--
 .../test_modular_pipelines_common.py          |  59 ++--
 4 files changed, 470 insertions(+), 161 deletions(-)

diff --git a/src/diffusers/modular_pipelines/minimax_h3/before_denoise.py b/src/diffusers/modular_pipelines/minimax_h3/before_denoise.py
index c7e03d22683b..1755412d61aa 100644
--- a/src/diffusers/modular_pipelines/minimax_h3/before_denoise.py
+++ b/src/diffusers/modular_pipelines/minimax_h3/before_denoise.py
@@ -162,6 +162,37 @@ def _fill_audio_positions(
     )
 
 
+class MiniMaxH3NoKeyframeAnchorsStep(ModularPipelineBlocks):
+    model_name = "minimax-h3"
+
+    @property
+    def description(self) -> str:
+        return (
+            "Declares that a `t2va` request anchors no keyframes. The layout step is the same block for `t2va` and "
+            "`fl2va` and reads the anchors the request resolved; a text-only one resolves none, and saying so here "
+            "keeps `keyframe_anchors` off the `t2va` signature."
+        )
+
+    @property
+    def intermediate_outputs(self) -> list[OutputParam]:
+        return [
+            OutputParam(
+                "keyframe_anchors",
+                type_hint=tuple,
+                description="Which end of the video every keyframe is anchored to — empty, since there are none.",
+            ),
+        ]
+
+    @torch.no_grad()
+    def __call__(self, components: MiniMaxH3ModularPipeline, state: PipelineState) -> PipelineState:
+        block_state = self.get_block_state(state)
+
+        block_state.keyframe_anchors = ()
+
+        self.set_block_state(state, block_state)
+        return components, state
+
+
 class MiniMaxH3PrepareLayoutStep(ModularPipelineBlocks):
     model_name = "minimax-h3"
 
@@ -727,15 +758,13 @@ class MiniMaxH3PrepareLatentsStep(ModularPipelineBlocks):
     @property
     def description(self) -> str:
         return (
-            "Draws every noise stream of the request and packs the video rows. MiniMax-H3 draws one condition at a "
-            "time first — noising the encoded anchors to its conditioning level — then the video noise as a latent "
-            "tensor, then the audio noise directly in row layout, all off the request's generator, in that order."
+            "Draws the noise of the generated rows and packs them: the video noise as a latent tensor first, then "
+            "the audio noise directly in row layout, both off the request's generator, in that order. Every "
+            "workflow generates the same way, so this is the same block for all of them; a request that conditions "
+            "on something noises it *before* this block — the draw order is part of what its generator reproduces — "
+            "and puts it in front of these rows after."
         )
 
-    @property
-    def expected_components(self) -> list[ComponentSpec]:
-        return [ComponentSpec("scheduler", MiniMaxH3Scheduler)]
-
     @property
     def inputs(self) -> list[InputParam]:
         return [
@@ -769,35 +798,6 @@ def inputs(self) -> list[InputParam]:
                 type_hint=torch.Tensor,
                 description="Pre-generated audio noise of shape `(2, 32, num_audio_latents)`.",
             ),
-            InputParam(
-                name="num_condition_video_rows",
-                type_hint=int,
-                default=0,
-                description="How many conditioning rows the layout reserved, which the packed conditioning must match.",
-            ),
-            InputParam(
-                name="num_condition_audio_rows",
-                type_hint=int,
-                default=0,
-                description="How many reference audio rows the layout reserved, which the packed rows must match.",
-            ),
-            InputParam(
-                name="condition_latents",
-                type_hint=list[torch.Tensor],
-                description=(
-                    "The encoded video conditioning latents, one `(1, latent_channels, num_latent_frames, "
-                    "latent_height, latent_width)` tensor per condition in packed order, or None for a request that "
-                    "has none. Noised and packed here."
-                ),
-            ),
-            InputParam(
-                name="audio_condition_latents",
-                type_hint=list[torch.Tensor],
-                description=(
-                    "The audio conditioning rows to prepend, one tensor per audio-bearing reference in packed "
-                    "order. Empty for a request that has none, which is every `t2va` and `fl2va` one."
-                ),
-            ),
         ]
 
     @property
@@ -806,12 +806,12 @@ def intermediate_outputs(self) -> list[OutputParam]:
             OutputParam(
                 "latents",
                 type_hint=torch.Tensor,
-                description="The video rows of the packed sequence, conditioning rows first.",
+                description="The generated video rows of the packed sequence.",
             ),
             OutputParam(
                 "audio_latents",
                 type_hint=torch.Tensor,
-                description="The channel-major audio rows of the packed sequence, reference rows first.",
+                description="The generated audio rows of the packed sequence, channel-major.",
             ),
         ]
 
@@ -822,33 +822,9 @@ def __call__(self, components: MiniMaxH3ModularPipeline, state: PipelineState) -
         patch_size = components.patch_size
 
         # A request draws every stream from the one generator it is given, and the order is part of what that
-        # generator reproduces: one draw per condition first, then the video noise as a latent tensor, then the audio
-        # noise directly in row layout. Passing `latents` or `audio_latents` skips its draw and shifts the ones after
-        # it.
-        condition_rows = None
-        if block_state.condition_latents:
-            # One draw per condition, in packed order. Each is packed on its own because `ref2va` references are
-            # encoded at their own resolutions, so their latents do not share a shape.
-            packed = []
-            for condition in block_state.condition_latents:
-                noise = randn_tensor(
-                    condition.shape, generator=block_state.generator, device=device, dtype=torch.float32
-                )
-                # The anchors are not fully clean: the released model noises them to `t = 0.999` and holds them there
-                # for every step. Mixing before the patchify is the same arithmetic, since patchify only permutes.
-                noised = components.scheduler.scale_noise(condition.to(device), components.keyframe_noise_aug, noise)
-                packed.append(patchify_video_latents(noised, patch_size))
-            condition_rows = torch.cat(packed)
-            # In a hand-assembled chain the canvas reaching the layout is user input, so it can disagree with the
-            # keyframes that were actually encoded. Left alone the mismatch first surfaces as an `index_copy` shape
-            # error inside the transformer, 50 layers deep.
-            if condition_rows.shape[0] != block_state.num_condition_video_rows:
-                raise ValueError(
-                    f"The layout reserved {block_state.num_condition_video_rows} conditioning rows but the encoded "
-                    f"conditioning latents pack into {condition_rows.shape[0]}. The canvas the layout was built from "
-                    "and the one the conditioning was encoded at do not agree."
-                )
-
+        # generator reproduces: any conditioning noise first (drawn before this block), then the video noise as a
+        # latent tensor, then the audio noise directly in row layout. Passing `latents` or `audio_latents` skips its
+        # draw and shifts the ones after it.
         latents = block_state.latents
         if latents is None:
             latents = randn_tensor(
@@ -879,8 +855,216 @@ def __call__(self, components: MiniMaxH3ModularPipeline, state: PipelineState) -
                 .reshape(-1, components.audio_latent_channels)
             )
 
-        if condition_rows is not None:
-            video_rows = torch.cat([condition_rows, video_rows])
+        block_state.latents, block_state.audio_latents = video_rows, audio_rows
+
+        self.set_block_state(state, block_state)
+        return components, state
+
+
+class MiniMaxH3PrepareConditionLatentsStep(ModularPipelineBlocks):
+    model_name = "minimax-h3"
+
+    @property
+    def description(self) -> str:
+        return (
+            "Noises the encoded visual conditioning to MiniMax-H3's conditioning level and packs it into rows — the "
+            "`fl2va` keyframes or the `ref2va` image and video references, the same recipe either way. It runs "
+            "*before* the noise of the generated rows is drawn, because a request draws one condition at a time "
+            "first and that order is part of what its generator reproduces."
+        )
+
+    @property
+    def expected_components(self) -> list[ComponentSpec]:
+        return [ComponentSpec("scheduler", MiniMaxH3Scheduler)]
+
+    @property
+    def inputs(self) -> list[InputParam]:
+        return [
+            InputParam.template(
+                "generator",
+                description=(
+                    "The generator of the request. The conditioning noise is drawn from it first, one draw per "
+                    "condition, before the noise of the generated rows."
+                ),
+            ),
+            InputParam(
+                name="num_condition_video_rows",
+                type_hint=int,
+                default=0,
+                description="How many conditioning rows the layout reserved, which the packed conditioning must match.",
+            ),
+            InputParam(
+                name="condition_latents",
+                type_hint=list[torch.Tensor],
+                required=True,
+                description=(
+                    "The encoded video conditioning latents, one `(1, latent_channels, num_latent_frames, "
+                    "latent_height, latent_width)` tensor per condition in packed order."
+                ),
+            ),
+        ]
+
+    @property
+    def intermediate_outputs(self) -> list[OutputParam]:
+        return [
+            OutputParam(
+                "condition_rows",
+                type_hint=torch.Tensor,
+                description="The noised conditioning, packed into the leading video rows of the sequence.",
+            ),
+        ]
+
+    @torch.no_grad()
+    def __call__(self, components: MiniMaxH3ModularPipeline, state: PipelineState) -> PipelineState:
+        block_state = self.get_block_state(state)
+        device = components._execution_device
+        patch_size = components.patch_size
+
+        # One draw per condition, in packed order. Each is packed on its own because `ref2va` references are encoded
+        # at their own resolutions, so their latents do not share a shape.
+        packed = []
+        for condition in block_state.condition_latents:
+            noise = randn_tensor(condition.shape, generator=block_state.generator, device=device, dtype=torch.float32)
+            # The anchors are not fully clean: the released model noises them to `t = 0.999` and holds them there
+            # for every step. Mixing before the patchify is the same arithmetic, since patchify only permutes.
+            noised = components.scheduler.scale_noise(condition.to(device), components.keyframe_noise_aug, noise)
+            packed.append(patchify_video_latents(noised, patch_size))
+        block_state.condition_rows = torch.cat(packed)
+        # In a hand-assembled chain the canvas reaching the layout is user input, so it can disagree with the
+        # conditioning that was actually encoded. Left alone the mismatch first surfaces as an `index_copy` shape
+        # error inside the transformer, 50 layers deep.
+        if block_state.condition_rows.shape[0] != block_state.num_condition_video_rows:
+            raise ValueError(
+                f"The layout reserved {block_state.num_condition_video_rows} conditioning rows but the encoded "
+                f"conditioning latents pack into {block_state.condition_rows.shape[0]}. The canvas the layout was "
+                "built from and the one the conditioning was encoded at do not agree."
+            )
+
+        self.set_block_state(state, block_state)
+        return components, state
+
+
+class MiniMaxH3FL2VAPrepareLatentsStep(ModularPipelineBlocks):
+    model_name = "minimax-h3"
+
+    @property
+    def description(self) -> str:
+        return (
+            "Finishes the video rows of a `fl2va` request by putting its noised keyframe conditioning in front of "
+            "the generated rows, which is where the layout reserved it. The denoising loop only ever writes the "
+            "generated rows, so the conditioning rides through every step unchanged."
+        )
+
+    @property
+    def inputs(self) -> list[InputParam]:
+        return [
+            InputParam(
+                name="condition_rows",
+                type_hint=torch.Tensor,
+                required=True,
+                description="The noised keyframe conditioning, packed into rows.",
+            ),
+            InputParam(
+                name="latents",
+                type_hint=torch.Tensor,
+                required=True,
+                description="The generated video rows of the packed sequence.",
+            ),
+        ]
+
+    @property
+    def intermediate_outputs(self) -> list[OutputParam]:
+        return [
+            OutputParam(
+                "latents",
+                type_hint=torch.Tensor,
+                description="The video rows of the packed sequence, conditioning rows first.",
+            ),
+        ]
+
+    @torch.no_grad()
+    def __call__(self, components: MiniMaxH3ModularPipeline, state: PipelineState) -> PipelineState:
+        block_state = self.get_block_state(state)
+
+        block_state.latents = torch.cat([block_state.condition_rows, block_state.latents])
+
+        self.set_block_state(state, block_state)
+        return components, state
+
+
+class MiniMaxH3Ref2VAPrepareLatentsStep(ModularPipelineBlocks):
+    model_name = "minimax-h3"
+
+    @property
+    def description(self) -> str:
+        return (
+            "Finishes both streams of a `ref2va` request by putting its conditioning in front of the generated "
+            "rows, which is where the layout reserved it: the noised image and video references on the video side, "
+            "and the reference soundtracks on the audio side. The soundtracks are never noised — a reference "
+            "soundtrack conditions at `t = 0` — and the denoising loop only ever writes the generated rows, so all "
+            "of it rides through every step unchanged."
+        )
+
+    @property
+    def inputs(self) -> list[InputParam]:
+        return [
+            InputParam(
+                name="condition_rows",
+                type_hint=torch.Tensor,
+                required=True,
+                description="The noised conditioning of the image and video references, packed into rows.",
+            ),
+            InputParam(
+                name="latents",
+                type_hint=torch.Tensor,
+                required=True,
+                description="The generated video rows of the packed sequence.",
+            ),
+            InputParam(
+                name="audio_condition_latents",
+                type_hint=list[torch.Tensor],
+                required=True,
+                description=(
+                    "The audio conditioning rows to prepend, one tensor per audio-bearing reference in packed "
+                    "order. Empty for a request that has none."
+                ),
+            ),
+            InputParam(
+                name="num_condition_audio_rows",
+                type_hint=int,
+                default=0,
+                description="How many reference audio rows the layout reserved, which the packed rows must match.",
+            ),
+            InputParam(
+                name="audio_latents",
+                type_hint=torch.Tensor,
+                required=True,
+                description="The generated audio rows of the packed sequence, channel-major.",
+            ),
+        ]
+
+    @property
+    def intermediate_outputs(self) -> list[OutputParam]:
+        return [
+            OutputParam(
+                "latents",
+                type_hint=torch.Tensor,
+                description="The video rows of the packed sequence, conditioning rows first.",
+            ),
+            OutputParam(
+                "audio_latents",
+                type_hint=torch.Tensor,
+                description="The channel-major audio rows of the packed sequence, reference rows first.",
+            ),
+        ]
+
+    @torch.no_grad()
+    def __call__(self, components: MiniMaxH3ModularPipeline, state: PipelineState) -> PipelineState:
+        block_state = self.get_block_state(state)
+        device = components._execution_device
+
+        block_state.latents = torch.cat([block_state.condition_rows, block_state.latents])
+
         if block_state.audio_condition_latents:
             num_reference_audio_rows = sum(rows.shape[0] for rows in block_state.audio_condition_latents)
             if num_reference_audio_rows != block_state.num_condition_audio_rows:
@@ -889,8 +1073,9 @@ def __call__(self, components: MiniMaxH3ModularPipeline, state: PipelineState) -
                     f"soundtracks pack into {num_reference_audio_rows}. The references the layout was built from and "
                     "the ones the audio conditioning was encoded from do not agree."
                 )
-            audio_rows = torch.cat([rows.to(device) for rows in block_state.audio_condition_latents] + [audio_rows])
-        block_state.latents, block_state.audio_latents = video_rows, audio_rows
+            block_state.audio_latents = torch.cat(
+                [rows.to(device) for rows in block_state.audio_condition_latents] + [block_state.audio_latents]
+            )
 
         self.set_block_state(state, block_state)
         return components, state
diff --git a/src/diffusers/modular_pipelines/minimax_h3/modular_blocks_minimax_h3.py b/src/diffusers/modular_pipelines/minimax_h3/modular_blocks_minimax_h3.py
index adb0cd2af7b1..d0494bbde454 100644
--- a/src/diffusers/modular_pipelines/minimax_h3/modular_blocks_minimax_h3.py
+++ b/src/diffusers/modular_pipelines/minimax_h3/modular_blocks_minimax_h3.py
@@ -14,11 +14,15 @@
 
 import torch
 
-from ..modular_pipeline import AutoPipelineBlocks, ConditionalPipelineBlocks, SequentialPipelineBlocks
+from ..modular_pipeline import ConditionalPipelineBlocks, SequentialPipelineBlocks
 from ..modular_pipeline_utils import OutputParam
 from .before_denoise import (
+    MiniMaxH3FL2VAPrepareLatentsStep,
+    MiniMaxH3NoKeyframeAnchorsStep,
+    MiniMaxH3PrepareConditionLatentsStep,
     MiniMaxH3PrepareLatentsStep,
     MiniMaxH3PrepareLayoutStep,
+    MiniMaxH3Ref2VAPrepareLatentsStep,
     MiniMaxH3Ref2VAPrepareLayoutStep,
     MiniMaxH3SetTimestepsStep,
 )
@@ -224,7 +228,7 @@ def description(self):
 # auto_docstring
 class MiniMaxH3CoreDenoiseStep(SequentialPipelineBlocks):
     """
-    Core denoising workflow for `t2va` / `fl2va`: builds the packed layout, draws and packs the noise, plans the per-row timesteps, runs the denoising loop against the `transformer` partition and unpacks the denoised rows back into latents.
+    Core denoising workflow for `t2va`: builds the packed layout, draws and packs the noise, plans the per-row timesteps, runs the denoising loop against the `transformer` partition and unpacks the denoised rows back into latents.
 
       Components:
           scheduler (`MiniMaxH3Scheduler`)
@@ -241,8 +245,6 @@ class MiniMaxH3CoreDenoiseStep(SequentialPipelineBlocks):
           num_frames (`int`, *optional*, defaults to 124):
               Number of frames to generate, at the fixed 24 fps. Snapped up to the next `17 * n + 5` the video VAE can decode;
               the resulting duration must stay between 5 and 15 seconds.
-          keyframe_anchors (`tuple`, *optional*, defaults to ()):
-              Which end of the video every keyframe is anchored to, in packed order.
           generator (`Generator`, *optional*):
               The generator of the request. The video noise is drawn from it first, then the audio noise.
           latents (`Tensor`, *optional*):
@@ -250,12 +252,100 @@ class MiniMaxH3CoreDenoiseStep(SequentialPipelineBlocks):
               draw.
           audio_latents (`Tensor`, *optional*):
               Pre-generated audio noise of shape `(2, 32, num_audio_latents)`.
-          condition_latents (`list`, *optional*):
+          num_inference_steps (`int`):
+              The number of denoising steps.
+          prompt_embeds (`Tensor`):
+              text embeddings used to guide the image generation. Can be generated from text_encoder step.
+          **denoiser_input_fields (`None`, *optional*):
+              The structural description of the packed sequence the transformer reads by name: `token_tags`, `position_ids` and
+              the three row-index tensors.
+          attention_kwargs (`dict`, *optional*):
+              Additional kwargs for attention processors.
+
+      Outputs:
+          latents (`Tensor`):
+              The generated video latents, of shape `(1, latent_channels, num_latent_frames, latent_height, latent_width)`.
+          audio_latents (`Tensor`):
+              The generated audio latents, one batch item per stereo channel.
+    """
+
+    model_name = "minimax-h3"
+    block_classes = [
+        MiniMaxH3NoKeyframeAnchorsStep,
+        MiniMaxH3PrepareLayoutStep,
+        MiniMaxH3PrepareLatentsStep,
+        MiniMaxH3SetTimestepsStep,
+        MiniMaxH3DenoiseStep,
+        MiniMaxH3AfterDenoiseStep,
+    ]
+    block_names = [
+        "no_keyframe_anchors",
+        "prepare_layout",
+        "prepare_latents",
+        "set_timesteps",
+        "denoise",
+        "after_denoise",
+    ]
+
+    @property
+    def description(self):
+        return (
+            "Core denoising workflow for `t2va`: builds the packed layout, draws and packs the noise, plans the "
+            "per-row timesteps, runs the denoising loop against the `transformer` partition and unpacks the "
+            "denoised rows back into latents."
+        )
+
+    @property
+    def outputs(self):
+        # What the decode steps consume: the generated latents of either modality.
+        return [
+            OutputParam(
+                "latents",
+                type_hint=torch.Tensor,
+                description="The generated video latents, of shape `(1, latent_channels, num_latent_frames, "
+                "latent_height, latent_width)`.",
+            ),
+            OutputParam(
+                "audio_latents",
+                type_hint=torch.Tensor,
+                description="The generated audio latents, one batch item per stereo channel.",
+            ),
+        ]
+
+
+# auto_docstring
+class MiniMaxH3FL2VACoreDenoiseStep(SequentialPipelineBlocks):
+    """
+    Core denoising workflow for `fl2va`: builds the packed layout with the keyframes anchored, draws and packs the noise around the keyframe conditioning, plans the per-row timesteps, runs the denoising loop against the `transformer` partition and unpacks the denoised rows back into latents.
+
+      Components:
+          scheduler (`MiniMaxH3Scheduler`)
+          audio_scheduler (`MiniMaxH3Scheduler`)
+          transformer (`MiniMaxH3Transformer3DModel`)
+
+      Inputs:
+          text_token_tags (`Tensor`):
+              The per-row modality tag of every row of `prompt_embeds`.
+          height (`int`, *optional*):
+              Height of the generated video in pixels, a multiple of 32.
+          width (`int`, *optional*):
+              Width of the generated video in pixels, a multiple of 32.
+          num_frames (`int`, *optional*, defaults to 124):
+              Number of frames to generate, at the fixed 24 fps. Snapped up to the next `17 * n + 5` the video VAE can decode;
+              the resulting duration must stay between 5 and 15 seconds.
+          keyframe_anchors (`tuple`, *optional*, defaults to ()):
+              Which end of the video every keyframe is anchored to, in packed order.
+          generator (`Generator`, *optional*):
+              The generator of the request. The conditioning noise is drawn from it first, one draw per condition, before the
+              noise of the generated rows.
+          condition_latents (`list`):
               The encoded video conditioning latents, one `(1, latent_channels, num_latent_frames, latent_height, latent_width)`
-              tensor per condition in packed order, or None for a request that has none. Noised and packed here.
-          audio_condition_latents (`list`, *optional*):
-              The audio conditioning rows to prepend, one tensor per audio-bearing reference in packed order. Empty for a request
-              that has none, which is every `t2va` and `fl2va` one.
+              tensor per condition in packed order.
+          latents (`Tensor`, *optional*):
+              Pre-generated video noise of shape `(1, 24, num_latent_frames, latent_height, latent_width)`, used instead of the
+              draw.
+          audio_latents (`Tensor`, *optional*):
+              Pre-generated audio noise of shape `(2, 32, num_audio_latents)`.
           num_inference_steps (`int`):
               The number of denoising steps.
           prompt_embeds (`Tensor`):
@@ -276,19 +366,29 @@ class MiniMaxH3CoreDenoiseStep(SequentialPipelineBlocks):
     model_name = "minimax-h3"
     block_classes = [
         MiniMaxH3PrepareLayoutStep,
+        MiniMaxH3PrepareConditionLatentsStep,
         MiniMaxH3PrepareLatentsStep,
+        MiniMaxH3FL2VAPrepareLatentsStep,
         MiniMaxH3SetTimestepsStep,
         MiniMaxH3DenoiseStep,
         MiniMaxH3AfterDenoiseStep,
     ]
-    block_names = ["prepare_layout", "prepare_latents", "set_timesteps", "denoise", "after_denoise"]
+    block_names = [
+        "prepare_layout",
+        "prepare_condition_latents",
+        "prepare_latents",
+        "prepare_latents_fl2va",
+        "set_timesteps",
+        "denoise",
+        "after_denoise",
+    ]
 
     @property
     def description(self):
         return (
-            "Core denoising workflow for `t2va` / `fl2va`: builds the packed layout, draws and packs the noise, "
-            "plans the per-row timesteps, runs the denoising loop against the `transformer` partition and unpacks "
-            "the denoised rows back into latents."
+            "Core denoising workflow for `fl2va`: builds the packed layout with the keyframes anchored, draws and "
+            "packs the noise around the keyframe conditioning, plans the per-row timesteps, runs the denoising loop "
+            "against the `transformer` partition and unpacks the denoised rows back into latents."
         )
 
     @property
@@ -336,7 +436,8 @@ class MiniMaxH3Ref2VACoreDenoiseStep(SequentialPipelineBlocks):
           num_frames (`int`):
               Resolved number of frames, of the form 17 * n + 5.
           generator (`Generator`, *optional*):
-              The generator of the request. The video noise is drawn from it first, then the audio noise.
+              The generator of the request. The conditioning noise is drawn from it first, one draw per condition, before the
+              noise of the generated rows.
           latents (`Tensor`, *optional*):
               Pre-generated video noise of shape `(1, 24, num_latent_frames, latent_height, latent_width)`, used instead of the
               draw.
@@ -362,12 +463,22 @@ class MiniMaxH3Ref2VACoreDenoiseStep(SequentialPipelineBlocks):
     model_name = "minimax-h3"
     block_classes = [
         MiniMaxH3Ref2VAPrepareLayoutStep,
+        MiniMaxH3PrepareConditionLatentsStep,
         MiniMaxH3PrepareLatentsStep,
+        MiniMaxH3Ref2VAPrepareLatentsStep,
         MiniMaxH3SetTimestepsStep,
         MiniMaxH3Ref2VADenoiseStep,
         MiniMaxH3AfterDenoiseStep,
     ]
-    block_names = ["prepare_layout", "prepare_latents", "set_timesteps", "denoise", "after_denoise"]
+    block_names = [
+        "prepare_layout",
+        "prepare_condition_latents",
+        "prepare_latents",
+        "prepare_latents_ref2va",
+        "set_timesteps",
+        "denoise",
+        "after_denoise",
+    ]
 
     @property
     def description(self):
@@ -396,11 +507,12 @@ def outputs(self):
 
 
 # auto_docstring
-class MiniMaxH3AutoDenoiseStep(AutoPipelineBlocks):
+class MiniMaxH3AutoDenoiseStep(ConditionalPipelineBlocks):
     """
     Denoise block.
        - `MiniMaxH3Ref2VACoreDenoiseStep` runs when `references` is provided (`ref2va`), against the `transformer_ref` checkpoint partition.
-       - `MiniMaxH3CoreDenoiseStep` runs otherwise, against the `transformer` partition.
+       - `MiniMaxH3FL2VACoreDenoiseStep` runs when a keyframe is provided (`fl2va`), against the `transformer` partition.
+       - `MiniMaxH3CoreDenoiseStep` runs otherwise (`t2va`), against the `transformer` partition.
 
       Components:
           scheduler (`MiniMaxH3Scheduler`)
@@ -426,7 +538,8 @@ class MiniMaxH3AutoDenoiseStep(AutoPipelineBlocks):
               Number of frames to generate, at the fixed 24 fps. Snapped up to the next `17 * n + 5` the video VAE can decode;
               the resulting duration must stay between 5 and 15 seconds.
           generator (`Generator`, *optional*):
-              The generator of the request. The video noise is drawn from it first, then the audio noise.
+              The generator of the request. The conditioning noise is drawn from it first, one draw per condition, before the
+              noise of the generated rows.
           latents (`Tensor`):
               Pre-generated video noise of shape `(1, 24, num_latent_frames, latent_height, latent_width)`, used instead of the
               draw.
@@ -452,9 +565,17 @@ class MiniMaxH3AutoDenoiseStep(AutoPipelineBlocks):
     """
 
     model_name = "minimax-h3"
-    block_classes = [MiniMaxH3Ref2VACoreDenoiseStep, MiniMaxH3CoreDenoiseStep]
-    block_names = ["ref2va", "t2va"]
-    block_trigger_inputs = ["references", None]
+    block_classes = [MiniMaxH3Ref2VACoreDenoiseStep, MiniMaxH3FL2VACoreDenoiseStep, MiniMaxH3CoreDenoiseStep]
+    block_names = ["ref2va", "fl2va", "t2va"]
+    block_trigger_inputs = ["references", "image", "last_image"]
+    default_block_name = "t2va"
+
+    def select_block(self, **kwargs) -> str | None:
+        if kwargs.get("references") is not None:
+            return "ref2va"
+        if kwargs.get("image") is not None or kwargs.get("last_image") is not None:
+            return "fl2va"
+        return None
 
     @property
     def description(self):
@@ -462,7 +583,9 @@ def description(self):
             "Denoise block.\n"
             + " - `MiniMaxH3Ref2VACoreDenoiseStep` runs when `references` is provided (`ref2va`), against the "
             "`transformer_ref` checkpoint partition.\n"
-            + " - `MiniMaxH3CoreDenoiseStep` runs otherwise, against the `transformer` partition."
+            + " - `MiniMaxH3FL2VACoreDenoiseStep` runs when a keyframe is provided (`fl2va`), against the "
+            "`transformer` partition.\n"
+            + " - `MiniMaxH3CoreDenoiseStep` runs otherwise (`t2va`), against the `transformer` partition."
         )
 
 
@@ -572,7 +695,8 @@ class MiniMaxH3Blocks(SequentialPipelineBlocks):
           audio_condition_latents (`list`, *optional*):
               The encoded audio conditioning rows, one per audio-bearing reference in packed order.
           generator (`Generator`, *optional*):
-              The generator of the request. The video noise is drawn from it first, then the audio noise.
+              The generator of the request. The conditioning noise is drawn from it first, one draw per condition, before the
+              noise of the generated rows.
           latents (`Tensor`):
               Pre-generated video noise of shape `(1, 24, num_latent_frames, latent_height, latent_width)`, used instead of the
               draw.
diff --git a/tests/modular_pipelines/minimax_h3/test_modular_pipeline_minimax_h3.py b/tests/modular_pipelines/minimax_h3/test_modular_pipeline_minimax_h3.py
index e2fa82d758d9..353644923ed8 100644
--- a/tests/modular_pipelines/minimax_h3/test_modular_pipeline_minimax_h3.py
+++ b/tests/modular_pipelines/minimax_h3/test_modular_pipeline_minimax_h3.py
@@ -34,7 +34,7 @@
 from diffusers.modular_pipelines.minimax_h3.encoders import MiniMaxH3Ref2VATextEncoderStep, MiniMaxH3TextEncoderStep
 from diffusers.modular_pipelines.minimax_h3.modular_pipeline import MINIMAX_H3_FPS
 
-from ..test_modular_pipelines_common import REQUIRED, ModularPipelineTesterMixin, _get_specified_components
+from ..test_modular_pipelines_common import ModularPipelineTesterMixin, _get_specified_components
 
 
 # MiniMax-H3 generates 5 to 15 seconds at a fixed 24 fps, so the shortest admissible request is 124 frames
@@ -57,10 +57,6 @@
 TINY_MODULAR_REPO_ID = "hf-internal-testing/tiny-minimax-h3-modular-pipe"
 
 
-_CORE_DENOISE = [
-    ("denoise.prepare_latents", "MiniMaxH3PrepareLatentsStep"),
-    ("denoise.set_timesteps", "MiniMaxH3SetTimestepsStep"),
-]
 _TAIL = [
     ("denoise.after_denoise", "MiniMaxH3AfterDenoiseStep"),
     ("decode.video", "MiniMaxH3VideoDecodeStep"),
@@ -68,8 +64,10 @@
 ]
 T2VA_WORKFLOW = [
     ("text_encoder", "MiniMaxH3TextEncoderStep"),
+    ("denoise.no_keyframe_anchors", "MiniMaxH3NoKeyframeAnchorsStep"),
     ("denoise.prepare_layout", "MiniMaxH3PrepareLayoutStep"),
-    *_CORE_DENOISE,
+    ("denoise.prepare_latents", "MiniMaxH3PrepareLatentsStep"),
+    ("denoise.set_timesteps", "MiniMaxH3SetTimestepsStep"),
     ("denoise.denoise", "MiniMaxH3DenoiseStep"),
     *_TAIL,
 ]
@@ -80,7 +78,10 @@
     ("text_encoder", "MiniMaxH3FL2VATextEncoderStep"),
     ("vae_encoder", "MiniMaxH3KeyframeVaeEncoderStep"),
     ("denoise.prepare_layout", "MiniMaxH3PrepareLayoutStep"),
-    *_CORE_DENOISE,
+    ("denoise.prepare_condition_latents", "MiniMaxH3PrepareConditionLatentsStep"),
+    ("denoise.prepare_latents", "MiniMaxH3PrepareLatentsStep"),
+    ("denoise.prepare_latents_fl2va", "MiniMaxH3FL2VAPrepareLatentsStep"),
+    ("denoise.set_timesteps", "MiniMaxH3SetTimestepsStep"),
     ("denoise.denoise", "MiniMaxH3DenoiseStep"),
     *_TAIL,
 ]
@@ -89,7 +90,10 @@
     ("text_encoder", "MiniMaxH3Ref2VATextEncoderStep"),
     ("vae_encoder", "MiniMaxH3Ref2VAReferenceEncoderStep"),
     ("denoise.prepare_layout", "MiniMaxH3Ref2VAPrepareLayoutStep"),
-    *_CORE_DENOISE,
+    ("denoise.prepare_condition_latents", "MiniMaxH3PrepareConditionLatentsStep"),
+    ("denoise.prepare_latents", "MiniMaxH3PrepareLatentsStep"),
+    ("denoise.prepare_latents_ref2va", "MiniMaxH3Ref2VAPrepareLatentsStep"),
+    ("denoise.set_timesteps", "MiniMaxH3SetTimestepsStep"),
     ("denoise.denoise", "MiniMaxH3Ref2VADenoiseStep"),
     *_TAIL,
 ]
@@ -99,57 +103,52 @@
 }
 MINIMAX_H3_REF2VA_WORKFLOWS = {"ref2va": REF2VA_WORKFLOW}
 
-# What each pruned workflow asks for, pinned explicitly: every component (each half loads its own transformer
-# partition, nothing else differs) and every input with its default.
+# What each pruned workflow asks for, pinned explicitly: every component with its class (each half loads its own
+# transformer partition, nothing else differs) and every input — the optional ones with their defaults, the
+# required ones by name. MiniMax-H3 declares no pipeline-level configs, which the omitted `configs` key asserts.
 _SHARED_COMPONENTS = {
-    "text_encoder": {},
-    "tokenizer": {},
-    "processor": {},
-    "scheduler": {},
-    "audio_scheduler": {},
-    "vae": {},
-    "audio_vae": {},
-    # the video decode block reverts the ImageNet normalization itself, so the processor must not denormalize again
-    "video_processor": {"vae_scale_factor": 16, "do_normalize": False},
+    "text_encoder": "Qwen3VLForConditionalGeneration",
+    "tokenizer": "Qwen2Tokenizer",
+    "processor": "Qwen3VLProcessor",
+    "scheduler": "MiniMaxH3Scheduler",
+    "audio_scheduler": "MiniMaxH3Scheduler",
+    "vae": "AutoencoderKLMiniMaxH3",
+    "audio_vae": "AutoencoderKLMiniMaxH3Audio",
+    "video_processor": "VideoProcessor",
 }
 _SHARED_INPUTS = {
-    "prompt": REQUIRED,
     "height": None,
     "width": None,
     "generator": None,
     "latents": None,
     "audio_latents": None,
-    "num_inference_steps": REQUIRED,
     "attention_kwargs": None,
     "output_type": "pil",
 }
 T2VA_DEFAULTS = {
-    "components": {**_SHARED_COMPONENTS, "transformer": {}},
-    "inputs": {
-        **_SHARED_INPUTS,
-        "num_frames": 124,
-        # the standalone surface of the shared layout and latents steps: with the keyframe blocks pruned, precomputed
-        # anchors and condition latents can still be fed to them directly
-        "keyframe_anchors": (),
-        "condition_latents": None,
-        "audio_condition_latents": None,
-    },
+    "components": {**_SHARED_COMPONENTS, "transformer": "MiniMaxH3Transformer3DModel"},
+    "required_inputs": ["prompt", "num_inference_steps"],
+    "inputs": {**_SHARED_INPUTS, "num_frames": 124},
 }
 FL2VA_DEFAULTS = {
-    "components": {**_SHARED_COMPONENTS, "transformer": {}, "image_processor": {"vae_scale_factor": 16}},
-    "inputs": {
-        **_SHARED_INPUTS,
-        "num_frames": 124,
-        "image": None,
-        "last_image": None,
-        "audio_condition_latents": None,
+    "components": {
+        **_SHARED_COMPONENTS,
+        "transformer": "MiniMaxH3Transformer3DModel",
+        "image_processor": "VaeImageProcessor",
     },
+    "required_inputs": ["prompt", "num_inference_steps"],
+    "inputs": {**_SHARED_INPUTS, "num_frames": 124, "image": None, "last_image": None},
 }
 REF2VA_DEFAULTS = {
-    "components": {**_SHARED_COMPONENTS, "transformer_ref": {}, "image_processor": {"vae_scale_factor": 16}},
+    "components": {
+        **_SHARED_COMPONENTS,
+        "transformer_ref": "MiniMaxH3Transformer3DModel",
+        "image_processor": "VaeImageProcessor",
+    },
     # `num_frames` cannot default on ref2va: reference soundtracks are truncated to the generated duration, so a
     # silent 124-frame default would cut them short. It is required instead.
-    "inputs": {**_SHARED_INPUTS, "references": REQUIRED, "num_frames": REQUIRED},
+    "required_inputs": ["prompt", "references", "num_frames", "num_inference_steps"],
+    "inputs": _SHARED_INPUTS,
 }
 MINIMAX_H3_WORKFLOW_DEFAULTS = {
     "t2va": T2VA_DEFAULTS,
diff --git a/tests/modular_pipelines/test_modular_pipelines_common.py b/tests/modular_pipelines/test_modular_pipelines_common.py
index 125258aa2b6d..5c51295a7e79 100644
--- a/tests/modular_pipelines/test_modular_pipelines_common.py
+++ b/tests/modular_pipelines/test_modular_pipelines_common.py
@@ -54,16 +54,6 @@ def _get_specified_components(path_or_repo_id, cache_dir=None):
     return components
 
 
-class _RequiredInput:
-    """Sentinel for `expected_workflow_defaults`: the input has no default and must be passed."""
-
-    def __repr__(self):
-        return "REQUIRED"
-
-
-REQUIRED = _RequiredInput()
-
-
 class ModularPipelineTesterMixin:
     """
     It provides a set of common tests for each modular pipeline,
@@ -541,37 +531,48 @@ def test_workflow_defaults(self):
         for workflow_name, expected_defaults in self.expected_workflow_defaults.items():
             workflow_blocks = blocks.get_workflow(workflow_name)
 
-            # every component of the workflow is named, so one appearing or disappearing fails loudly
+            # components: every one of the workflow is named with its class, so one appearing, disappearing or
+            # changing type fails loudly
             component_specs = {spec.name: spec for spec in workflow_blocks.expected_components}
             expected_components = expected_defaults["components"]
             assert set(component_specs) == set(expected_components), (
                 f"Workflow '{workflow_name}' expects components {sorted(component_specs)}, "
                 f"the test expects {sorted(expected_components)}"
             )
-            for component_name, expected_config in expected_components.items():
-                config = component_specs[component_name].config or {}
-                for field, expected_value in expected_config.items():
-                    assert config.get(field) == expected_value, (
-                        f"Workflow '{workflow_name}': component '{component_name}' config '{field}' is "
-                        f"{config.get(field)}, expected {expected_value}"
-                    )
-
-            # kwargs-style inputs (e.g. **denoiser_input_fields) have no name and no default to pin
+            for component_name, expected_class_name in expected_components.items():
+                actual_class_name = component_specs[component_name].type_hint.__name__
+                assert actual_class_name == expected_class_name, (
+                    f"Workflow '{workflow_name}': component '{component_name}' is a {actual_class_name}, "
+                    f"expected {expected_class_name}"
+                )
+
+            # configs: the pipeline-level configs the workflow declares, with their defaults
+            config_specs = {spec.name: spec.default for spec in workflow_blocks.expected_configs}
+            expected_configs = expected_defaults.get("configs", {})
+            assert config_specs == expected_configs, (
+                f"Workflow '{workflow_name}' declares configs {config_specs}, the test expects {expected_configs}"
+            )
+
+            # inputs: `inputs` names every optional input with its default and `required_inputs` the required ones,
+            # and together they are exactly the workflow's inputs. kwargs-style inputs (e.g.
+            # **denoiser_input_fields) have no name and no default to pin
             input_params = {param.name: param for param in workflow_blocks.inputs if param.name is not None}
             expected_inputs = expected_defaults["inputs"]
-            assert set(input_params) == set(expected_inputs), (
+            expected_required = expected_defaults.get("required_inputs", [])
+            assert set(input_params) == set(expected_inputs) | set(expected_required), (
                 f"Workflow '{workflow_name}' takes inputs {sorted(input_params)}, "
-                f"the test expects {sorted(expected_inputs)}"
+                f"the test expects {sorted(set(expected_inputs) | set(expected_required))}"
             )
+            for input_name in expected_required:
+                assert input_params[input_name].required, (
+                    f"Workflow '{workflow_name}': input '{input_name}' should be required"
+                )
             for input_name, expected_default in expected_inputs.items():
                 param = input_params[input_name]
-                if expected_default is REQUIRED:
-                    assert param.required, f"Workflow '{workflow_name}': input '{input_name}' should be required"
-                else:
-                    assert not param.required and param.default == expected_default, (
-                        f"Workflow '{workflow_name}': input '{input_name}' default is "
-                        f"{param.default!r} (required={param.required}), expected {expected_default!r}"
-                    )
+                assert not param.required and param.default == expected_default, (
+                    f"Workflow '{workflow_name}': input '{input_name}' default is "
+                    f"{param.default!r} (required={param.required}), expected {expected_default!r}"
+                )
 
     def test_from_pretrained_workflow(self):
         blocks = self.pipeline_blocks_class()

From 0c88475e9803fbb0ad253c2a6f94ab7048165edc Mon Sep 17 00:00:00 2001
From: yiyixuxu <yixu310@gmail.com>
Date: Tue, 4 Aug 2026 10:08:10 +0000
Subject: [PATCH 15/16] Let the MiniMax-H3 canvas be configured rather than
 patched
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

`MINIMAX_H3_SHORT_EDGE` and `MINIMAX_H3_MAX_PIXELS` were module constants
read straight out of `resolve_canvas_size`, so the only way to generate — or
to condition on a reference — at another resolution was to reach into the
module and reassign them, which is what the tests did. They become
`canvas_short_edge` and `canvas_max_pixels`, declared as pipeline config by
each of the three blocks that resolves a canvas, passed into
`resolve_canvas_size` alongside the multiple it already took. The rule stays
one rule: a video reference is put on the canvas its own aspect ratio
resolves to under the same numbers the generated video follows, which is why
this is pipeline config and not per-block.

The tests configure instead of patching: the `ref2va` tester overrides
`get_pipeline` to swap in a setup step with a small
`reference_image_short_edge` and to `update_components` the canvas down, and
the resample test passes the rule explicitly to `_normalize_video_condition`.
The autouse fixture that monkeypatched a class `__init__` and two module
globals for the whole file is gone. `expected_workflow_defaults` grows a
`configs` section that now asserts something: every workflow declares the
released canvas.

The rest is the test file, which had drifted into its own dialect. It reads
like every other modular pipeline's now: no local tester base class, each
tester declaring its own attributes and pinning only the workflows it drives,
the way flux2-klein does for two workflows of one blockset. Both text
encoders and the `ref2va` one are exercised through their blocks alone rather
than through a whole pipeline, and the two `test_encode_prompt`s fold into
those. The module constants and the four media helpers are inlined at their
use sites, with the arithmetic that was worth keeping — 124 frames as
`17 * 7 + 5`, its 37 latent frames and 207 audio latents, 160 Hz as the tiny
audio VAE's own rate — written as comments where a reader meets the number.
`TestMiniMaxH3ReferenceGeometry` merges into `TestMiniMaxH3Reference`, the
file-decoding tests and their PyAV fixtures are dropped, and
`test_reference_rates_default_to_the_model_rates` says what it checks:
`test_reference_without_rates_is_not_resampled`.

Verified equivalent, not assumed: the composed prepare-latents chain still
returns bit-identical rows to the pre-split single block at three seeds, and
the generated docstrings regenerate clean.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 .../minimax_h3/before_denoise.py              |  15 +-
 .../minimax_h3/before_encoder.py              |  42 +-
 .../minimax_h3/modular_blocks_minimax_h3.py   |  20 +
 .../minimax_h3/modular_pipeline.py            |  32 +-
 .../test_modular_pipeline_minimax_h3.py       | 748 +++++++-----------
 5 files changed, 387 insertions(+), 470 deletions(-)

diff --git a/src/diffusers/modular_pipelines/minimax_h3/before_denoise.py b/src/diffusers/modular_pipelines/minimax_h3/before_denoise.py
index 1755412d61aa..19ec2d0786bf 100644
--- a/src/diffusers/modular_pipelines/minimax_h3/before_denoise.py
+++ b/src/diffusers/modular_pipelines/minimax_h3/before_denoise.py
@@ -19,7 +19,7 @@
 from ...utils import logging
 from ...utils.torch_utils import randn_tensor
 from ..modular_pipeline import ModularPipelineBlocks, PipelineState
-from ..modular_pipeline_utils import ComponentSpec, InputParam, OutputParam
+from ..modular_pipeline_utils import ComponentSpec, ConfigSpec, InputParam, OutputParam
 from .modular_pipeline import (
     MINIMAX_H3_AUDIO_CHANNELS,
     MINIMAX_H3_AUDIO_TAG,
@@ -206,6 +206,11 @@ def description(self) -> str:
             "through."
         )
 
+    @property
+    def expected_configs(self) -> list[ConfigSpec]:
+        # The canvas MiniMax-H3 was released for, which a request without keyframes generates on at 16:9.
+        return [ConfigSpec("canvas_short_edge", 768), ConfigSpec("canvas_max_pixels", 768 * 1344)]
+
     @property
     def inputs(self) -> list[InputParam]:
         return [
@@ -393,7 +398,13 @@ def __call__(self, components: MiniMaxH3ModularPipeline, state: PipelineState) -
 
         # Without a keyframe to take the aspect ratio from, MiniMax-H3 generates on its own 16:9 canvas.
         if block_state.height is None:
-            block_state.height, block_state.width = resolve_canvas_size(16, 9, components.canvas_multiple)
+            block_state.height, block_state.width = resolve_canvas_size(
+                16,
+                9,
+                components.canvas_multiple,
+                components.config.canvas_short_edge,
+                components.config.canvas_max_pixels,
+            )
         if block_state.height % components.canvas_multiple or block_state.width % components.canvas_multiple:
             raise ValueError(
                 f"`height` and `width` must be multiples of {components.canvas_multiple}, got "
diff --git a/src/diffusers/modular_pipelines/minimax_h3/before_encoder.py b/src/diffusers/modular_pipelines/minimax_h3/before_encoder.py
index 7cefedc8b95a..d493eb29f636 100644
--- a/src/diffusers/modular_pipelines/minimax_h3/before_encoder.py
+++ b/src/diffusers/modular_pipelines/minimax_h3/before_encoder.py
@@ -23,7 +23,7 @@
 from ...image_processor import VaeImageProcessor
 from ...utils import logging
 from ..modular_pipeline import ModularPipelineBlocks, PipelineState
-from ..modular_pipeline_utils import ComponentSpec, InputParam, OutputParam
+from ..modular_pipeline_utils import ComponentSpec, ConfigSpec, InputParam, OutputParam
 from .modular_pipeline import (
     MINIMAX_H3_FPS,
     MiniMaxH3ModularPipeline,
@@ -63,6 +63,12 @@ def expected_components(self) -> list[ComponentSpec]:
             ),
         ]
 
+    @property
+    def expected_configs(self) -> list[ConfigSpec]:
+        # The canvas MiniMax-H3 was released for. Every block that resolves one declares these, so a fine-tune that
+        # generates at another resolution is configured rather than patched.
+        return [ConfigSpec("canvas_short_edge", 768), ConfigSpec("canvas_max_pixels", 768 * 1344)]
+
     @property
     def inputs(self) -> list[InputParam]:
         return [
@@ -117,7 +123,12 @@ def __call__(self, components: MiniMaxH3ModularPipeline, state: PipelineState) -
             if keyframe is not None
         )
         if block_state.height is None:
-            block_state.height, block_state.width = resolve_canvas_size(*keyframes[0].size, components.canvas_multiple)
+            block_state.height, block_state.width = resolve_canvas_size(
+                *keyframes[0].size,
+                components.canvas_multiple,
+                components.config.canvas_short_edge,
+                components.config.canvas_max_pixels,
+            )
 
         prepared = []
         for index, keyframe in enumerate(keyframes):
@@ -201,6 +212,11 @@ def expected_components(self) -> list[ComponentSpec]:
             ),
         ]
 
+    @property
+    def expected_configs(self) -> list[ConfigSpec]:
+        # The canvas MiniMax-H3 was released for, which a video reference is put on as well.
+        return [ConfigSpec("canvas_short_edge", 768), ConfigSpec("canvas_max_pixels", 768 * 1344)]
+
     @property
     def inputs(self) -> list[InputParam]:
         return [
@@ -253,7 +269,9 @@ def intermediate_outputs(self) -> list[OutputParam]:
         ]
 
     @staticmethod
-    def _normalize_video_condition(frames, fps: float, num_frames: int, canvas_multiple: int) -> np.ndarray:
+    def _normalize_video_condition(
+        frames, fps: float, num_frames: int, canvas_multiple: int, canvas_short_edge: int, canvas_max_pixels: int
+    ) -> np.ndarray:
         r"""
         Normalize a video reference's frames: any accepted layout, onto `uint8` at 24 fps, truncated to the generated
         frame count, on the canvas its own aspect ratio resolves to.
@@ -271,6 +289,9 @@ def _normalize_video_condition(frames, fps: float, num_frames: int, canvas_multi
             fps (`float`): The frame rate `frames` carries.
             num_frames (`int`): The generated frame count the reference is truncated to.
             canvas_multiple (`int`): What both canvas axes round to, i.e. `components.canvas_multiple`.
+            canvas_short_edge (`int`), canvas_max_pixels (`int`):
+                The canvas rule the reference is put on, i.e. `components.config.canvas_short_edge` and
+                `components.config.canvas_max_pixels` — the same one the generated video follows.
 
         Returns:
             `np.ndarray` of shape `(num_frames, height, width, 3)`: the normalized `uint8` RGB frames.
@@ -301,7 +322,9 @@ def _normalize_video_condition(frames, fps: float, num_frames: int, canvas_multi
         # Truncated to the generated frame count and put on the canvas of its *own* aspect ratio — the same rule the
         # target canvas follows, unlike an image reference.
         frames = frames[:num_frames]
-        height, width = resolve_canvas_size(frames.shape[2], frames.shape[1], canvas_multiple)
+        height, width = resolve_canvas_size(
+            frames.shape[2], frames.shape[1], canvas_multiple, canvas_short_edge, canvas_max_pixels
+        )
         if frames.shape[1:3] == (height, width):
             return frames
         return np.stack(
@@ -388,7 +411,9 @@ def __call__(self, components: MiniMaxH3ModularPipeline, state: PipelineState) -
         # frame count, so that is what the ceiling holds for: 346 frames would otherwise pass the check and then be
         # rounded up to 362, i.e. 15.083 seconds.
         if block_state.height is None:
-            block_state.height, block_state.width = resolve_canvas_size(16, 9, multiple)
+            block_state.height, block_state.width = resolve_canvas_size(
+                16, 9, multiple, components.config.canvas_short_edge, components.config.canvas_max_pixels
+            )
         aligned_num_frames = align_num_frames(
             block_state.num_frames, components.vae_frames_per_chunk, components.vae_latents_per_chunk
         )
@@ -443,7 +468,12 @@ def __call__(self, components: MiniMaxH3ModularPipeline, state: PipelineState) -
                 normalized.append(
                     MiniMaxH3VideoReference(
                         frames=self._normalize_video_condition(
-                            entry.frames, float(entry.fps), block_state.num_frames, multiple
+                            entry.frames,
+                            float(entry.fps),
+                            block_state.num_frames,
+                            multiple,
+                            components.config.canvas_short_edge,
+                            components.config.canvas_max_pixels,
                         ),
                         fps=float(components.fps),
                         audio=waveform,
diff --git a/src/diffusers/modular_pipelines/minimax_h3/modular_blocks_minimax_h3.py b/src/diffusers/modular_pipelines/minimax_h3/modular_blocks_minimax_h3.py
index d0494bbde454..6f83751719ba 100644
--- a/src/diffusers/modular_pipelines/minimax_h3/modular_blocks_minimax_h3.py
+++ b/src/diffusers/modular_pipelines/minimax_h3/modular_blocks_minimax_h3.py
@@ -49,6 +49,10 @@ class MiniMaxH3AutoBeforeEncodeStep(ConditionalPipelineBlocks):
       Components:
           image_processor (`VaeImageProcessor`)
 
+      Configs:
+          canvas_short_edge (default: 768)
+          canvas_max_pixels (default: 1032192)
+
       Inputs:
           references (`list`, *optional*):
               The references to condition on, **in the order the model should read them**: the order labels them in the prompt
@@ -235,6 +239,10 @@ class MiniMaxH3CoreDenoiseStep(SequentialPipelineBlocks):
           audio_scheduler (`MiniMaxH3Scheduler`)
           transformer (`MiniMaxH3Transformer3DModel`)
 
+      Configs:
+          canvas_short_edge (default: 768)
+          canvas_max_pixels (default: 1032192)
+
       Inputs:
           text_token_tags (`Tensor`):
               The per-row modality tag of every row of `prompt_embeds`.
@@ -323,6 +331,10 @@ class MiniMaxH3FL2VACoreDenoiseStep(SequentialPipelineBlocks):
           audio_scheduler (`MiniMaxH3Scheduler`)
           transformer (`MiniMaxH3Transformer3DModel`)
 
+      Configs:
+          canvas_short_edge (default: 768)
+          canvas_max_pixels (default: 1032192)
+
       Inputs:
           text_token_tags (`Tensor`):
               The per-row modality tag of every row of `prompt_embeds`.
@@ -520,6 +532,10 @@ class MiniMaxH3AutoDenoiseStep(ConditionalPipelineBlocks):
           transformer_ref (`MiniMaxH3Transformer3DModel`)
           transformer (`MiniMaxH3Transformer3DModel`)
 
+      Configs:
+          canvas_short_edge (default: 768)
+          canvas_max_pixels (default: 1032192)
+
       Inputs:
           text_token_tags (`Tensor`):
               The per-row modality tag of every row of `prompt_embeds`.
@@ -660,6 +676,10 @@ class MiniMaxH3Blocks(SequentialPipelineBlocks):
           transformer (`MiniMaxH3Transformer3DModel`)
           video_processor (`VideoProcessor`)
 
+      Configs:
+          canvas_short_edge (default: 768)
+          canvas_max_pixels (default: 1032192)
+
       Inputs:
           references (`list`, *optional*):
               The references to condition on, **in the order the model should read them**: the order labels them in the prompt
diff --git a/src/diffusers/modular_pipelines/minimax_h3/modular_pipeline.py b/src/diffusers/modular_pipelines/minimax_h3/modular_pipeline.py
index 925a9a0058ac..0be5ccc9d90b 100644
--- a/src/diffusers/modular_pipelines/minimax_h3/modular_pipeline.py
+++ b/src/diffusers/modular_pipelines/minimax_h3/modular_pipeline.py
@@ -24,13 +24,11 @@
 MINIMAX_H3_TEXT_TAG = 1
 MINIMAX_H3_AUDIO_TAG = 2
 
-# MiniMax-H3 generates at a fixed 24 fps and was released for a 768 pixel short edge only, with a soft area cap of
-# 768x1344. The multiple both axes round to follows from
-# the VAE and the transformer, so it is `MiniMaxH3ModularPipeline.canvas_multiple` below and reaches these helpers
-# as an argument.
+# MiniMax-H3 generates at a fixed 24 fps. The canvas it generates on is configurable rather than a constant here:
+# the short edge and the area cap are the `canvas_short_edge` / `canvas_max_pixels` configs of the blocks that
+# resolve a canvas, and the multiple both axes round to follows from the VAE and the transformer, so it is
+# `MiniMaxH3ModularPipeline.canvas_multiple` below. All three reach these helpers as arguments.
 MINIMAX_H3_FPS = 24
-MINIMAX_H3_SHORT_EDGE = 768
-MINIMAX_H3_MAX_PIXELS = 768 * 1344
 MINIMAX_H3_MIN_ASPECT_RATIO = 1 / 4
 MINIMAX_H3_MAX_ASPECT_RATIO = 4
 
@@ -40,19 +38,25 @@
 MINIMAX_H3_AUDIO_CHANNELS = 2
 
 
-def resolve_canvas_size(aspect_width: float, aspect_height: float, canvas_multiple: int) -> tuple[int, int]:
+def resolve_canvas_size(
+    aspect_width: float, aspect_height: float, canvas_multiple: int, short_edge: int, max_pixels: int
+) -> tuple[int, int]:
     r"""
     Resolve a display aspect ratio into a MiniMax-H3 canvas.
 
-    The short edge starts at 768, the area is capped at `768 * 1344` and both axes are then rounded to the nearest
-    `canvas_multiple` — so the final area may end up slightly above the pre-rounding budget. Only the ratio of the two
-    arguments matters; pass either the aspect ratio (`16, 9`) or the source dimensions of a keyframe.
+    The short edge starts at `short_edge`, the area is capped at `max_pixels` and both axes are then rounded to the
+    nearest `canvas_multiple` — so the final area may end up slightly above the pre-rounding budget. Only the ratio of
+    the first two arguments matters; pass either the aspect ratio (`16, 9`) or the source dimensions of a keyframe.
 
     Args:
         aspect_width (`float`): Width of the target ratio.
         aspect_height (`float`): Height of the target ratio.
         canvas_multiple (`int`):
             What both axes round to, i.e. `components.canvas_multiple` — 32 for the released checkpoint.
+        short_edge (`int`):
+            The short edge to aim for, i.e. `components.config.canvas_short_edge` — 768 for the released checkpoint.
+        max_pixels (`int`):
+            The area budget, i.e. `components.config.canvas_max_pixels` — `768 * 1344` for the released checkpoint.
 
     Returns:
         `tuple[int, int]`: the `(height, width)` of the canvas.
@@ -67,13 +71,13 @@ def resolve_canvas_size(aspect_width: float, aspect_height: float, canvas_multip
         )
 
     if ratio >= 1.0:
-        width, height = MINIMAX_H3_SHORT_EDGE * ratio, float(MINIMAX_H3_SHORT_EDGE)
+        width, height = short_edge * ratio, float(short_edge)
     else:
-        width, height = float(MINIMAX_H3_SHORT_EDGE), MINIMAX_H3_SHORT_EDGE / ratio
+        width, height = float(short_edge), short_edge / ratio
 
     area = width * height
-    if area > MINIMAX_H3_MAX_PIXELS:
-        scale = (MINIMAX_H3_MAX_PIXELS / area) ** 0.5
+    if area > max_pixels:
+        scale = (max_pixels / area) ** 0.5
         width, height = width * scale, height * scale
 
     multiple = canvas_multiple
diff --git a/tests/modular_pipelines/minimax_h3/test_modular_pipeline_minimax_h3.py b/tests/modular_pipelines/minimax_h3/test_modular_pipeline_minimax_h3.py
index 353644923ed8..4b7c7ad16c0e 100644
--- a/tests/modular_pipelines/minimax_h3/test_modular_pipeline_minimax_h3.py
+++ b/tests/modular_pipelines/minimax_h3/test_modular_pipeline_minimax_h3.py
@@ -26,86 +26,67 @@
     MiniMaxH3ImageReference,
     MiniMaxH3VideoReference,
 )
-from diffusers.modular_pipelines.minimax_h3 import modular_pipeline as minimax_h3_geometry
-from diffusers.modular_pipelines.minimax_h3 import (
-    references as minimax_h3_references,
-)
 from diffusers.modular_pipelines.minimax_h3.before_encoder import MiniMaxH3Ref2VASetupStep
-from diffusers.modular_pipelines.minimax_h3.encoders import MiniMaxH3Ref2VATextEncoderStep, MiniMaxH3TextEncoderStep
+from diffusers.modular_pipelines.minimax_h3.encoders import (
+    MiniMaxH3FL2VATextEncoderStep,
+    MiniMaxH3Ref2VATextEncoderStep,
+    MiniMaxH3TextEncoderStep,
+)
 from diffusers.modular_pipelines.minimax_h3.modular_pipeline import MINIMAX_H3_FPS
 
-from ..test_modular_pipelines_common import ModularPipelineTesterMixin, _get_specified_components
-
-
-# MiniMax-H3 generates 5 to 15 seconds at a fixed 24 fps, so the shortest admissible request is 124 frames
-# (`17 * 7 + 5`, the next length the video VAE can decode). It is affordable on CPU because the canvas is tiny: 32
-# pixels is a single `(1, 2, 2)` patch row per latent frame.
-NUM_FRAMES = 124
-RESOLUTION = 32
-NUM_LATENT_FRAMES = 37
-NUM_AUDIO_LATENTS = 207
-# `prod(encoder_rates)` of the tiny audio VAE, standing in for the released 800 samples per latent.
-AUDIO_HOP_LENGTH = 4
-# The tiny audio VAE's own sample rate, so a reference soundtrack is never resampled.
-AUDIO_SAMPLE_RATE = 40 * AUDIO_HOP_LENGTH
-
-# The released short edge of an image reference is 2048 pixels, which packs thousands of conditioning rows.
-TEST_REFERENCE_IMAGE_SHORT_EDGE = 64
-
-# Both blocksets read the same repository, as the released one does: `transformer/` serves the `t2va` / `fl2va` half
-# and `transformer_ref/` the `ref2va` one, every other component is shared.
-TINY_MODULAR_REPO_ID = "hf-internal-testing/tiny-minimax-h3-modular-pipe"
-
-
-_TAIL = [
-    ("denoise.after_denoise", "MiniMaxH3AfterDenoiseStep"),
-    ("decode.video", "MiniMaxH3VideoDecodeStep"),
-    ("decode.audio", "MiniMaxH3AudioDecodeStep"),
-]
-T2VA_WORKFLOW = [
-    ("text_encoder", "MiniMaxH3TextEncoderStep"),
-    ("denoise.no_keyframe_anchors", "MiniMaxH3NoKeyframeAnchorsStep"),
-    ("denoise.prepare_layout", "MiniMaxH3PrepareLayoutStep"),
-    ("denoise.prepare_latents", "MiniMaxH3PrepareLatentsStep"),
-    ("denoise.set_timesteps", "MiniMaxH3SetTimestepsStep"),
-    ("denoise.denoise", "MiniMaxH3DenoiseStep"),
-    *_TAIL,
-]
-# A keyframe adds the canvas block and the one block that encodes it; whether it anchors the first or the last frame
-# is a matter of the packed layout, not of which blocks run.
-FL2VA_WORKFLOW = [
-    ("before_encode", "MiniMaxH3ResizeStep"),
-    ("text_encoder", "MiniMaxH3FL2VATextEncoderStep"),
-    ("vae_encoder", "MiniMaxH3KeyframeVaeEncoderStep"),
-    ("denoise.prepare_layout", "MiniMaxH3PrepareLayoutStep"),
-    ("denoise.prepare_condition_latents", "MiniMaxH3PrepareConditionLatentsStep"),
-    ("denoise.prepare_latents", "MiniMaxH3PrepareLatentsStep"),
-    ("denoise.prepare_latents_fl2va", "MiniMaxH3FL2VAPrepareLatentsStep"),
-    ("denoise.set_timesteps", "MiniMaxH3SetTimestepsStep"),
-    ("denoise.denoise", "MiniMaxH3DenoiseStep"),
-    *_TAIL,
-]
-REF2VA_WORKFLOW = [
-    ("before_encode", "MiniMaxH3Ref2VASetupStep"),
-    ("text_encoder", "MiniMaxH3Ref2VATextEncoderStep"),
-    ("vae_encoder", "MiniMaxH3Ref2VAReferenceEncoderStep"),
-    ("denoise.prepare_layout", "MiniMaxH3Ref2VAPrepareLayoutStep"),
-    ("denoise.prepare_condition_latents", "MiniMaxH3PrepareConditionLatentsStep"),
-    ("denoise.prepare_latents", "MiniMaxH3PrepareLatentsStep"),
-    ("denoise.prepare_latents_ref2va", "MiniMaxH3Ref2VAPrepareLatentsStep"),
-    ("denoise.set_timesteps", "MiniMaxH3SetTimestepsStep"),
-    ("denoise.denoise", "MiniMaxH3Ref2VADenoiseStep"),
-    *_TAIL,
-]
+from ..test_modular_pipelines_common import ModularPipelineTesterMixin
+
+
+# The blocks every workflow of [`MiniMaxH3Blocks`] runs, in order. A keyframe adds the canvas block and the one
+# block that encodes it; whether it anchors the first or the last frame is a matter of the packed layout, not of
+# which blocks run, so `fl2va` covers both.
 MINIMAX_H3_WORKFLOWS = {
-    "t2va": T2VA_WORKFLOW,
-    "fl2va": FL2VA_WORKFLOW,
+    "t2va": [
+        ("text_encoder", "MiniMaxH3TextEncoderStep"),
+        ("denoise.no_keyframe_anchors", "MiniMaxH3NoKeyframeAnchorsStep"),
+        ("denoise.prepare_layout", "MiniMaxH3PrepareLayoutStep"),
+        ("denoise.prepare_latents", "MiniMaxH3PrepareLatentsStep"),
+        ("denoise.set_timesteps", "MiniMaxH3SetTimestepsStep"),
+        ("denoise.denoise", "MiniMaxH3DenoiseStep"),
+        ("denoise.after_denoise", "MiniMaxH3AfterDenoiseStep"),
+        ("decode.video", "MiniMaxH3VideoDecodeStep"),
+        ("decode.audio", "MiniMaxH3AudioDecodeStep"),
+    ],
+    "fl2va": [
+        ("before_encode", "MiniMaxH3ResizeStep"),
+        ("text_encoder", "MiniMaxH3FL2VATextEncoderStep"),
+        ("vae_encoder", "MiniMaxH3KeyframeVaeEncoderStep"),
+        ("denoise.prepare_layout", "MiniMaxH3PrepareLayoutStep"),
+        ("denoise.prepare_condition_latents", "MiniMaxH3PrepareConditionLatentsStep"),
+        ("denoise.prepare_latents", "MiniMaxH3PrepareLatentsStep"),
+        ("denoise.prepare_latents_fl2va", "MiniMaxH3FL2VAPrepareLatentsStep"),
+        ("denoise.set_timesteps", "MiniMaxH3SetTimestepsStep"),
+        ("denoise.denoise", "MiniMaxH3DenoiseStep"),
+        ("denoise.after_denoise", "MiniMaxH3AfterDenoiseStep"),
+        ("decode.video", "MiniMaxH3VideoDecodeStep"),
+        ("decode.audio", "MiniMaxH3AudioDecodeStep"),
+    ],
+}
+MINIMAX_H3_REF2VA_WORKFLOWS = {
+    "ref2va": [
+        ("before_encode", "MiniMaxH3Ref2VASetupStep"),
+        ("text_encoder", "MiniMaxH3Ref2VATextEncoderStep"),
+        ("vae_encoder", "MiniMaxH3Ref2VAReferenceEncoderStep"),
+        ("denoise.prepare_layout", "MiniMaxH3Ref2VAPrepareLayoutStep"),
+        ("denoise.prepare_condition_latents", "MiniMaxH3PrepareConditionLatentsStep"),
+        ("denoise.prepare_latents", "MiniMaxH3PrepareLatentsStep"),
+        ("denoise.prepare_latents_ref2va", "MiniMaxH3Ref2VAPrepareLatentsStep"),
+        ("denoise.set_timesteps", "MiniMaxH3SetTimestepsStep"),
+        ("denoise.denoise", "MiniMaxH3Ref2VADenoiseStep"),
+        ("denoise.after_denoise", "MiniMaxH3AfterDenoiseStep"),
+        ("decode.video", "MiniMaxH3VideoDecodeStep"),
+        ("decode.audio", "MiniMaxH3AudioDecodeStep"),
+    ],
 }
-MINIMAX_H3_REF2VA_WORKFLOWS = {"ref2va": REF2VA_WORKFLOW}
 
 # What each pruned workflow asks for, pinned explicitly: every component with its class (each half loads its own
-# transformer partition, nothing else differs) and every input — the optional ones with their defaults, the
-# required ones by name. MiniMax-H3 declares no pipeline-level configs, which the omitted `configs` key asserts.
+# transformer partition, nothing else differs), the pipeline configs it declares, and every input — the optional
+# ones with their defaults, the required ones by name.
 _SHARED_COMPONENTS = {
     "text_encoder": "Qwen3VLForConditionalGeneration",
     "tokenizer": "Qwen2Tokenizer",
@@ -116,6 +97,9 @@
     "audio_vae": "AutoencoderKLMiniMaxH3Audio",
     "video_processor": "VideoProcessor",
 }
+# The canvas MiniMax-H3 was released for. Every workflow resolves a canvas somewhere — from a keyframe, from a
+# reference or from the bare 16:9 default — so all three declare the rule as pipeline config.
+_SHARED_CONFIGS = {"canvas_short_edge": 768, "canvas_max_pixels": 768 * 1344}
 _SHARED_INPUTS = {
     "height": None,
     "width": None,
@@ -125,155 +109,56 @@
     "attention_kwargs": None,
     "output_type": "pil",
 }
-T2VA_DEFAULTS = {
-    "components": {**_SHARED_COMPONENTS, "transformer": "MiniMaxH3Transformer3DModel"},
-    "required_inputs": ["prompt", "num_inference_steps"],
-    "inputs": {**_SHARED_INPUTS, "num_frames": 124},
-}
-FL2VA_DEFAULTS = {
-    "components": {
-        **_SHARED_COMPONENTS,
-        "transformer": "MiniMaxH3Transformer3DModel",
-        "image_processor": "VaeImageProcessor",
+MINIMAX_H3_WORKFLOW_DEFAULTS = {
+    "t2va": {
+        "components": {**_SHARED_COMPONENTS, "transformer": "MiniMaxH3Transformer3DModel"},
+        "configs": _SHARED_CONFIGS,
+        "required_inputs": ["prompt", "num_inference_steps"],
+        "inputs": {**_SHARED_INPUTS, "num_frames": 124},
     },
-    "required_inputs": ["prompt", "num_inference_steps"],
-    "inputs": {**_SHARED_INPUTS, "num_frames": 124, "image": None, "last_image": None},
-}
-REF2VA_DEFAULTS = {
-    "components": {
-        **_SHARED_COMPONENTS,
-        "transformer_ref": "MiniMaxH3Transformer3DModel",
-        "image_processor": "VaeImageProcessor",
+    "fl2va": {
+        "components": {
+            **_SHARED_COMPONENTS,
+            "transformer": "MiniMaxH3Transformer3DModel",
+            "image_processor": "VaeImageProcessor",
+        },
+        "configs": _SHARED_CONFIGS,
+        "required_inputs": ["prompt", "num_inference_steps"],
+        "inputs": {**_SHARED_INPUTS, "num_frames": 124, "image": None, "last_image": None},
     },
-    # `num_frames` cannot default on ref2va: reference soundtracks are truncated to the generated duration, so a
-    # silent 124-frame default would cut them short. It is required instead.
-    "required_inputs": ["prompt", "references", "num_frames", "num_inference_steps"],
-    "inputs": _SHARED_INPUTS,
 }
-MINIMAX_H3_WORKFLOW_DEFAULTS = {
-    "t2va": T2VA_DEFAULTS,
-    "fl2va": FL2VA_DEFAULTS,
+MINIMAX_H3_REF2VA_WORKFLOW_DEFAULTS = {
+    "ref2va": {
+        "components": {
+            **_SHARED_COMPONENTS,
+            "transformer_ref": "MiniMaxH3Transformer3DModel",
+            "image_processor": "VaeImageProcessor",
+        },
+        "configs": _SHARED_CONFIGS,
+        # `num_frames` cannot default on ref2va: reference soundtracks are truncated to the generated duration, so a
+        # silent 124-frame default would cut them short. It is required instead.
+        "required_inputs": ["prompt", "references", "num_frames", "num_inference_steps"],
+        "inputs": _SHARED_INPUTS,
+    },
 }
-MINIMAX_H3_REF2VA_WORKFLOW_DEFAULTS = {"ref2va": REF2VA_DEFAULTS}
-
-
-def _video_frames(num_frames: int, size: int) -> np.ndarray:
-    """Synthesized video reference frames: `uint8` RGB at MiniMax-H3's own 24 fps."""
-    return (np.random.default_rng(0).random((num_frames, size, size, 3)) * 255).astype("uint8")
-
-
-def _waveform(duration: float) -> torch.Tensor:
-    """A synthesized soundtrack: a stereo waveform at the tiny audio VAE's own sample rate, so nothing is resampled."""
-    return torch.rand(2, round(duration * AUDIO_SAMPLE_RATE), generator=torch.Generator("cpu").manual_seed(1)) * 2 - 1
-
-
-def _reference_video(num_frames: int, size: int) -> MiniMaxH3VideoReference:
-    """A silent video reference at MiniMax-H3's own 24 fps."""
-    return MiniMaxH3VideoReference(frames=_video_frames(num_frames, size), fps=float(MINIMAX_H3_FPS))
-
-
-def _reference_audio(duration: float) -> MiniMaxH3AudioReference:
-    """A standalone audio reference at the tiny audio VAE's own sample rate."""
-    return MiniMaxH3AudioReference(audio=_waveform(duration), sample_rate=AUDIO_SAMPLE_RATE)
-
-
-# The synthesized media fixtures the file-decoding tests are built from: a tiny 8 fps clip with a stereo soundtrack.
-FIXTURE_FPS = 8.0
-FIXTURE_NUM_FRAMES = 8
-FIXTURE_SAMPLE_RATE = 8000
-
 
-def _write_video(path, with_audio: bool) -> None:
-    """Encode a tiny 64x32 clip, with a stereo soundtrack when asked, with PyAV."""
-    av = pytest.importorskip("av")
 
-    with av.open(str(path), "w") as container:
-        # Both streams are declared before anything is muxed, which is what the muxer needs to lay out the file.
-        video_stream = container.add_stream("libx264", rate=int(FIXTURE_FPS))
-        video_stream.width, video_stream.height, video_stream.pix_fmt = 64, 32, "yuv420p"
-        audio_stream = None
-        if with_audio:
-            audio_stream = container.add_stream("aac", rate=FIXTURE_SAMPLE_RATE)
-            audio_stream.codec_context.layout = "stereo"
+class TestMiniMaxH3ModularPipelineFast(ModularPipelineTesterMixin):
+    """The `t2va` and `fl2va` requests of [`MiniMaxH3Blocks`]: a prompt, optionally with keyframes."""
 
-        for index in range(FIXTURE_NUM_FRAMES):
-            pixels = np.full((32, 64, 3), index * 16, dtype="uint8")
-            frame = av.VideoFrame.from_ndarray(pixels, format="rgb24")
-            frame.pts = index
-            container.mux(video_stream.encode(frame))
-        container.mux(video_stream.encode())
-
-        if audio_stream is None:
-            return
-        num_samples = int(FIXTURE_NUM_FRAMES / FIXTURE_FPS * FIXTURE_SAMPLE_RATE)
-        samples = np.zeros((1, 2 * num_samples), dtype="int16")
-        frame = av.AudioFrame.from_ndarray(samples, format="s16", layout="stereo")
-        frame.sample_rate = FIXTURE_SAMPLE_RATE
-        resampler = av.audio.resampler.AudioResampler(format="fltp", layout="stereo", rate=FIXTURE_SAMPLE_RATE)
-        pts = 0
-        for resampled in resampler.resample(frame):
-            resampled.pts = pts
-            pts += resampled.samples
-            container.mux(audio_stream.encode(resampled))
-        container.mux(audio_stream.encode())
-
-
-def _media_fixtures(directory) -> tuple:
-    """A video with a soundtrack, a still image and an audio clip, as files a reference can be built from."""
-    av = pytest.importorskip("av")
-
-    video_path, image_path, audio_path = (
-        directory / "reference.mp4",
-        directory / "reference.png",
-        directory / "reference.wav",
-    )
-    _write_video(video_path, with_audio=True)
-    Image.new("RGB", (64, 32), color=(10, 20, 30)).save(image_path)
-    with av.open(str(audio_path), "w") as container:
-        stream = container.add_stream("pcm_s16le", rate=FIXTURE_SAMPLE_RATE)
-        stream.codec_context.layout = "stereo"
-        frame = av.AudioFrame.from_ndarray(
-            np.zeros((1, 2 * FIXTURE_SAMPLE_RATE), dtype="int16"), format="s16", layout="stereo"
-        )
-        frame.sample_rate = FIXTURE_SAMPLE_RATE
-        frame.pts = 0
-        container.mux(stream.encode(frame))
-        container.mux(stream.encode())
-    return video_path, image_path, audio_path
-
-
-@pytest.fixture(autouse=True, scope="module")
-def small_references():
-    """
-    Encode references at `TEST_REFERENCE_IMAGE_SHORT_EDGE` instead of the released 2048 pixels.
-
-    A 2048 pixel short edge packs thousands of conditioning rows, which is minutes per pipeline call on CPU. Every
-    request of this module passes `height` and `width`, so the canvas of a generated video is never derived from
-    these. `TestMiniMaxH3ReferenceGeometry` restores the released value where it pins it.
-    """
-    original_init = MiniMaxH3Ref2VASetupStep.__init__
-
-    def small_reference_init(self, *args, **kwargs):
-        kwargs.setdefault("reference_image_short_edge", TEST_REFERENCE_IMAGE_SHORT_EDGE)
-        original_init(self, *args, **kwargs)
-
-    with pytest.MonkeyPatch.context() as patch:
-        patch.setattr(MiniMaxH3Ref2VASetupStep, "__init__", small_reference_init)
-        patch.setattr(minimax_h3_geometry, "MINIMAX_H3_SHORT_EDGE", TEST_REFERENCE_IMAGE_SHORT_EDGE)
-        patch.setattr(minimax_h3_geometry, "MINIMAX_H3_MAX_PIXELS", TEST_REFERENCE_IMAGE_SHORT_EDGE**2 * 2)
-        yield
-
-
-class MiniMaxH3ModularTesterBase(ModularPipelineTesterMixin):
-    """What the two blocksets share: the repository, the output surface and the tests that do not apply."""
+    pipeline_class = MiniMaxH3ModularPipeline
+    pipeline_blocks_class = MiniMaxH3Blocks
+    pretrained_model_name_or_path = "hf-internal-testing/tiny-minimax-h3-modular-pipe"
 
-    pretrained_model_name_or_path = TINY_MODULAR_REPO_ID
+    params = frozenset(["prompt", "image", "last_image", "height", "width", "num_frames"])
     # MiniMax-H3 packs one request into one sequence and rejects a list of prompts, so nothing is batched.
     batch_params = frozenset()
     # The checkpoint is guidance-distilled and generates a video, so neither `guidance_scale` nor
     # `num_images_per_prompt` exists.
     optional_params = frozenset(["num_inference_steps", "latents", "output_type"])
     output_name = "videos"
+    expected_workflow_blocks = MINIMAX_H3_WORKFLOWS
+    expected_workflow_defaults = MINIMAX_H3_WORKFLOW_DEFAULTS
 
     @pytest.mark.skip(reason="MiniMax-H3 packs one request into one sequence, so a batch of prompts is not a thing.")
     def test_inference_batch_consistent(self):
@@ -287,42 +172,6 @@ def test_inference_batch_single_identical(self):
     def test_num_images_per_prompt(self):
         pass
 
-    def test_load_expected_components_from_pretrained(self, tmp_path):
-        r"""
-        Every component the repository holds *for this half* is loaded from it.
-
-        The repository holds both checkpoint partitions, as the released one does, so its index also names the
-        transformer of the other half — which these blocks never declare and must therefore never load.
-        """
-        pipe = self.get_pipeline()
-        specified = _get_specified_components(self.pretrained_model_name_or_path, cache_dir=tmp_path)
-
-        expected = {name for name in specified if name in pipe.components}
-        actual = {
-            name
-            for name in pipe.components
-            if getattr(pipe, name, None) is not None
-            and getattr(getattr(pipe, name), "_diffusers_load_id", None) not in (None, "null")
-        }
-
-        assert expected == actual, f"Component mismatch: missing={expected - actual}, unexpected={actual - expected}"
-        assert "transformer_ref" in specified and "transformer" in specified
-
-    def injected_noise(self, pipe, seed=3):
-        r"""The video and audio noise a request would otherwise draw, in the shapes the blocks expect back."""
-        latents = torch.randn(
-            1,
-            pipe.vae_latent_channels,
-            NUM_LATENT_FRAMES,
-            RESOLUTION // pipe.vae_spatial_compression_ratio,
-            RESOLUTION // pipe.vae_spatial_compression_ratio,
-            generator=torch.Generator("cpu").manual_seed(seed),
-        )
-        audio_latents = torch.randn(
-            2, pipe.audio_latent_channels, NUM_AUDIO_LATENTS, generator=torch.Generator("cpu").manual_seed(seed + 1)
-        )
-        return latents, audio_latents
-
     def test_duration_ceiling_holds_for_the_aligned_count(self):
         r"""
         346 frames are 14.417 seconds, but they are rounded up to 362, i.e. 15.083 seconds: the ceiling holds for the
@@ -336,23 +185,17 @@ def test_duration_ceiling_holds_for_the_aligned_count(self):
         with pytest.raises(ValueError, match="rounded up to 362"):
             pipe(**inputs)
 
-
-class TestMiniMaxH3ModularPipelineFast(MiniMaxH3ModularTesterBase):
-    pipeline_class = MiniMaxH3ModularPipeline
-    pipeline_blocks_class = MiniMaxH3Blocks
-
-    params = frozenset(["prompt", "image", "last_image", "height", "width", "num_frames"])
-    expected_workflow_blocks = MINIMAX_H3_WORKFLOWS
-    expected_workflow_defaults = MINIMAX_H3_WORKFLOW_DEFAULTS
-
     def get_dummy_inputs(self, seed=0):
         return {
             "prompt": "a robot dancing",
             "generator": self.get_generator(seed),
             "num_inference_steps": 2,
-            "height": RESOLUTION,
-            "width": RESOLUTION,
-            "num_frames": NUM_FRAMES,
+            # MiniMax-H3 generates 5 to 15 seconds at a fixed 24 fps, so 124 frames (`17 * 7 + 5`, the next length
+            # the video VAE can decode) is the shortest admissible request; a 32 pixel canvas is one `(1, 2, 2)`
+            # patch row per latent frame, which is what makes it affordable on CPU.
+            "height": 32,
+            "width": 32,
+            "num_frames": 124,
             "output_type": "pt",
         }
 
@@ -363,10 +206,11 @@ def test_video_and_audio_outputs(self):
         state = pipe(**self.get_dummy_inputs())
         video, audio = state.get("videos"), state.get("audio")
 
-        assert video.shape == (1, NUM_FRAMES, 3, RESOLUTION, RESOLUTION)
+        assert video.shape == (1, 124, 3, 32, 32)
         # The audio VAE is mono and takes the two stereo channels as two batch items, which the decoder block stacks
         # back into `(batch, 2, samples)`.
-        assert audio.shape == (1, 2, NUM_AUDIO_LATENTS * AUDIO_HOP_LENGTH)
+        # 207 audio latents at the tiny VAE's 4 samples per latent
+        assert audio.shape == (1, 2, 207 * 4)
         assert video.min() >= 0.0 and video.max() <= 1.0
         assert state.get("sampling_rate") == pipe.audio_vae.config.sampling_rate
 
@@ -381,7 +225,7 @@ def test_fl2va_keyframes(self, keyframes, num_condition_rows):
 
         They are packed in front of the generated video rows and ride along at their own `t = 0.999`. The loop only
         ever writes the generated rows, so the conditioning rows the encoder block produced survive it untouched,
-        which is what the denoised sequence is checked against here. On a `RESOLUTION` canvas a keyframe is a single
+        which is what the denoised sequence is checked against here. On a `32` canvas a keyframe is a single
         `(1, 2, 2)` patch row.
         """
         pipe = self.get_pipeline()
@@ -391,7 +235,7 @@ def test_fl2va_keyframes(self, keyframes, num_condition_rows):
         inputs.update(dict.fromkeys(keyframes, keyframe))
         state = pipe(**inputs)
 
-        assert state.get("videos").shape == (1, NUM_FRAMES, 3, RESOLUTION, RESOLUTION)
+        assert state.get("videos").shape == (1, 124, 3, 32, 32)
         assert state.get("num_condition_video_rows") == num_condition_rows
         condition_latents = state.get("condition_latents")
         assert condition_latents.shape[0] == num_condition_rows
@@ -402,9 +246,10 @@ def test_generator_reproducibility(self, with_keyframe):
         r"""
         Two runs from the same generator state are identical, two seeds differ.
 
-        The blocks draw from the one generator the request carries, in the order they run — the keyframe conditioning
-        noise in the VAE encoder step, then the video and the audio noise in the prepare-latents step — which is the
-        whole reproducibility contract of a request.
+        The blocks draw from the one generator the request carries, in the order they run — a keyframe's conditioning
+        noise in the prepare-condition-latents step, then the video and the audio noise in the prepare-latents step —
+        which is the whole reproducibility contract of a request. The keyframe's own VAE encode draws too, but under
+        a generator of its own seeded independently of the request, so it never shifts the streams after it.
         """
         pipe = self.get_pipeline()
         keyframe = Image.new("RGB", (48, 80))
@@ -434,7 +279,10 @@ def test_injected_latents_replace_the_draws(self):
         very same video and soundtrack.
         """
         pipe = self.get_pipeline()
-        latents, audio_latents = self.injected_noise(pipe)
+        # the noise the request would otherwise draw, in the shapes the tiny checkpoint expects back: 4 latent
+        # channels over 37 latent frames on the 32/16 canvas, and 8 audio latent channels over 207 latents
+        latents = torch.randn(1, 4, 37, 2, 2, generator=torch.Generator("cpu").manual_seed(3))
+        audio_latents = torch.randn(2, 8, 207, generator=torch.Generator("cpu").manual_seed(4))
 
         outputs = []
         for seed in (7, 8):
@@ -448,51 +296,32 @@ def test_injected_latents_replace_the_draws(self):
         assert torch.equal(outputs[0][0], outputs[1][0])
         assert torch.equal(outputs[0][1], outputs[1][1])
 
-    @pytest.mark.parametrize("num_keyframes", [0, 1, 2], ids=["text_only", "one_keyframe", "two_keyframes"])
-    def test_encode_prompt(self, num_keyframes):
-        r"""
-        The presentation is encoded in one conditioner call, whatever it carries.
-
-        A keyframe prepends a `"<Picture i>: "` label and a vision block, whose rows are tagged as *video*; a
-        text-only presentation is the verbatim prompt and is tagged as text throughout. Every vision block also makes
-        Qwen3-VL lay its rotary positions out per modality, which it reads off the `mm_token_type_ids` the processor
-        derives from the vision pad ids.
-        """
-        pipe = self.get_pipeline()
-        keyframe = Image.fromarray((np.random.default_rng(0).random((32, 32, 3)) * 255).astype("uint8"))
-
-        inputs = self.get_dummy_inputs()
-        if num_keyframes:
-            inputs["image"] = keyframe
-        if num_keyframes == 2:
-            inputs["last_image"] = keyframe
-        state = pipe(**inputs)
-        prompt_embeds, text_token_tags = state.get("prompt_embeds"), state.get("text_token_tags")
-
-        assert prompt_embeds.shape[0] == 1
-        assert prompt_embeds.shape[-1] == pipe.transformer.config.text_dim
-        assert prompt_embeds.shape[1] == text_token_tags.shape[0]
-        assert torch.isfinite(prompt_embeds).all()
-        # `0` tags a row of a vision block and `1` a text row, so a text-only presentation carries text rows alone.
-        assert set(text_token_tags.tolist()) == ({0, 1} if num_keyframes else {1})
-
-    def test_text_encoder_block_standalone(self):
+    @pytest.mark.parametrize("with_keyframes", [False, True], ids=["t2va", "fl2va"])
+    def test_text_encoder_block_standalone(self, with_keyframes):
         r"""
-        The text encoder block runs on its own, without the denoiser or the VAEs.
-
-        Encoding a presentation once and reusing it across requests is the modular way of passing `prompt_embeds`,
-        so the block may only touch the components it declares.
+        Either text encoder block runs on its own, without the denoiser or the VAEs, and encodes its presentation in
+        one conditioner call.
+
+        Encoding a presentation once and reusing it across requests is the modular way of passing `prompt_embeds`, so
+        a block may only touch the components it declares. `t2va` presents the prompt verbatim and tags every row as
+        text; `fl2va` prepends a `"<Picture i>: "` label and a vision block per keyframe, whose rows are tagged as
+        *video* — which is also what makes Qwen3-VL lay its rotary positions out per modality, off the
+        `mm_token_type_ids` the processor derives from the vision pad ids.
         """
-        pipe = MiniMaxH3TextEncoderStep().init_pipeline(self.pretrained_model_name_or_path)
+        keyframes = [Image.fromarray((np.random.default_rng(0).random((32, 32, 3)) * 255).astype("uint8"))] * 2
+        block = MiniMaxH3FL2VATextEncoderStep() if with_keyframes else MiniMaxH3TextEncoderStep()
+        pipe = block.init_pipeline(self.pretrained_model_name_or_path)
         pipe.load_components(dtype=torch.float32)
 
-        outputs = pipe(prompt="a robot dancing", output=["prompt_embeds", "text_token_tags"])
+        request = {"keyframes": keyframes} if with_keyframes else {}
+        outputs = pipe(prompt="a robot dancing", **request, output=["prompt_embeds", "text_token_tags"])
 
         assert set(pipe.components) == {"text_encoder", "tokenizer", "processor"}
         assert outputs["prompt_embeds"].shape[0] == 1
         assert outputs["prompt_embeds"].shape[1] == outputs["text_token_tags"].shape[0]
-        # `1` tags a text row, and a text-only presentation is the verbatim prompt.
-        assert set(outputs["text_token_tags"].tolist()) == {1}
+        assert torch.isfinite(outputs["prompt_embeds"]).all()
+        # `0` tags a row of a vision block and `1` a text row, so a text-only presentation carries text rows alone.
+        assert set(outputs["text_token_tags"].tolist()) == ({0, 1} if with_keyframes else {1})
 
     @pytest.mark.parametrize("output_type", ["np", "pil", "latent"])
     def test_output_type(self, output_type):
@@ -505,14 +334,14 @@ def test_output_type(self, output_type):
         video, audio = state.get("videos"), state.get("audio")
 
         if output_type == "np":
-            assert video.shape == (1, NUM_FRAMES, RESOLUTION, RESOLUTION, 3)
+            assert video.shape == (1, 124, 32, 32, 3)
         elif output_type == "pil":
-            assert len(video[0]) == NUM_FRAMES
-            assert video[0][0].size == (RESOLUTION, RESOLUTION)
+            assert len(video[0]) == 124
+            assert video[0][0].size == (32, 32)
         else:
             # The video as `(1, C, F, H, W)` and the audio channel-major.
-            assert video.shape == (1, 4, NUM_LATENT_FRAMES, RESOLUTION // 16, RESOLUTION // 16)
-            assert audio.shape == (2, 8, NUM_AUDIO_LATENTS)
+            assert video.shape == (1, 4, 37, 32 // 16, 32 // 16)
+            assert audio.shape == (2, 8, 207)
 
     @pytest.mark.parametrize(
         "overrides,message",
@@ -541,23 +370,84 @@ def test_check_inputs(self, overrides, message):
             pipe(**inputs)
 
 
-class TestMiniMaxH3Ref2VAModularPipelineFast(MiniMaxH3ModularTesterBase):
+class TestMiniMaxH3Ref2VAModularPipelineFast(ModularPipelineTesterMixin):
+    """The `ref2va` requests of [`MiniMaxH3Blocks`]: a prompt and an ordered list of references."""
+
     pipeline_class = MiniMaxH3ModularPipeline
     pipeline_blocks_class = MiniMaxH3Blocks
+    pretrained_model_name_or_path = "hf-internal-testing/tiny-minimax-h3-modular-pipe"
 
     params = frozenset(["prompt", "references", "height", "width", "num_frames"])
+    # MiniMax-H3 packs one request into one sequence and rejects a list of prompts, so nothing is batched.
+    batch_params = frozenset()
+    # The checkpoint is guidance-distilled and generates a video, so neither `guidance_scale` nor
+    # `num_images_per_prompt` exists.
+    optional_params = frozenset(["num_inference_steps", "latents", "output_type"])
+    output_name = "videos"
     expected_workflow_blocks = MINIMAX_H3_REF2VA_WORKFLOWS
     expected_workflow_defaults = MINIMAX_H3_REF2VA_WORKFLOW_DEFAULTS
 
+    def get_pipeline(self, components_manager=None, dtype=torch.float32):
+        r"""
+        Normalize references onto a 64 pixel short edge instead of MiniMax-H3's own resolutions.
+
+        A reference is put on a canvas of its own, and both released sizes pack thousands of conditioning rows —
+        minutes per pipeline call on CPU. The two follow different rules, so both are made small: an image reference
+        by the setup step's own `reference_image_short_edge`, which is why the block is swapped for a configured one,
+        and a video reference by the canvas rule it shares with the generated video, which is pipeline config. Every
+        request here passes `height` and `width`, so shrinking the shared rule never touches a generated canvas.
+        """
+        blocks = self.pipeline_blocks_class()
+        blocks.sub_blocks["before_encode"].sub_blocks["ref2va"] = MiniMaxH3Ref2VASetupStep(
+            reference_image_short_edge=64
+        )
+
+        pipeline = blocks.init_pipeline(self.pretrained_model_name_or_path, components_manager=components_manager)
+        pipeline.update_components(canvas_short_edge=64, canvas_max_pixels=64**2 * 2)
+        pipeline.load_components(dtype=dtype)
+        pipeline.set_progress_bar_config(disable=None)
+        return pipeline
+
+    @pytest.mark.skip(reason="MiniMax-H3 packs one request into one sequence, so a batch of prompts is not a thing.")
+    def test_inference_batch_consistent(self):
+        pass
+
+    @pytest.mark.skip(reason="MiniMax-H3 packs one request into one sequence, so a batch of prompts is not a thing.")
+    def test_inference_batch_single_identical(self):
+        pass
+
+    @pytest.mark.skip(reason="One request generates one video, so there is no `num_images_per_prompt`.")
+    def test_num_images_per_prompt(self):
+        pass
+
+    def test_duration_ceiling_holds_for_the_aligned_count(self):
+        r"""
+        346 frames are 14.417 seconds, but they are rounded up to 362, i.e. 15.083 seconds: the ceiling holds for the
+        aligned count, so this is rejected rather than silently generating too long a video.
+
+        `ref2va` resolves and checks the frame count in its setup step rather than in the layout step, so the two
+        halves reach this ceiling by different code.
+        """
+        pipe = self.get_pipeline()
+
+        inputs = self.get_dummy_inputs()
+        inputs["num_frames"] = 346
+
+        with pytest.raises(ValueError, match="rounded up to 362"):
+            pipe(**inputs)
+
     def get_dummy_inputs(self, seed=0):
         return {
             "prompt": "a robot dancing",
             "references": [MiniMaxH3ImageReference(image=Image.new("RGB", (48, 80)))],
             "generator": self.get_generator(seed),
             "num_inference_steps": 2,
-            "height": RESOLUTION,
-            "width": RESOLUTION,
-            "num_frames": NUM_FRAMES,
+            # MiniMax-H3 generates 5 to 15 seconds at a fixed 24 fps, so 124 frames (`17 * 7 + 5`, the next length
+            # the video VAE can decode) is the shortest admissible request; a 32 pixel canvas is one `(1, 2, 2)`
+            # patch row per latent frame, which is what makes it affordable on CPU.
+            "height": 32,
+            "width": 32,
+            "num_frames": 124,
             "output_type": "pt",
         }
 
@@ -568,8 +458,9 @@ def test_video_and_audio_outputs(self):
         state = pipe(**self.get_dummy_inputs())
         video, audio = state.get("videos"), state.get("audio")
 
-        assert video.shape == (1, NUM_FRAMES, 3, RESOLUTION, RESOLUTION)
-        assert audio.shape == (1, 2, NUM_AUDIO_LATENTS * AUDIO_HOP_LENGTH)
+        assert video.shape == (1, 124, 3, 32, 32)
+        # 207 audio latents at the tiny VAE's 4 samples per latent
+        assert audio.shape == (1, 2, 207 * 4)
         assert video.min() >= 0.0 and video.max() <= 1.0
 
     def test_generator_reproducibility(self):
@@ -605,8 +496,12 @@ def test_injected_latents_replace_the_draws(self):
         same noise is still another sample, through the conditioning noise the references are augmented with.
         """
         pipe = self.get_pipeline()
-        latents, audio_latents = self.injected_noise(pipe)
-        other_latents, other_audio_latents = self.injected_noise(pipe, seed=11)
+        # the noise the request would otherwise draw, in the shapes the tiny checkpoint expects back: 4 latent
+        # channels over 37 latent frames on the 32/16 canvas, and 8 audio latent channels over 207 latents
+        latents = torch.randn(1, 4, 37, 2, 2, generator=torch.Generator("cpu").manual_seed(3))
+        audio_latents = torch.randn(2, 8, 207, generator=torch.Generator("cpu").manual_seed(4))
+        other_latents = torch.randn(1, 4, 37, 2, 2, generator=torch.Generator("cpu").manual_seed(11))
+        other_audio_latents = torch.randn(2, 8, 207, generator=torch.Generator("cpu").manual_seed(12))
 
         def run(seed, video_noise, audio_noise):
             inputs = self.get_dummy_inputs()
@@ -629,7 +524,7 @@ def run(seed, video_noise, audio_noise):
 
     @pytest.mark.parametrize(
         "kinds,num_frames",
-        [(("video",), NUM_FRAMES), (("image", "audio"), NUM_FRAMES), (("video", "image"), NUM_FRAMES)],
+        [(("video",), 124), (("image", "audio"), 124), (("video", "image"), 124)],
         ids=["video", "image_audio", "video_image"],
     )
     def test_reference_combinations(self, kinds, num_frames):
@@ -646,14 +541,18 @@ def test_reference_combinations(self, kinds, num_frames):
         """
         media = {
             "image": MiniMaxH3ImageReference(image=Image.new("RGB", (48, 80))),
-            # A one-second video reference, soundtrack included, and a six-second standalone soundtrack.
+            # A one-second video reference, soundtrack included, and a six-second standalone soundtrack. Both
+            # waveforms are at 160 Hz, the tiny audio VAE's own rate, so nothing is ever resampled.
             "video": MiniMaxH3VideoReference(
-                frames=_video_frames(MINIMAX_H3_FPS, 64),
+                frames=(np.random.default_rng(0).random((MINIMAX_H3_FPS, 64, 64, 3)) * 255).astype("uint8"),
                 fps=float(MINIMAX_H3_FPS),
-                audio=_waveform(1.0),
-                sample_rate=AUDIO_SAMPLE_RATE,
+                audio=torch.rand(2, 160, generator=torch.Generator("cpu").manual_seed(1)) * 2 - 1,
+                sample_rate=160,
+            ),
+            "audio": MiniMaxH3AudioReference(
+                audio=torch.rand(2, 6 * 160, generator=torch.Generator("cpu").manual_seed(1)) * 2 - 1,
+                sample_rate=160,
             ),
-            "audio": _reference_audio(6.0),
         }
 
         pipe = self.get_pipeline()
@@ -667,7 +566,7 @@ def test_reference_combinations(self, kinds, num_frames):
         num_audio_condition_rows = state.get("num_condition_audio_rows")
         assert num_condition_rows > 0
         assert (num_audio_condition_rows > 0) == any(kind in ("video", "audio") for kind in kinds)
-        assert state.get("videos").shape == (1, state.get("num_frames"), 3, RESOLUTION, RESOLUTION)
+        assert state.get("videos").shape == (1, state.get("num_frames"), 3, 32, 32)
         # The loop only ever writes the generated rows, so the anchors the encoder block produced survive it.
         assert torch.equal(state.get("latents")[:num_condition_rows], state.get("condition_latents"))
         if num_audio_condition_rows:
@@ -678,23 +577,38 @@ def test_reference_combinations(self, kinds, num_frames):
     @pytest.mark.parametrize(
         "kinds", [("image",), ("video",), ("video", "image")], ids=["image", "video", "video_image"]
     )
-    def test_encode_prompt(self, kinds):
+    def test_text_encoder_block_standalone(self, kinds):
         r"""
-        The presentation is encoded in one conditioner call, whatever references it labels.
-
-        The rows of a reference's vision block are tagged as *video*, and those blocks are what makes Qwen3-VL lay its
-        rotary positions out per modality run, which it reads off the `mm_token_type_ids` the processor derives from
-        the vision pad ids. A video reference contributes one timestamped block per merged frame pair.
+        The `ref2va` text encoder block runs on its own, without the denoiser or the VAEs, and encodes its
+        presentation in one conditioner call whatever references it labels.
+
+        Encoding a presentation once and reusing it across requests is the modular way of passing `prompt_embeds`, so
+        the block may only touch the components it declares. The rows of a reference's vision block are tagged as
+        *video*, and those blocks are what makes Qwen3-VL lay its rotary positions out per modality run, which it
+        reads off the `mm_token_type_ids` the processor derives from the vision pad ids. A video reference
+        contributes one timestamped block per merged frame pair.
         """
-        pipe = self.get_pipeline()
-        media = {"image": MiniMaxH3ImageReference(image=Image.new("RGB", (48, 80))), "video": _reference_video(25, 32)}
-        inputs = self.get_dummy_inputs()
-        inputs["references"] = [media[kind] for kind in kinds]
-        state = pipe(**inputs)
-        prompt_embeds, text_token_tags = state.get("prompt_embeds"), state.get("text_token_tags")
+        media = {
+            "image": MiniMaxH3ImageReference(image=Image.new("RGB", (48, 80))),
+            "video": MiniMaxH3VideoReference(
+                frames=(np.random.default_rng(0).random((25, 32, 32, 3)) * 255).astype("uint8"),
+                fps=float(MINIMAX_H3_FPS),
+            ),
+        }
+        pipe = MiniMaxH3Ref2VATextEncoderStep().init_pipeline(self.pretrained_model_name_or_path)
+        pipe.load_components(dtype=torch.float32)
+
+        outputs = pipe(
+            prompt="a robot dancing",
+            # the block reads the references the setup step normalized, which for the conditioner is media of any
+            # accepted layout at the model's own rates — what these already are
+            normalized_references=[media[kind] for kind in kinds],
+            output=["prompt_embeds", "text_token_tags"],
+        )
+        prompt_embeds, text_token_tags = outputs["prompt_embeds"], outputs["text_token_tags"]
 
+        assert set(pipe.components) == {"text_encoder", "tokenizer", "processor"}
         assert prompt_embeds.shape[0] == 1
-        assert prompt_embeds.shape[-1] == pipe.transformer_ref.config.text_dim
         assert prompt_embeds.shape[1] == text_token_tags.shape[0]
         assert torch.isfinite(prompt_embeds).all()
         # `0` tags a row of a vision block and `1` a text row, and every reference here carries a vision block.
@@ -709,7 +623,7 @@ def test_reference_media_layouts(self, media_type):
         VAE untouched.
         """
         pipe = self.get_pipeline()
-        pixels = _video_frames(4, TEST_REFERENCE_IMAGE_SHORT_EDGE)
+        pixels = (np.random.default_rng(0).random((4, 64, 64, 3)) * 255).astype("uint8")
         if media_type == "pil":
             image, frames = Image.fromarray(pixels[0]), [Image.fromarray(frame) for frame in pixels]
         elif media_type == "np":
@@ -728,14 +642,15 @@ def test_reference_media_layouts(self, media_type):
         assert np.array_equal(np.asarray(references[0].image), pixels[0])
         assert np.array_equal(references[1].frames, pixels)
 
-    def test_reference_rates_default_to_the_model_rates(self):
+    def test_reference_without_rates_is_not_resampled(self):
         r"""
-        A reference that leaves its rates out is taken to already be at MiniMax-H3's own: the frames flow through
-        untouched, without a resampling pass and without a copy, and so do the samples of a waveform.
+        A reference that leaves its rates out is taken to already be at MiniMax-H3's own — 24 fps for frames, the
+        audio VAE's own sample rate for a waveform — so neither normalization pass runs at all: the frames flow
+        through without a resampling pass and without a copy, and so do the samples of a waveform.
         """
         pipe = self.get_pipeline()
-        frames = _video_frames(NUM_FRAMES, TEST_REFERENCE_IMAGE_SHORT_EDGE)
-        waveform = _waveform(2.0)
+        frames = (np.random.default_rng(0).random((124, 64, 64, 3)) * 255).astype("uint8")
+        waveform = torch.rand(2, 2 * 160, generator=torch.Generator("cpu").manual_seed(1)) * 2 - 1
 
         inputs = self.get_dummy_inputs()
         inputs["references"] = [MiniMaxH3VideoReference(frames=frames), MiniMaxH3AudioReference(audio=waveform)]
@@ -748,12 +663,12 @@ def test_reference_rates_default_to_the_model_rates(self):
     def test_reference_sample_rate_override_resamples(self):
         r"""A waveform that says it carries another rate is resampled onto the audio VAE's own."""
         pipe = self.get_pipeline()
-        waveform = _waveform(2.0)
+        waveform = torch.rand(2, 2 * 160, generator=torch.Generator("cpu").manual_seed(1)) * 2 - 1
 
         inputs = self.get_dummy_inputs()
         inputs["references"] = [
             MiniMaxH3ImageReference(image=Image.new("RGB", (48, 80))),
-            MiniMaxH3AudioReference(audio=waveform, sample_rate=AUDIO_SAMPLE_RATE // 2),
+            MiniMaxH3AudioReference(audio=waveform, sample_rate=160 // 2),
         ]
         state = pipe(**inputs)
         references = state.get("normalized_references")
@@ -773,125 +688,60 @@ def test_check_inputs_references(self, references, message):
 
 class TestMiniMaxH3Reference:
     """
-    The three reference dataclasses, which hold in-memory media and the rate it carries.
+    The three reference dataclasses and the passes that normalize them, neither of which needs a checkpoint.
 
-    Each knows its own modality, so nothing has to derive it from which fields happen to be set, and the fields a
-    modality has no use for do not exist on it.
+    Each class knows its own modality, so nothing has to derive it from which fields happen to be set, and the
+    fields a modality has no use for do not exist on it. The rest is the pure geometry `MiniMaxH3Ref2VASetupStep`
+    and the text encoder run a reference through before any VAE or conditioner sees it.
     """
 
     def test_reference_defaults(self):
-        r"""A reference knows its own modality, and defaults to MiniMax-H3's own frame rate for its frames."""
-        assert MiniMaxH3VideoReference(frames=_video_frames(2, 32)).fps == float(MINIMAX_H3_FPS)
+        r"""
+        A reference knows its own modality, and defaults to MiniMax-H3's own frame rate for its frames.
+
+        `kind` and `has_audio` are what the setup step and the layout branch on, so each class has to answer both
+        from its type alone rather than from which fields happen to be set.
+        """
+        frames = (np.random.default_rng(0).random((2, 32, 32, 3)) * 255).astype("uint8")
+        waveform = torch.rand(2, 6 * 160, generator=torch.Generator("cpu").manual_seed(1)) * 2 - 1
+
+        # frames handed over without a rate are taken to already be at MiniMax-H3's own 24 fps
+        assert MiniMaxH3VideoReference(frames=frames).fps == float(MINIMAX_H3_FPS)
+
+        # an image conditions on one still: it is a video condition of a single frame, and never an audio one
         assert MiniMaxH3ImageReference(image=Image.new("RGB", (32, 32))).kind == "image"
         assert not MiniMaxH3ImageReference(image=Image.new("RGB", (32, 32))).has_audio
-        assert _reference_video(2, 32).kind == "video"
-        assert not _reference_video(2, 32).has_audio
-        assert _reference_audio(6.0).kind == "audio"
-        assert _reference_audio(6.0).has_audio
+
+        # a video conditions on its motion, and on a soundtrack only when it was given one — this one is silent
+        assert MiniMaxH3VideoReference(frames=frames).kind == "video"
+        assert not MiniMaxH3VideoReference(frames=frames).has_audio
+
+        # a standalone clip is the one kind that is audio-only, so it always contributes audio rows
+        assert MiniMaxH3AudioReference(audio=waveform, sample_rate=160).kind == "audio"
+        assert MiniMaxH3AudioReference(audio=waveform, sample_rate=160).has_audio
 
     def test_video_reference_has_audio_follows_its_soundtrack(self):
         r"""A video reference contributes audio rows exactly when it was given a soundtrack of its own."""
-        frames = _video_frames(2, 32)
+        frames = (np.random.default_rng(0).random((2, 32, 32, 3)) * 255).astype("uint8")
+        waveform = torch.rand(2, 160, generator=torch.Generator("cpu").manual_seed(1)) * 2 - 1
 
         assert not MiniMaxH3VideoReference(frames=frames).has_audio
-        assert MiniMaxH3VideoReference(frames=frames, audio=_waveform(1.0)).has_audio
+        assert MiniMaxH3VideoReference(frames=frames, audio=waveform).has_audio
 
     def test_a_modality_only_carries_its_own_fields(self):
         r"""
         The fields that used to be dead weight are gone: an image reference has no rates, and no reference can be
         built holding two media at once.
         """
+        frames = (np.random.default_rng(0).random((2, 32, 32, 3)) * 255).astype("uint8")
+        waveform = torch.rand(2, 160, generator=torch.Generator("cpu").manual_seed(1)) * 2 - 1
         image = MiniMaxH3ImageReference(image=Image.new("RGB", (32, 32)))
 
         assert not hasattr(image, "fps") and not hasattr(image, "sample_rate")
         with pytest.raises(TypeError):
-            MiniMaxH3ImageReference(image=Image.new("RGB", (32, 32)), audio=_waveform(1.0))
+            MiniMaxH3ImageReference(image=Image.new("RGB", (32, 32)), audio=waveform)
         with pytest.raises(TypeError):
-            MiniMaxH3AudioReference(audio=_waveform(1.0), frames=_video_frames(2, 32))
-
-
-class TestMiniMaxH3ReferenceLoading:
-    """
-    Decoding references off the filesystem, which is the caller's job rather than the blocks'.
-
-    None of this needs a checkpoint: [`MiniMaxH3VideoReference.from_file`] and [`MiniMaxH3AudioReference.from_file`]
-    read a container with PyAV and return a reference carrying the rates it reports.
-    """
-
-    def test_decode_video_carries_frames_rate_and_soundtrack(self, tmp_path):
-        r"""
-        A decoded video brings the three things the model conditions on: the frames, the rate they were shot at, and
-        the container's soundtrack as this reference's own.
-        """
-        video_path, _, _ = _media_fixtures(tmp_path)
-
-        video = MiniMaxH3VideoReference.from_file(video_path)
-
-        assert isinstance(video, MiniMaxH3VideoReference) and video.kind == "video"
-        assert video.frames.shape == (FIXTURE_NUM_FRAMES, 32, 64, 3) and video.frames.dtype == np.uint8
-        assert video.fps == FIXTURE_FPS
-        assert video.has_audio and video.audio.shape[0] == 2 and video.sample_rate == FIXTURE_SAMPLE_RATE
-
-    def test_decode_audio_carries_the_sample_rate(self, tmp_path):
-        r"""A decoded audio file brings the rate its samples are at, which is what they are resampled from."""
-        _, _, audio_path = _media_fixtures(tmp_path)
-
-        audio = MiniMaxH3AudioReference.from_file(audio_path)
-
-        assert isinstance(audio, MiniMaxH3AudioReference) and audio.kind == "audio"
-        assert audio.audio.shape[0] == 2 and audio.audio.dtype == torch.float32
-        assert audio.sample_rate == FIXTURE_SAMPLE_RATE
-
-    def test_decoded_rates_can_be_corrected(self, tmp_path):
-        r"""A container whose metadata is wrong is corrected on the reference the decode returned."""
-        video_path, _, _ = _media_fixtures(tmp_path)
-
-        video = MiniMaxH3VideoReference.from_file(video_path)
-        video.fps = 12.0
-
-        assert video.fps == 12.0 and video.sample_rate == FIXTURE_SAMPLE_RATE
-
-    def test_decode_silent_video_carries_no_soundtrack(self, tmp_path):
-        r"""There is nothing to adopt from a container without an audio stream."""
-        silent_path = tmp_path / "silent.mp4"
-        _write_video(silent_path, with_audio=False)
-
-        reference = MiniMaxH3VideoReference.from_file(silent_path)
-
-        assert not reference.has_audio and reference.sample_rate is None
-        assert reference.fps == FIXTURE_FPS
-
-    def test_decoding_needs_pyav(self, tmp_path, monkeypatch):
-        r"""Decoding a video or an audio file is a PyAV job, and says so when PyAV is not installed."""
-        video_path, _, audio_path = _media_fixtures(tmp_path)
-        monkeypatch.setattr(minimax_h3_references, "is_av_available", lambda: False)
-
-        with pytest.raises(ImportError, match="pip install av"):
-            MiniMaxH3VideoReference.from_file(video_path)
-        with pytest.raises(ImportError, match="pip install av"):
-            MiniMaxH3AudioReference.from_file(audio_path)
-
-    @pytest.mark.parametrize(
-        "loader,path",
-        [
-            (MiniMaxH3ImageReference.from_file, "missing.png"),
-            (MiniMaxH3VideoReference.from_file, "missing.mp4"),
-            (MiniMaxH3AudioReference.from_file, "missing.wav"),
-        ],
-        ids=["image", "video", "audio"],
-    )
-    def test_from_file_needs_a_real_path(self, loader, path):
-        r"""The path has to name a file it can open, or a URL."""
-        with pytest.raises(ValueError, match="not a valid path"):
-            loader(path)
-
-
-class TestMiniMaxH3ReferenceGeometry:
-    """
-    How a reference is prepared, which is pure geometry and needs no checkpoint.
-
-    These are the passes `MiniMaxH3Ref2VASetupStep` runs a reference through before any VAE sees it.
-    """
+            MiniMaxH3AudioReference(audio=waveform, frames=frames)
 
     def test_video_reference_vision_blocks(self):
         r"""
@@ -901,7 +751,10 @@ def test_video_reference_vision_blocks(self):
         A 25 frame reference at 24 fps samples three frames, which merge into two blocks at 0.25 and 1.0 seconds.
         """
         frames, timestamps = MiniMaxH3Ref2VATextEncoderStep._sample_video_condition_frames(
-            _video_frames(25, 32), fps=24.0, sample_fps=2.0, temporal_patch=2
+            (np.random.default_rng(0).random((25, 32, 32, 3)) * 255).astype("uint8"),
+            fps=24.0,
+            sample_fps=2.0,
+            temporal_patch=2,
         )
 
         assert len(frames) == 3
@@ -930,20 +783,19 @@ def test_video_reference_resampled_to_the_model_frame_rate(self):
         output slot is dropped, so a 30 fps reference loses one frame in five, the later of the two that tie for a
         slot. Frames already at 24 fps are returned as they are, without a copy.
         """
-        # Every frame carries its own index as its pixel value, so the resampled frames name the ones that
-        # survived. The frames sit at the canvas their aspect resolves to under the `small_references` fixture, so
-        # the resize pass is a no-op and the 24 fps route returns the input without a copy.
-        size = TEST_REFERENCE_IMAGE_SHORT_EDGE
+        # Every frame carries its own index as its pixel value, so the resampled frames name the ones that survived.
+        # The canvas rule is passed shrunken so the frames already sit at the canvas their aspect resolves to, which
+        # makes the resize pass a no-op and lets the 24 fps route return the input without a copy.
+        size = 64
         frames = np.arange(30, dtype="uint8").reshape(-1, 1, 1, 1) * np.ones((1, size, size, 3), dtype="uint8")
+        canvas = {"canvas_multiple": 32, "canvas_short_edge": 64, "canvas_max_pixels": 64**2 * 2}
 
-        resampled = MiniMaxH3Ref2VASetupStep._normalize_video_condition(
-            frames, fps=30.0, num_frames=NUM_FRAMES, canvas_multiple=32
-        )
+        resampled = MiniMaxH3Ref2VASetupStep._normalize_video_condition(frames, fps=30.0, num_frames=124, **canvas)
 
         assert [int(frame[0, 0, 0]) for frame in resampled] == [
             index for index in range(30) if index not in (2, 7, 12, 17, 22, 27)
         ]
         untouched = MiniMaxH3Ref2VASetupStep._normalize_video_condition(
-            frames, fps=float(MINIMAX_H3_FPS), num_frames=NUM_FRAMES, canvas_multiple=32
+            frames, fps=float(MINIMAX_H3_FPS), num_frames=124, **canvas
         )
         assert np.shares_memory(untouched, frames)

From c4f9ad5a81728ef94da27242480de4520d048ac2 Mon Sep 17 00:00:00 2001
From: yiyixuxu <yixu310@gmail.com>
Date: Tue, 4 Aug 2026 21:25:57 +0000
Subject: [PATCH 16/16] Make every MiniMax-H3 docs example one that runs
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The page's examples called `pipe.to("cuda")`, which cannot work: the
checkpoint is ~134GB in bfloat16 and no single card holds it. Both now
register their components in a `ComponentsManager` with auto offloading,
which is the recipe the page's own Memory section documents.

The `t2va` and `fl2va` snippets passed no `num_frames`. They build the
pipeline without a `workflow=`, so the un-pruned signature merges the
input to None — `MiniMaxH3Ref2VASetupStep` declares it required with no
default and wins the first declaration over the layout step's 124 — and
the layout step reads that None rather than its own default. Fixed
upstream by #14234, which is not in this base yet, so both calls pass
`num_frames` explicitly until it is.

Also: the loading section now separates picking a workflow from loading
one, a tip introduces `pipe.doc`, the conditioner note moves up beside
the rest of the checkpoint layout, and the generation-as-a-reference
example loads both partitions in one call instead of describing a second
call it no longer makes.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---
 docs/source/en/api/pipelines/minimax_h3.md | 52 +++++++++++++---------
 1 file changed, 31 insertions(+), 21 deletions(-)

diff --git a/docs/source/en/api/pipelines/minimax_h3.md b/docs/source/en/api/pipelines/minimax_h3.md
index d2440fa09680..4d815156b2a5 100644
--- a/docs/source/en/api/pipelines/minimax_h3.md
+++ b/docs/source/en/api/pipelines/minimax_h3.md
@@ -34,7 +34,9 @@ MiniMax-H3 was released as two checkpoint partitions that share every component
 
 Everything but the transformer, i.e. the video VAE, the audio VAE, the Qwen3-VL conditioner, its tokenizer and processor, and the two schedulers, is shared and stored once.
 
-All three tasks are workflows of the one [`MiniMaxH3Blocks`], and the repository carries one `modular_model_index.json` naming every component with its own loading spec. To serve a single task, pass the workflow to `from_pretrained`: it keeps only that workflow's blocks, so the pipeline's signature (`pipe.blocks.doc`) documents exactly that task's inputs, only that task's components are declared, and `load_components` fetches exactly their subfolders — a `t2va` / `fl2va` pipeline never touches `transformer_ref/`, a `ref2va` one never touches `transformer/`.
+The conditioner is a `Qwen3VLForConditionalGeneration`, and MiniMax-H3 reads the *unnormalized* hidden state after its 50th decoder layer rather than the last one, so the full released checkpoint is used with its language-model head unused.
+
+All three tasks are workflows of the one [`MiniMaxH3Blocks`], and the repository carries one `modular_model_index.json` naming every component with its own loading spec. To serve a single task, pass the workflow to `from_pretrained`: it keeps only that workflow's blocks, so the pipeline's signature (`pipe.doc`) documents exactly that task's inputs, only that task's components are declared, and `load_components` fetches exactly their subfolders — a `t2va` / `fl2va` pipeline never touches `transformer_ref/`, a `ref2va` one never touches `transformer/`.
 
 ```py
 import torch
@@ -44,18 +46,22 @@ pipe = ModularPipeline.from_pretrained("MiniMaxAI/MiniMax-H3", workflow="ref2va"
 pipe.load_components(dtype=torch.bfloat16)
 ```
 
-To keep every workflow available on one pipeline instead, load the full blockset — it picks the workflow per call from the inputs it is passed — and restrict the *loading* per workflow with `load_components(workflow=...)`:
+> [!TIP]
+> `pipe.doc` prints what the pipeline in front of you takes and returns — every input with its default, the components it expects and the outputs it produces. Pruned to one workflow it describes exactly that task, which is the quickest way to see what a request needs before making one.
+
+To keep every workflow available on one pipeline instead, leave the `workflow` argument out: the pipeline then picks the workflow per call from the inputs it is passed.
 
 ```py
 pipe = ModularPipeline.from_pretrained("MiniMaxAI/MiniMax-H3")
+```
+
+The *loading* can still go one workflow at a time. This one call fetches `transformer/` and every shared component, which serves both `t2va` and `fl2va`:
 
-# loads `transformer/` and every shared component — this one call serves `t2va` and `fl2va`
+```py
 pipe.load_components(workflow="t2va", dtype=torch.bfloat16)
 ```
 
-A plain `load_components()` with no `workflow=` pulls **both** 61.7GB transformer partitions. That is a deliberate choice when a [`ComponentsManager`] with auto offloading manages the memory: the weights live in host RAM, the manager moves onto the accelerator just what each step needs, and switching workflows takes no extra call — when the `ref2va` denoiser wants the device, the strategy offloads the smallest set of components that frees enough room, which tends to be the idle `transformer/` partition rather than the (slightly larger) conditioner. See [Memory](#memory) for the recipes.
-
-The conditioner is a `Qwen3VLForConditionalGeneration`, and MiniMax-H3 reads the *unnormalized* hidden state after its 50th decoder layer rather than the last one, so the full released checkpoint is used with its language-model head unused.
+A plain `load_components()` with no `workflow=` pulls **both** 61.7GB transformer partitions, which is what lets one pipeline serve all three workflows without another loading call. Pair it with a [`ComponentsManager`] and auto offloading: the weights live in host RAM and the manager moves onto the accelerator just what each step needs, so when the `ref2va` denoiser wants the device the strategy offloads whatever frees enough room. See [Memory](#memory) for the recipes.
 
 ## Two schedulers
 
@@ -162,26 +168,30 @@ Two 80 GB cards run full bfloat16 this way with nothing streaming; two 48 GB car
 
 ```py
 import torch
-from diffusers import ModularPipeline
+from diffusers import ComponentsManager, ModularPipeline
 from diffusers.utils import load_image
 from diffusers.utils.export_utils import encode_video
 
-pipe = ModularPipeline.from_pretrained("MiniMaxAI/MiniMax-H3")
+# 61.7GB of transformer and 62.1GB of conditioner do not sit on one accelerator, so the components are
+# registered in a manager that moves each one on and off as the blocks reach it. See [Memory](#memory).
+manager = ComponentsManager()
+manager.enable_auto_cpu_offload(device="cuda")
+
+pipe = ModularPipeline.from_pretrained("MiniMaxAI/MiniMax-H3", components_manager=manager)
 pipe.load_components(workflow="fl2va", dtype=torch.bfloat16)
-pipe.to("cuda")
 
 prompt = "A red fox trotting through a snowy pine forest, snow crunching underfoot"
 # `output=` returns exactly the named outputs instead of the whole pipeline state.
 outputs = ["videos", "audio", "sampling_rate"]
 
 # Text to video + audio.
-results = pipe(prompt=prompt, generator=torch.Generator().manual_seed(42), output=outputs)
+results = pipe(prompt=prompt, num_frames=124, generator=torch.Generator().manual_seed(42), output=outputs)
 
 # First frame (and optionally last frame) to video + audio. The canvas follows the first keyframe.
 image = load_image(
     "https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/diffusers/astronaut.jpg"
 )
-results = pipe(prompt=prompt, image=image, generator=torch.Generator().manual_seed(42), output=outputs)
+results = pipe(prompt=prompt, image=image, num_frames=124, generator=torch.Generator().manual_seed(42), output=outputs)
 
 encode_video(
     results["videos"][0],
@@ -216,7 +226,7 @@ The blocks never open a media file — decoding a path is the caller's job, as i
 
 ```py
 import torch
-from diffusers import ModularPipeline
+from diffusers import ComponentsManager, ModularPipeline
 from diffusers.modular_pipelines.minimax_h3 import (
     MiniMaxH3AudioReference,
     MiniMaxH3ImageReference,
@@ -226,10 +236,12 @@ from diffusers.utils import load_video
 from diffusers.utils.export_utils import encode_video
 
 # `ref2va` is a workflow of the one MiniMax-H3 pipeline; selecting it loads only the `transformer_ref/`
-# checkpoint partition.
-pipe = ModularPipeline.from_pretrained("MiniMaxAI/MiniMax-H3", workflow="ref2va")
+# checkpoint partition, and the manager moves each component on and off the accelerator in turn.
+manager = ComponentsManager()
+manager.enable_auto_cpu_offload(device="cuda")
+
+pipe = ModularPipeline.from_pretrained("MiniMaxAI/MiniMax-H3", workflow="ref2va", components_manager=manager)
 pipe.load_components(dtype=torch.bfloat16)
-pipe.to("cuda")
 
 subject = MiniMaxH3ImageReference.from_file(
     "https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/diffusers/astronaut.jpg"
@@ -281,11 +293,11 @@ from diffusers.modular_pipelines.minimax_h3 import MiniMaxH3VideoReference
 manager = ComponentsManager()
 manager.enable_auto_cpu_offload(device="cuda")
 
-# The full pipeline holds every workflow and picks one per call from the inputs. Each
-# `load_components(workflow=...)` loads only what that workflow still misses — the second call adds just
-# the `transformer_ref/` partition, everything else is already there.
+# The full pipeline holds every workflow and picks one per call from the inputs. Loading without a
+# `workflow=` brings both transformer partitions in one call, so the `ref2va` request that follows the
+# `t2va` generation needs no further loading.
 pipe = ModularPipeline.from_pretrained("MiniMaxAI/MiniMax-H3", components_manager=manager)
-pipe.load_components(workflow="t2va", dtype=torch.bfloat16)
+pipe.load_components(dtype=torch.bfloat16)
 
 results = pipe(
     prompt="An astronaut hiking through the mountains, humming a tune",
@@ -298,8 +310,6 @@ reference = MiniMaxH3VideoReference(
     audio=results["audio"][0],
     sample_rate=results["sampling_rate"],
 )
-
-pipe.load_components(workflow="ref2va", dtype=torch.bfloat16)
 results = pipe(
     prompt="The same astronaut now walks along a beach at sunset, humming the same tune",
     references=[reference],