toobusy MiniMax H3 Semantic Reference

In a two-stage MiniMax H3 character-sheet workflow, the optional references are a gamble. That prop photo might be perfect, or it might be half out of frame with bad lighting - and you don't want H3 taking visual cues from a bad image. But the text describing what the reference is for is still useful either way. This node is the valve: it keeps the semantic description no matter what, and only forwards the actual picture when a Gemma analysis says the visual is safe to trust.

It's the middle piece of the toobusy H3 reference trio. The Optional Reference node gates a slot on a manual switch; this one gates it on an actual judgment call about the image.

How it works

The analysis input is a text string, and it comes from ComfyUI's core TextGenerate node running a Gemma-class vision model - an LLM in the graph doing a job that isn't diffusion (the pattern the KB's llm-in-comfyui essay walks through). The author's example prompt asks Gemma for exactly two lines:

VISUAL_REFERENCE: YES
SEMANTIC_DESCRIPTION: a clear prop; silver pistol, distinct silhouette, matte finish

The node parses those two lines with a regex. VISUAL_REFERENCE: YES means the image is coherent enough to constrain H3; SEMANTIC_DESCRIPTION: is whatever follows, kept verbatim. Then a routing dropdown decides what happens:

• auto - forward the image only if the analysis says YES. The default, and the sensible one.
• semantic_only - always drop the image, always keep the text.
• visual_reference - always forward the image, trusting you over the model.

Like its sibling, this node is lazy: analysis only gets computed when enabled is on, and image only gets computed once it knows the picture will actually be used.

The inputs and outputs

• enabled - default true, so it gates on analysis from the start.
• role_label - a short single-line label for the role ("Optional prop", "Environment"). Combined with the description.
• analysis / image - both optional and lazy; the Gemma text and the reference photo.

Outputs: visual_reference (IMAGE, null when the image is dropped) and semantic_role (STRING, formatted role_label: description). The text always flows; the picture flows only when it earned the right.

Installing it

Same pack as the rest of the toobusy H3 set, no extra pip dependencies:

cd ComfyUI/custom_nodes
git clone https://github.com/nicekriss/toobusy.git toobusy

Restart ComfyUI and hard-refresh the browser. What this node does need is a Gemma model and the core TextGenerate node upstream to produce the analysis - and H3 weights downstream. One honest warning before you go down this path: H3's community license geofences out the US, EU, UK and South Korea, so if you're in one of those regions the local weights aren't licensed for you to run at all (the KB's minimax-h3 panel has the details). That's a licensing call, not a technical one.

Where people get burned

The two-line format is a contract, not a suggestion. If your TextGenerate prompt doesn't emit a line starting VISUAL_REFERENCE:, the regex misses, the node assumes not safe, and in auto mode your image silently never gets forwarded while the text flows on. That silent drop is the classic failure. Second: role_label is single-line, so don't paste a paragraph into it. And if you're on semantic_only, the image is never going through - that's not a bug, it's the setting doing what it says.