Higgsfield - Reference Images

Generating from text is the easy half. The interesting half is handing a closed model an image you already have - to edit it, to restyle it, or to keep a face consistent across shots - and for the Higgsfield nodes that job belongs to HFReferenceImages. It generates nothing and calls nothing on its own. It's an adapter: ComfyUI IMAGE in, the pack's HF_REFERENCES bundle out, which the generate nodes then upload alongside your prompt.

If you've been fighting character consistency locally with IP-Adapter weight tuning, this is the same problem solved another way. The KB's read on that subject is blunt and it applies here: the community stopped trying to encode a character and started editing the image that already contains it - "generate the character once, then edit that image". A reference chain into Sunburst is exactly that move, except the edit happens on someone else's GPU.

How the chain works

Each node converts every image you hand it into a PNG in memory (float tensor clipped to 0–1, scaled to 8-bit), hashes it, and keeps the result. That's why a reference chain is built by chaining rather than by one node with many inputs:

Load Image → Reference Images (A) ──references──┐
                                                 ↓ previous
Load Image → Reference Images (B) ────────────────→ Generate / Edit Image

Wire the upstream node's references output into the next node's previous input, and the final output into the generate node's references input. Order follows the chain, and because the list is built as previous plus this node's own images, the node at the head of the chain becomes reference 1. On Seedance 2.5 Image to Video that matters: reference 1 is your start frame and reference 2 your end frame.

Why bother chaining when you could just batch images into one node? Because a differently-sized image in the list would otherwise be squashed into a single batch tensor. Separate nodes keep each reference at its own resolution, which is what you want when you're combining a subject from one picture with the setting from another.

Inputs and outputs

Two inputs, and you'll only ever set one of them. images takes an IMAGE - a Load Image node, or any node in your graph that outputs images, which is the point: a locally generated or upscaled image can become a reference without ever leaving the graph. previous (optional) is the HF_REFERENCES chain described above. The single output is references.

Nothing validates the count or content here - that happens in the generate node. Sunburst caps out at 16 reference images and rejects anything that isn't an image; image generation won't take a video or audio reference from anywhere. You can build and queue chains with no API key at all, by the way: the files are only uploaded at the moment a generation actually runs.

Install

The node arrives with the pack, so this is once-per-install, not once-per-node:

cd ComfyUI/custom_nodes
git clone https://github.com/w0ver/Higgsfield-api-comfyui-nodes ComfyUI-Higgsfield

Restart ComfyUI and look under Higgsfield/References - or search "Higgsfield" in ComfyUI Manager, which does the same thing with fewer terminal seconds. There's nothing to download and no checkpoint to place: the whole pack's dependency list is requests. The credential setup only matters for the generate nodes; instructions are in the pack's Configure API.bat (Windows) or the HF_API_KEY_ID / HF_API_KEY_SECRET environment variables.

Where people get burned

• The reference never reaches the model. Check the chain direction - references out, previous in - and that the last node feeds the generate node. A disconnected chain is silently ignored when references is empty.
• "You changed the reference and got a new paid generation." Yep. The node fingerprints each reference's content, and that fingerprint is part of what defines the request. Editing your reference image is a new request by design; it isn't a cache miss you can argue with.
• Everything got smaller / distorted. You pushed a mixed-size image list through one node instead of separate chained nodes.
• Feeding a reference to a Text to Video route errors out. Seedance reference routes are Reference to Video and Image to Video; text-to-video takes no references at all.
• Workflow sharing. References travel as tensor inputs, so the images themselves are in the graph's node data - check before you paste a workflow into a public thread, since uploads eventually land on someone else's servers, and that's the deal you signed with every API node.