Burve Gemini Reference Pack

The modern Gemini image models take reference images, and the difference between a reference that helps and one that confuses is whether the model knows what the image is for. Burve Gemini Reference Pack is the node that adds that job description. Up to fourteen images, each tagged with a role - generic, object, character, or style - plus an optional label, packed into one GEMINI_REFERENCE_PIPE that plugs into the reference_pack input on the Burve Gemini generation nodes.

Why roles matter: character consistency is the hardest unsolved problem in this space, and the closest thing to a solution with a closed model is giving it a face and telling it "this one is the character." Mark one reference as character and the model treats it as identity to preserve; mark a product shot as object and it keeps the thing looking like the thing. A pile of unlabelled images reads as vague vibes. This is the same instinct behind face-lock and identity-preservation tooling, just expressed as a role dropdown instead of an adapter.

How it works

It's a packer, not a generator. Each of the 14 slots has three optional inputs: imageN (an IMAGE), roleN (default generic), and labelN (free text). Empty image slots are skipped entirely, so you can fill five slots of fourteen and leave the rest alone. The node bundles only the filled ones into the pipe - and importantly, it doesn't enforce the model's reference limits itself. The generator validates the totals against the selected model before the request goes out, so the failure shows up as a clear error at generation time rather than a silent API rejection.

That per-model limit is real and worth knowing. Google's own docs (which the pack author re-verified against Google's public documentation) cap total references at 14, then split by role per model - Gemini 3 Pro Image, for instance, allows up to 6 object, 5 character, and 3 style references in that 14. The node gives you 14 slots; the model decides how many of each it'll actually take. The reference_pack pipe also outranks the older route: reference precedence in the generator is Character Generation Pipe → Gemini Reference Pack → legacy IMAGE_LIST, with a warning added to system_messages if you connect more than one source.

Install

Pack-wide, one time: ComfyUI Manager → search ComfyUI_Burve_Tools → install → restart, or

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

Dependencies: google-genai (≥2.13, <3), pillow, pillow-heif. No model downloads, no key on this node itself - the generation node downstream needs GEMINI_API_KEY (AI Studio) or a Vertex setup, and ComfyUI 0.4.0+.

Gotchas

• Roles are per-slot, not per-image-list. Each of the 14 slots carries its own role and label, so an unlabelled slot defaults to generic.
• Watch the per-role caps on 3 Pro Image. It's easy to throw five character references in and discover the model only takes a subset with your other roles. The generator's error message tells you the exact limit.
• Your references leave the machine. Like every Gemini input, these images go to Google's servers when you run the generator - and Gemini image models sit behind aggressive filtering. If a reference would trip a refusal, the model refuses; no node in this pack changes that.

It's a small pack, so don't expect a wall of community tutorials - but role-tagged references are exactly the kind of feature that looks trivial and quietly becomes the backbone of a repeatable character workflow.