LoadImageReference

Reference-to-video models don't want "a picture". They want numbered slots. MiniMax H3's reference node exposes ref_images.ref_image_0 and ref_images.ref_image_1, and the prompt you feed it is expected to contain <Picture 1> and <Picture 2> tags that mean exactly those sockets. H3 treats text, image, video and audio as one context, so a reference image is a sentence fragment, not a conditioning tensor with a strength dial.

Which leaves the boring problem: where do the bytes come from? Core's LoadImage gives you a dropdown of filenames scraped out of ComfyUI/input. Fine for one image. Miserable when your prompt is a TOML file with twenty scene variants that each reference a different person, because the variation lives in the text file and the dropdown lives in the workflow JSON, and the two drift apart the moment you duplicate a workflow.

LoadImageReference exists to close that gap. It reads a file path out of the prompt file you already wrote.

What it actually does

The awkward part is upstream of the node, so start there. LOAD_REFERENCES is not a file and not a tensor - it's a small dict the prompt decoder builds while parsing your TOML: one list per type (picture, audio, video), each entry a path. You fill those slots with a <load> directive:

[h3.refs]
hero = "<load type=picture key=hero>/home/you/refs/hero.png</load>"
room = "<load type=picture key=room>${refdir}/room.jpg</load>"

[h3.prompt]
_t = """<Picture hero> walks into <Picture room>, slow dolly-in, 4 seconds."""

Set refdir = "/home/you/refs" somewhere in the file and ${refdir} interpolates. Feed PromptDecodeV2 the key list h3.refs, h3.prompt.

The key=hero alias and the <Picture hero> tag in your text are the same name, so they land on the same slot, and by the time the prompt reaches H3 it reads <Picture 1> walks into <Picture 2>. The <load> key emits nothing into the prompt itself - it only registers the path.

Then the node does the one thing its name says: looks up references.get("picture", n) and opens that file. PIL, convert to RGB, float32 divided by 255, one extra dimension for the batch. Out comes a [1, H, W, 3] IMAGE.

Inputs and outputs that matter

Two inputs, both required, and only one you'll think about:

• references - the LOAD_REFERENCES socket, wired from PromptDecodeV2's seventh output, labelled References. This is the whole trick.
• n - INT, 1 to 10, default 1. Which picture slot to serve. Slot 1 is <Picture 1>, which is ref_image_0, and so on up the list.

One output: IMAGE, a single-image batch. Wire it into ref_images.ref_image_0 on the H3 reference node, or into start_image on WanImageToVideo, or anywhere else that wants pixels.

Install

ComfyUI Manager, search the pack title comfyui-toml-prompt, or by hand:

cd ComfyUI/custom_nodes
git clone https://github.com/morino-kumasan/comfyui-toml-prompt

Then restart ComfyUI. That's genuinely all of it - the pack's requirements.txt is empty, so there's no pip step and no model download. Do not follow the repo's README install block literally: it still says comfyui-utils and uses an git@ SSH URL, which will just fail with Permission denied (publickey) unless you have keys configured. The README predates the rename.

Drop your .toml into ComfyUI/custom_nodes/comfyui-toml-prompt/prompts/, because that's the folder PromptLoader scans.

Where people get burned

The number isn't something you write. Slot order is the order the parser first met that alias - across both <Picture name> tags and <load> directives. Load a file before its tag ever appears and it grabs slot 1, shifting everything else down. The pack's own tests pin this behaviour. Use aliases everywhere and let the numbering fall out.

An empty slot returns None instead of erroring. The node checks for a missing path and hands back None, so nothing complains until something downstream tries to use an IMAGE. Two causes: your n points past the end, or the key holding the <load> wasn't in key_name_list - directives only run for keys that actually get decoded. The pack ships NoneToEmptyImage for exactly this, which turns a None into a 64×64 black frame so an optional reference can stay unfilled.

There is no MASK output. Core's LoadImage gives you IMAGE and MASK; this gives one IMAGE and forces RGB, so alpha is gone. If your graph needs the mask, stay on core LoadImage.

Paths are filesystem paths, not names. Absolute is the sane choice. A relative path resolves against ComfyUI's working directory, not your prompt folder, and a typo surfaces as a PIL FileNotFoundError at queue time.

And a small naming trap: the node displayed as PromptDecode (class TomlPromptDecode) has six outputs and no References socket at all. You need PromptDecodeV2. Wire the wrong one and the input simply won't connect.