Prompt Studio Reference Collection

Here's a small, honest confession about this node: it does nothing at runtime. It carries no pixels, encodes nothing, and its one output isn't an image. It exists so Prompt Studio knows how many reference tiles to show you and which roles to offer - and it's the node that makes the whole reference system work with any model, not just Qwen.

What it is

PS_ReferenceCollection declares reference capacity and roles for Image Studio. You wire its references output into Prompt Studio Reference Prompt Settings and into one Prompt Studio Reference Item per slot you intend to support. Its output type is PS_REFERENCES - an ordered list of image records with roles, not a tensor. Connecting it to an IMAGE socket will not work, and that's the single most common wiring mistake with this node.

Why the pack needs this at all: Image Studio discovers capabilities by reading the graph. It looks for connected declaration nodes that reach the workflow's image output, and the collection is how a model says "I take up to four ordered references, and they can be labelled subject, style, clothing and so on." Get it wrong and the Studio UI offers slots your model can't use, or hides ones it can.

How it goes together

The pattern the pack documents is Collection → Item(s) → your model's existing image inputs, and it's deliberately model-agnostic:

• minimum - how many semantic references must be attached before generating. 0 makes them optional. Structure-only guides don't count toward it. If your model's encoder refuses unfilled image slots, set minimum equal to maximum.
• maximum - the most entries Studio will allow, including an attached structure guide. 0 to 64. Set it to your model's real capacity and wire Items 1 through that number. The pack says it plainly: increasing it does not add image support to the model.
• roles - comma-separated lowercase identifiers offered in the References panel. The default is custom,subject,clothing,pose,background,style,object, and you can invent your own. Roles are prompt-preparation hints, not wiring. The custom role requires the user to type an instruction.
• references_json - leave it at []. Studio fills it. It's the manual escape hatch for running the graph straight from the canvas, in the form [{"image":{"filename":"ref.png","subfolder":"","type":"input"},"role":"style"}].

It validates hard: minimum above maximum throws, and so does a filled list outside the declared band (Workflow requires between 0 and 4 references). A Reference Item pointing at an unfilled slot returns None, so either your encoder accepts absence or minimum = maximum.

Why this is the interesting node of the set

Multi-image referencing is where 2026 image work actually happens. The character-consistency picture in mid-2026 is that one character across many images is largely solved by editing a good source image, while two characters in one frame is still the hard case - the same-subject attribution problem that VLMs and diffusion encoders both fumble. Ordered, role-labelled references are exactly how you stop two subjects bleeding into each other, and Qwen 2.1's Create path accepts up to ten of them (Edit takes the source plus nine). The bundled Prompt Studio workflows ship ten PS_ReferenceItem nodes in the Create graph and nine in the Edit graph, which tells you what the author considers the practical ceiling.

That's also the honest limit: a collection cannot make an encoder smarter than it is. If a model takes two images and merges faces, declaring maximum = 10 won't save you.

Install

It's part of the pack, so:

cd ComfyUI/custom_nodes
git clone https://github.com/tiko13/ComfyUI_PromptStudio

Restart ComfyUI. No extra dependencies, no models. Two workflow-side requirements matter more than the install: the workflow filename must start with [PS] to be visible to Studio, and the collection has to be connected and reaching the image output to be detected. Save it, then hit Refresh workflows in Studio.

Common issues

• Studio shows no reference tiles. Either the collection isn't connected all the way through, the Collection isn't wired to Reference Prompt Settings, or the workflow isn't saved with the [PS] prefix and refreshed.
• Generation fails with "Workflow requires between N and M references." Studio filled fewer or more entries than the band you declared. Loosen minimum if references should be optional, or raise maximum (and wire the extra Items) if you genuinely wanted more.
• The encoder errors on a missing image. Set minimum = maximum so every declared slot is filled, or replace the encoder's fixed image inputs with a node that accepts an absent reference.
• You changed maximum and Studio still won't take a fifth image. You also need Reference Item nodes at indices 5+ wired to real image inputs. The collection advertises slots; the Items are what actually exist.