H3 RefMod Text Encode

If you've ever built an H3 workflow with a character reference and wished you could just say "the woman in the first photo does this, the one in the second does that," this is the node that lets you try. H3 RefMod Text Encode (class MiniMaxH3RefModTextEncode) takes a bundle of saved references from the MiniMaxH3Mod pack and hands them to H3's native text/vision encoder, which numbers them so your prompt can point at <Picture 1>, <Video 2>, <Audio 3>. It's the only path in this pack where a reference has a name the model can resolve.

It's the sibling of Apply H3 RefMod, and the difference is the whole story. Apply just appends reference latents to your conditioning - the DiT attends to them, but the vision encoder never "sees" them and you can't tell them apart. This node decodes each reference to actual pixels, feeds those to the Qwen-based encoder inside H3 during tokenization, and returns conditioning carrying both the visual presentation and the DiT reference payload. Two characters in one scene, each anchored to their own saved photo, is the canonical use: numbered labels are how you keep them from merging into one person.

How it works

Behind the scenes it does the two jobs in the right order. For every mod with a strength above zero it applies that strength to the stored latent, decodes it with the H3 video VAE (ComfyUI owns device placement and the OOM/tiled fallback), and samples frames for the vision encoder at ~2 fps - videos get timestamps, images keep just their first frame. Those pixels become minimax_ref_items passed into clip.tokenize(prompt, ...), so the encoder counts each modality separately in bundle order and hands back the labels. The node then stashes the original latent blocks into the conditioning metadata (minimax_refs) so the DiT gets the actual reference too. Zero-strength slots are dropped from both sides.

Read the source and two things stand out as non-negotiable: your clip must be H3's native CLIP or a projected encoder whose tokenize exposes minimax_ref_items (the current ClipProj loader qualifies - the node checks and errors otherwise), and if any visual mod is active you must connect the H3 video VAE, because nothing can be shown to Qwen until the latent is decoded. Audio-only bundles skip the VAE entirely.

Inputs that matter

• prompt - multiline text. Write it with the labels from reference_map: The woman in <Picture 1> stands on the left. The woman in <Picture 2> stands on the right. They turn toward each other and smile.
• clip - native H3 CLIP, or a projected ClipProj-style CLIP that supports H3 reference presentation.
• mods - the bundle from Load H3 RefMods (strengths here do affect the latents Qwen sees).
• reference_fps (default 24) - playback timing for the reconstructed video. Original timing is gone after compression, so this only sets how Qwen's 2 fps sampling reads it.
• max_total_tokens (default 0 = off) - caps DiT reference tokens. It does not cap Qwen tokens or VAE decode memory, so don't expect it to protect you from a heavy decode.
• vae - the H3 video VAE, required whenever any visual reference is active.

Outputs are conditioning (wire to the sampler's positive input) and reference_map (a STRING like <Picture 1> = alice - drag it onto a text display to see what's what). The critical rule: this node already attaches the references, so don't run the same bundle through Apply or Bridge afterwards. Negative conditioning and the generation latent stay as normal.

Install

ComfyUI Manager (search "ComfyUI-MiniMaxH3Mod") or:

cd ComfyUI/custom_nodes
git clone https://github.com/Luisacaotica/ComfyUI-MiniMaxH3Mod

Then restart. Requirements are just safetensors, numpy, Pillow (torch comes with ComfyUI); Manager installs them automatically. You need a current ComfyUI with native MiniMax H3 support - this pack imports no sibling pack and downloads no models itself, but you'll want the H3 weights and its video VAE (and audio VAE for audio refs) already on disk.

The honest caveats

The README is admirably straight about this being experimental: presentation and payload tests pass, but full GPU generation and identity/voice quality are not verified. Compressed references reconstruct less detail than the originals, so Qwen is judging a degraded picture, and saved Apply curves don't apply here. Also worth knowing before you go deep on H3 at all: the open weights ship under the MiniMax H3 Community License, which excludes the US, EU, UK and South Korea - if you're in one of those, check the license before running anything. Start by comparing this against a plain Apply workflow with the same refs, prompt and seed; if numbered labels don't beat it, you've learned something cheap.