Prompt Studio Reference Item

This is the adapter node, and it's the one that makes Prompt Studio's reference system compatible with anything. Collection carries an ordered list of records; Item turns position N of that list into a plain IMAGE (and a MASK) you can plug into a model encoder that has never heard of Prompt Studio.

What it is

PS_ReferenceItem takes the references output of Reference Collection plus an index, and returns two standard sockets: image and mask. Internally it looks up the record at that one-based position and loads the actual file through the pack's image-input loader. If the position is empty, both outputs are None - an explicit "nothing here," which is why downstream nodes need to tolerate absence (or why you set Collection's minimum equal to maximum).

It also does the right thing about caching: its change detection is tied to the identity of the reference image, so swapping a reference in the Studio actually re-runs the branch that encodes it instead of silently serving the previous run's cache.

The index is not the model's image number

This is the trap, and the pack's own tooltip is unusually direct about it. index is a position in the collection, not a slot in your model's image tokens. Qwen 2.1 Create takes references starting at image_1, so Item 1 goes to image_1. Qwen 2.1 Edit reserves image_1 for the image being edited, so the source goes there and Item 1 goes to image_2, Item 2 to image_3, and so on. Get that off by one and the model happily treats your reference as the edit target, which produces confident nonsense rather than an error.

The bundled workflows show the shape exactly: the Create graph wires ten PS_ReferenceItem nodes into image_1 through image_10 of a single native TextEncodeQwenImage21, and the Edit graph wires nine into image_2 through image_10 with the Image Source on image_1. Reference Prompt Settings is where you tell Studio that numbering convention so the prompt text matches; this node only moves pixels.

The two outputs

• image - the reference as a normal IMAGE tensor. Wire it to your model's reference input, or through a preprocessor if that model wants, say, a depth map instead of a photo. Several Items can read the same collection, so you fan one collection out across as many encoder inputs as you have.
• mask - the reference image's transparency: 1 for transparent pixels, 0 for opaque ones, all-zero for a fully opaque image. It is not Studio's painted edit mask, and it is not a segmentation. It's there for models that use alpha (the RGBA paths), and if you were hoping this was "the mask", you want Edit Mask or Structure Input instead.

Install

Same pack, same drill:

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

Restart ComfyUI. No pip packages, no model downloads - this node is pure plumbing, and its only model-facing requirement is that whatever you wire it into has an image input that accepts None. That's true of native TextEncodeQwenImage21 and of plenty of custom encoders, which is the point of doing it this way rather than through a Prompt-Studio-only encoder.

Common issues

• Type mismatch when you wire the output. You connected the Collection to something expecting an IMAGE. PS_REFERENCES is a list of records; the Item is the thing that produces images.
• The model edits your reference and ignores the source (or vice versa). Off-by-one index. Check Reference Prompt Settings' first_reference_index against the actual wiring - Edit uses 2, Create uses 1 - and remember Item indices always start at 1 regardless.
• downstream node errors with a None input. You left a slot unfilled and the encoder requires it. Either set Collection's minimum to maximum, or use a node that handles an absent image.
• You swapped a reference and the output didn't change. Save the workflow, then hit Refresh workflows in Studio - the pack refreshes the workflow list when a [PS] workflow is saved, and the selected workflow is re-checked before queueing.
• You expected a mask of the subject. The mask output is alpha only. For painted-mask preservation you want PS_EditMask; for guide/preservation masks you want PS_StructureInput.