DHan-API-Image-gen RefStacker

The DHan-API-Image-gen RefStacker is the least glamorous node in this pack, and that's the point. It takes up to fourteen IMAGE inputs, drops the empty ones, and outputs a single API_IMAGE_REFS connection that goes into the main node's references input. No sliders, no weighting, no config object. It's a junction box.

Why want one? Reference-driven editing is where the closed image models earn their money - Nano Banana Pro takes up to 14 reference images, GPT Image accepts 16 inputs total including the primary - and eight Load Image nodes wired straight into the generator turns your graph into a spider's web. The stacker lets you park the donors next to whatever produces them: a local inpaint pass, a face crop, a product-shot batch. One clean wire into the generator. The README calls it the successor to the "former Nano stacker," and the difference is telling - this one doesn't configure anything, it just collects.

How it works

The mechanism is about as literal as it gets: ref_image_1 through ref_image_14, each optional but forced to be a wired input, and the node returns the connected ones in index order as a list, skipping anything left empty. That list is what the main node walks through when it labels each image REFERENCE IMAGE n - DONOR REFERENCE ONLY in the Gemini request and when it appends files in order for OpenAI.

Which means order is the interface. Reference 1 is whichever socket has the lowest number, not whichever you connected first. If you fill sockets 1 and 3 and leave 2 empty, your third image becomes "Reference Image 2" in the prompt - and since the main node normalises "ref 2"/"reference image 2" to the matching label, mis-numbering your prompt is a real way to swap the wrong donor into a render. Honestly, if you're going to reference images by number in your text, keep the sockets contiguous and delete what you're not using.

Also worth knowing: if you wire both a stacker into references and images into the main node's own ref_image_N sockets, the stacker's list is sent first and the direct sockets follow. Useful for a fixed "always these references" block plus a variable one, confusing if you didn't know.

The inputs and output

Only ref_image_1 … ref_image_14 (all IMAGE, all optional), and one output: references of type API_IMAGE_REFS. Send your donors here and put the image you want edited - the canvas - into the main node's image input. Mixing those up is the most common mistake: a donor that lands as the primary becomes the edit target, and the model dutifully preserves the wrong picture's pose and framing.

Note that API_IMAGE_REFS is this wrapper's own type. The underlying editors use their legacy NANO_REFS and GPT_IMAGE_REFS types, so don't try to feed this output into an older Nano stacker node and expect it to click.

Install

Same pack, same steps - there's nothing to install separately, and nothing extra to download.

cd ComfyUI/custom_nodes
git clone https://github.com/DHan315/Comfyui-DHan-API-Image-gen
# restart ComfyUI

Or search "Comfyui-DHan-API-Image-gen" in ComfyUI Manager. Its declared dependency is just requests.

Gotchas

It does not batch for you. Fourteen sockets means fourteen separate images. If you feed it an IMAGE that carries a batch, the main node converts tensors with tensor[0] - frame zero only. So a stacker full of frames from one video clip doesn't send a sequence; it sends the first frame of each. Combine frames into a grid or an edit mosaic if that's what you're after.

Duplicates cost money. Nothing dedupes the list. The same reference wired to two sockets gets uploaded twice and counts twice against the provider's input limit - and on a 14-image stack you're already close to GPT Image's 16-image ceiling once the primary image is added.

No influence control. There's no weight, no strength, nothing to dial. The stacker's own source comment says as much - no weighting is applied. Control comes from your prompt wording and from which socket each donor sits in, which loops back to the ordering point.

It's a pass-through, so failures show up downstream. If the main node errors on an image count or a rejected reference, the stacker isn't the problem; check the main node's log output, which reports the reference count and the sizes that actually left your machine.