Prompt Studio Reference Prompt Settings

The honest summary of this node: on the ComfyUI canvas it passes your prompt through untouched and calls nothing. Every setting on it is an instruction to the browser-side Studio about how to prepare text before the graph is ever queued. It is a declaration node wearing a text node's costume.

What it is

PS_ReferencePrompt sits between your Prompt Slot (or Prompt Amplify) and your model's text encoder. It takes a STRING prompt, an optional references collection, and a handful of settings, and returns a STRING prompt. If you queue the graph yourself from the canvas, the output is exactly the input - no LLM, no rewriting, no surprise.

Why it exists: reference-driven models don't just need the images wired, they need the prompt text to name those images in the syntax the model was trained on. Qwen 2.1 expect tags like <image1>, <image2> in the instruction, and which number maps to which picture depends on whether the workflow is a Create or an Edit graph. Studio handles that assembly - with a vision-capable local model doing subject analysis, or by assembling your explicit roles directly when LLM amplification is off - and this node is where Studio learns your conventions.

Worth remembering while you assemble that text: Qwen's encoder is an LLM (Qwen2.5-VL), so you write sentences and instructions - (weight:1.4) syntax arrives as literal punctuation.

The settings that matter

• prompt_mode - edit_instruction prepares a source-aware instruction from the selected source image, your references and your request, while keeping the Main and Final prompts unchanged; full_prompt uses the normal scene-prompt pipeline and appends reference guidance. In an editing workflow wired for instruction mode, the workflow deliberately receives the latest edit instruction rather than the whole final prompt.
• reference_token - how references are named, default <image{index}>. It must contain {index}; change it to [ref-{index}] or whatever your model expects, and understand that it changes labels, not wiring.
• first_reference_index - the number substituted for {index} for the first semantic reference, incrementing from there. Qwen Edit uses 2 because the source is image1; Qwen Create uses 1. Reference Item indices still start at 1 - the two numbering schemes are deliberately separate, and mismatching them is how you get a model that edits the wrong picture.
• source_token - what the image being edited is called in prepared instructions (<image1>, [canvas]). It doesn't select or connect the source; it just names it.
• instructions - optional model-specific guidance, e.g. concise editing commands or attribute-transfer rules, appended during assisted preparation. It can't add capabilities the model doesn't have.

Connect the references input to the same collection your Item nodes read. Leaving it disconnected is only correct for a graph with no semantic references at all - a guide-only edit, for instance. One connected settings node per workflow.

How it fits the bigger picture

In 2026 the reference-driven edit is the mainstream way to hold a character across images, and the residue of the old stack - IP-Adapter for faces, a pose ControlNet, careful LoRA weighting - is exactly what people get told to drop. What replaced it is "hand the model the source plus a couple of labelled references and describe the change." Labelled is doing real work in that sentence: role assignment (subject, clothing, style, object) is how you tell Qwen which traits to borrow from which picture, and it's why a workflow that wires images correctly but leaves the numbering wrong behaves so badly.

Install

The node is part of the pack:

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

Restart ComfyUI. No runtime pip requirements, no model files. To use LLM-assisted preparation you also need a local model server - Ollama on http://localhost:11434 by default, or KoboldCpp / Llama.cpp via Settings → Backend settings. With Use LLM amplification off, your text goes straight through as-is.

Common issues

• The prompt looks unchanged in the graph but the image is fine. That's expected: Studio prepares the text before queueing. Don't try to verify reference assembly by reading the canvas widget.
• reference_token without {index}. You've turned the token into a fixed literal, so every reference gets the same label. The placeholder is the mechanism.
• The model borrows from the wrong image. A first_reference_index mismatch against the actual encoder wiring. Edit = 2, Create = 1, and check it against which image_N socket Item 1 lands on.
• Changing capacity or roles didn't take effect. Those edits invalidate prepared reference instructions; re-save the [PS] workflow, refresh workflows in Studio, and let it re-prepare rather than reusing the previous run's text.