Runware Reference Images

Most builders in this pack exist to feed a model node one typed value. Reference Images is the one that changes how you write your prompt. It's how the pack wires reference media - a person, a garment, a voice - into models that do virtual try-on and lip-sync, and it's the most-used builder in the catalog (75 model nodes accept its socket). The trick is the tag: you give a group of references a name that starts with @, then mention that @name in your prompt, and the model knows exactly which references to apply where.

The inputs

• image and images - both required IMAGE inputs. The first image plus the batch; for try-on, this is your subject (person) or your product (garment). A few good shots beat one bad one.
• role - enum: person or garment. This is what tells the try-on pipeline which reference is the body and which is the clothing. If you're building a try-on workflow, you'll typically have two of these builders - one for the person, one for the garment.
• type - enum: grid or image. How the reference group is structured: a single image, or a grid of multiple shots. Grids are the standard way to give the model several angles of the same subject.
• tag - required STRING, and the part to get right. It must start with @ (e.g. @actor1, @style), and it's the identifier you'll type into the prompt. Tag and prompt have to agree - tag it @actor1 and then mention @actor1 in your positive prompt, or the reference group is never actually invoked.
• audio - optional STRING (UUID or URL): a voice reference for lip-sync, max 15 seconds. This is how you give the model a timbre to sync lips to. It's an audio reference, not the video's soundtrack - keep the two separate in your head.

How to assemble it

For try-on: Builder A with the model/person photos (role person, tag @person), Builder B with the garment photos (role garment, tag @garment), chain them via the referenceImages input socket, wire the chain into the model node's referenceImages socket, and prompt with something like "wearing the @garment." For lip-sync: reference photos tagged @speaker plus an audio reference, and the prompt ties them together. The chain input means you can stack as many reference groups as the workflow needs, and the tags keep them distinguishable.

Output and wiring

Output is RUNWARE_REFERENCEIMAGES, chainable through the referenceImages input of the same type. Wire the end of the chain into a model node's referenceImages socket.

Install

The usual:

cd ComfyUI/custom_nodes
git clone https://github.com/Runware/ComfyUI-Runware
pip install -r ComfyUI-Runware/requirements.txt

Restart, add your Runware API key (Settings → Runware API key, or RUNWARE_API_KEY).

The honest take

The whole node is easy; the discipline is remembering the @ in both places. Tag it @person but prompt with "person" and nothing happens, and it's a genuinely confusing nothing because the workflow still runs and bills you. So: tag starts with @, prompt mentions the exact tag, audio stays under 15 seconds for lip-sync. Get those three and this is the most powerful builder in the pack for the "make this person wear this thing / say this" workflows that are otherwise painful to assemble.