H3 Tagged Reference Prompt

The busy-work that kills H3 workflows, automated

MiniMax H3 is the open-weight omni-modal video model - 33B, native stereo audio, text/image/video/audio as one context - and it's genuinely good. It also has a reference problem: to drive it well you feed it up to nine reference images and three audio clips, then write the prompt as a set of <Subject 1> / <Audio 1> legends that describe what each reference means. Doing that by hand for every shot is the worst kind of ComfyUI busywork. It's exactly where a "workflow included" video turns into forty minutes of rewiring sockets.

H3 Tagged Reference Prompt (class H3TaggedReferencePrompt, from video/text) exists to kill that. You maintain a local library of tagged references once - image, audio clip, or both - and then write {tag} placeholders straight into your prompt. The node does the rest: it resolves the tags, rewrites the prompt into H3's subject/audio format, and hands you the image and audio tensors already ordered for the model's sockets.

How it works

The node reads your library from ComfyUI/user/h3_reference_library/ - a library.json manifest plus images/ and audio/ folders. You build that library through the web manager at /h3-references (there's an Open Reference Library button right on the node, and a launcher in the ComfyUI toolbar): upload an image and a voice clip, tag them, give them a category, add a short description. Bulk imports auto-pair image and audio by filename stem, so news_anchor.png + news_anchor.mp3 become one record.

Then in the node's prompt you write:

[Shot 1] {news_anchor} is sitting at {news_desk}.

On execution it resolves tags in first-use order, rewriting the prompt into H3's reference language:

<Subject 1> (S1) is defined by the first reference image: a woman in a gray suit at a desk. <Audio 1> is the voice-timbre reference for <Subject 1> (S1): a calm American anchor voice.
<Subject 2> is defined by the second reference image: a dark newsroom desk with a city backdrop.

The priority logic is the interesting bit. Records carrying both image and audio are sorted first, then image-only, then standalone audio - and since H3 only has three audio sockets, when your prompt wants more than three voiced characters, the fourth and later ones keep their image reference and get their voice described in text instead of erroring out. Graceful degradation, and it reads naturally in the output prompt. More than nine image references, on the other hand, is a hard error, and a {tag} with no record errors too, naming the missing tag.

The inputs and outputs that matter

• prompt_template (STRING, multiline) - the prompt with {tag} placeholders. Default [Shot 1] {news_anchor} is sitting at {news_desk}. Tags may only contain letters, numbers, _ and -. No tags at all? The prompt passes through unchanged and loads nothing.
• prompt (STRING) - the rewritten H3-style prompt. Goes into the MiniMax H3 node's prompt input.
• mapping (STRING) - a {tag} -> <Subject 1> legend you don't wire anywhere; it's for sanity checks.
• image_1 … image_9 (IMAGE) - up to nine reference images. Unused slots come back empty, so just wire all nine into H3's reference-image inputs and forget them.
• audio_1 … audio_3 (AUDIO) - the three voice/sound references, wired into H3's audio-reference inputs.

Installing it

Search ComfyUI Manager for H3 Reference Library, or:

cd ComfyUI/custom_nodes
git clone https://github.com/nikaskeba/ComfyUI-Minimax-H3-Reference-Library.git

Restart, then open a fresh browser tab (the routes are registered at startup). That's the whole install: pyproject.toml declares zero dependencies, there are no model downloads, and the library lives outside the custom-node folder - updating or reinstalling the pack won't touch your references. No API key anywhere, because this node doesn't call an API; it's a local media organizer with a prompt rewriter in front.

Where people get burned

Three things trip people up. First, the H3 weights themselves: if you're in the US, EU, UK or South Korea, the MiniMax H3 Community License doesn't grant you rights to run the local weights - the hosted Hailuo API is the only licensed path. That's upstream of this node, but it's the first thing to check when nothing works. Second, an empty prompt-template default: every one of the 12 media outputs fires even when nothing's tagged, so an empty string silently passes through with zero references loaded - the node is built around the manager, not around typing freeform. Finally, keep voice clips short and clean. H3's audio references are timbre references, not dialogue read-aloud; a clip with background noise teaches it the wrong voice.

If your characters are ones H3 already knows, the same pack's Built-In Reference node handles those prompt-only with ^Character Name^ tags - and leaves all twelve media sockets free for your own material. Between the two, a reference-heavy H3 workflow stops being socket archaeology and starts being a two-minute setup you reuse across every shot.