Reference Images Pixaroma

The problem this thing actually solves

Somewhere in 2026 the answer to "how do I keep this character consistent" stopped being IP-Adapter and became "give the edit model the picture and describe what to do with it." Every multi-reference model then invented its own dialect for naming pictures. Qwen Image 2.1 wants <image1>, <image2>. FLUX 3 Image Klein wants <ref_image_0> and counts from zero - the kind of off-by-one that quietly ruins a run. MiniMax H3 wants <Picture 1>. Flux 2 Klein and a pile of others just want plain words: "image 1".

So the workflow breaks in a boring way. You wire three references into the encoder, type "put the jacket from picture 2 on the guy in picture 1", and get something adjacent-to-right, because the model never saw its own token. Reference Images Pixaroma makes that mismatch stop: you write @1, @2, @3 like a human and it writes the model's dialect for you.

It's also a nicer place to hold refs: twelve slots, each with a job attached.

How it works

The cards live in the browser, not in widgets. Pictures go up through ComfyUI's own /upload/image into your input folder, and the card list (file, role, name) rides into the backend as a hidden input when you hit Run. That's why the node looks like a little gallery and why there's nothing to configure in the usual input list - the settings sit in the node's properties, not in sockets.

On a run it loads each picture, fixes phone rotation from the EXIF, flattens transparency onto a fill colour, optionally caps it at 1MP or 2MP and trims edges to a clean multiple. Then it builds prompt in two pieces: a sentence saying what each picture is for ("Use the character from <image1>, the outfit from <image2>."), and your own text with every @N swapped for the model's tag.

Auto finds the model by walking the wire out of prompt, up to six nodes, looking for a known text-encode class: Qwen Image 2.1, FLUX 3, MiniMax H3, or one of the plain-words encoders. Find nothing and it assumes plain words - the safe guess, not always the right one.

The inputs and outputs that matter

There's exactly one input in the schema: text (optional, and it must be wired - it won't take a typed value). Feed it from Prompt Pixaroma and it replaces the prompt box on the node, while @1, @2 inside it still get converted.

Outputs are prompt (STRING) plus image_1 … image_12 (IMAGE). Two rules, and they're the whole game:

• Wire prompt into the model's text encode (or into Prompt Pixaroma's text input). This is what names the pictures.
• Wire image_N into the model's picture input number N, in the order shown on the node. Prompt and pictures have to agree, or this is just a fancier way to get the wrong result.

Empty slots come back blocked, so you wire two pictures' worth, not twelve, and nothing downstream errors over the ten you left alone.

The rest of the settings live on the node face: roles, the model picker (Auto / Qwen Image 2.1 / FLUX 3 Image Klein / MiniMax H3 / Plain words / Custom with {n} and {i} placeholders), whether the role sentence goes before your text, after it, or off, fill colour for transparent PNGs, size cap and trim multiple. On Auto, Qwen Image 2.1 gets trimmed to multiples of 32, because its encoder stretches whatever it's handed onto a 32 grid and your edit comes back a few pixels wider than the original.

Install

ComfyUI Manager: search Pixaroma. Be warned, Manager only offers version 1.4.144 - the author says the Registry flagged newer releases for no stated reason. For the version with this node, use Easy-Install on Windows, set the pack to nightly in Manager, or clone it:

cd ComfyUI/custom_nodes
git clone https://github.com/pixaroma/ComfyUI-Pixaroma

The README's own command points at the GitLab mirror (https://gitlab.com/pixaroma/comfyui-pixaroma.git); either works. Restart ComfyUI, then Ctrl+Shift+R in the browser - skip that and you'll be staring at old node UIs.

No model downloads and no extra packages for this node. The pack's requirements.txt is one line - imageio-ffmpeg, for the video nodes.

Where people get burned

"picture 1 (foo.png) is not in ComfyUI's input folder." The card remembers a filename; rename or delete the file and the node can't run.

The model ignored your tags. They came out as plain "image 1", so Auto guessed wrong - usually because prompt takes a few hops before reaching a class it knows. Set the model explicitly. One dropdown, saves an hour.

@2 survived literally. You referenced a picture that isn't on the node. It only converts @N for pictures that exist.

Pictures in the wrong order. Every slot is numbered so it's fixable, but the symptom reads as a bad model rather than a bad graph - features bleeding between subjects.

Transparent cutouts came back on white. That's the fill setting. Pick black or grey.

And if consistency still drifts, no amount of neat tagging fixes it - an edit model re-emits the whole frame, so cropping to a mask and stitching it back is the actual fix.