MiniMax H3 Ref Extract

MiniMax H3 is the open-weights video model that treats text, image, video and audio as one input context - 33B, native stereo audio, up to 15 seconds at 2K/24fps. (It also ships under a licence that geofences out the US, EU, UK and South Korea, so read that before you build anything on the outputs. That's the model, not this node, but it's not a footnote you want to discover late.)

H3's references are the interesting part of working with it: instead of text-only conditioning you can hand it actual media as context. UC_MiniMaxH3RefExtract turns images or video frames into those references, and - the reason this node exists - it hands them to you as an object you can save and reuse, so you're not re-VAE-encoding the same reference images on every queue.

What it produces

Each reference is a MiniMax H3 VAE latent: a 24-channel tensor per visual reference, plus metadata. The outputs are ref (MINIMAX_H3_REF) and info, a string summarising what you got - shapes and the token cost of each reference, and for video, how many source frames were actually used.

info is worth wiring to a text display while you're learning the node. Reference size is token budget, and the token count is the number you're spending: for a visual reference it's frames × (H/2) × (W/2), and for audio it's twice the latent length. Compression is how you trade that away.

The image/video split

media_type is a dynamic combo with two modes, and they behave very differently.

image encodes each image in the batch as its own separate reference. Four reference photos in, four independent references out. This is the mode you want for subject and composition conditioning.

video treats the ordered batch as one 24 fps clip and produces a single reference. The clip needs at least five frames - that's a hard requirement, not a suggestion. Use it only when the frames really are one continuous shot; feeding it unrelated images gets you a smeared reference built from unrelated moments.

Either way, vae wants the MiniMax H3 video VAE. The audio node takes the audio VAE; mixing those up is the classic mistake in this family.

Compression: the dial that matters

Under media_type sits a compression choice with three modes and a couple of numbers that change with it.

encode keeps the full latent - maximum detail, maximum tokens, no extra compute. This is the default and the honest starting point.

pooled shrinks the latent (averaging down to a smaller grid, sized by reference_resolution, the long edge in pixels, default 256, multiples of 32) and keeps the shorter edge proportional to the source. Cheaper tokens, softer reference. Start around 128–512px; 256 is the sensible default. In video mode, temporal_density (default 16) decides how finely time is represented - higher keeps motion detail, lower blends moments together, and the clip stays fully covered either way.

refined takes the pooled latent and spends refine_steps (default 100; 50–200 is the suggested range) of gradient descent optimising the compressed latent to reconstruct the original one. To be clear about what this is, because the name invites the wrong idea in a world where everyone trains LoRAs: it optimises only the latent. No model is trained. It's a nicer compressed reference in exchange for time.

description is free-text notes that get stored with the reference. It does not enter your prompt and does not change conditioning - it's for you, six weeks from now, when you've forgotten which reference was which.

Install

Manager → search "ComfyUI-UtilsCollection", or:

cd ComfyUI/custom_nodes
git clone https://github.com/silveroxides/ComfyUI-UtilsCollection
# restart ComfyUI

No models of its own; it uses whatever H3 VAE your workflow already loads. The pack's requirements.txt pulls opencv-python, huggingface_hub, unifiedefficientloader and typing-extensions, and the collection imports kornia at load time without declaring it - if the nodes don't appear after install, that's your first suspect.

Pair it with MiniMax H3 Ref Save to keep references on disk and MiniMax H3 Ref Apply to attach them to conditioning.

Where it goes wrong

The info output's frame accounting is the tell when a video reference looks off - if it reports fewer prepared frames than source frames, your clip was longer than the chosen duration allowed. And if you're applying references that suddenly push you over a token budget, the compression mode is what to revisit, not the Apply node, which errors rather than silently trimming your references for you.