Multi-Ref Storyboard Prompt Composer (Encyclopedic BFL / Calliope)

Multi-reference editing is the reason people put up with Flux 2 / Klein's size at all: one model, several reference images, one composition. Character from image 1, costume from image 3, location from image 5. The hard part isn't loading the images - it's writing the text that tells the model which reference is which. That's exactly the job this node exists for.

It's the third node in the ComfyUI-StudioPromptDirector pack, and it's a text composer: pick a use case, pick an interaction and atmosphere, and it outputs one multi_ref_prompt string that names image slots explicitly. Everything is grounded in how the model is actually prompted - "The character in image 1 on the left and the character in image 2 on the right are wearing outfits from image 3 and image 4…" That slot-naming style matters, because the community's hard-won lesson with Klein editing is to describe the composition of files, not a scene you imagine. Identity drift is the model's classic failure mode, and prompts that treat the references as ingredients rather than vibes drift a lot less.

The use cases

reference_use_case is the only dropdown you really need to understand. Seven modes covering the standard BFL/Flux multi-ref situations:

• Scene Compositing [5-Refs] - two characters, two costumes, one place
• Character & Costume Composite [4-Refs] - the default
• Character in Location [3-Refs]
• Style & Material Transfer [2-Refs] - content image + style image
• Object Replacement & Liquid Fill [2-Refs]
• Logo & Branding Placement [2-Refs]
• Single-to-Sheet 360 Turnaround [1-Ref] - four-view character sheet from one image

Each mode has its own base template that maps images to roles, so you can't accidentally write a 5-ref prompt with 3 references loaded. The two other required dropdowns, character_interaction_preset (heated argument, comfort embrace, "Custom Action") and location_atmosphere_preset, get appended as descriptive clauses. There's a Custom_MultiRef_Prose_Override box that bypasses everything if you want to hand-write the whole thing, plus per-slot custom boxes for the interaction and the lighting.

What it doesn't do

Big one: this node only outputs text. It does not load, slot, or arrange your reference images - you still wire those into the model's reference inputs yourself, in the right order to match the "image 1… image 5" numbering. If you're using Klein's kv-fp8 checkpoint with the Flux KV node, that's your speed play for multi-ref work (roughly halves render time by caching reference key/values); the composer doesn't know or care, it just makes the prompt. Also, the "Calliope" in the display name is the author's branding - don't go hunting for a model called Calliope; the actual target is the BFL/Flux 2 multi-ref stack.

Install

The whole pack is pure Python with no dependencies:

cd ComfyUI/custom_nodes
git clone https://github.com/nexusfinancial-dev/ComfyUI-StudioPromptDirector.git

Or search "ComfyUI-StudioPromptDirector" in ComfyUI Manager and restart. Nodes appear under StudioPromptDirector.

Gotchas

Wire multi_ref_prompt into the prompt input of your Klein multi-ref workflow. If the model keeps drifting off the references, the community playbook is: keep the reference mapping explicit (this node does), maintain the faces and posture in the prompt ("Maintain the faces. Maintain the posture."), and don't crank CFG unless the distilled 8-step default is giving you anatomy trouble. And when a composite fails, check the reference order first - the most common mistake is loading images in a different sequence than the prompt says, and no prompt composer can fix that for you.