PRYX ComfyUI Higgsfield Reference Collector

Multimodal video models eat references. Kling wants your character and your outfit. Wan 3.0's reference endpoint wants image 1, image 2, a video reference and maybe an audio track, and it addresses them by number in the prompt. Feeding five separate wires into a generator and hoping it guesses the order is how you get the wrong face on the right body.

The Reference Collector is the node that fixes that: one socket in the graph, a list of media in a defined order, and a generator that reads them in exactly the order you built.

How it works

It builds a references value - the pack's own PRYX_HF_REFERENCES type - from every socket you connect. Slot counts:

• image … image_30 - 30 image slots, and image batches are split, so a 4-image batch from one Load Image becomes four ordered references.
• video … video_10 - 10 video slots.
• audio … audio_10 - 10 audio slots.
• references - merge an existing collection in, if you have one already.
• external_url + external_type (url or file) - one already-public HTTPS link to a document or web page.

Order is deterministic and not the order you drew the wires. Slots are collected in numeric order: image_2 always comes after image, even if you connected image_2 first. Direct inputs on the generator (its image, video, audio, end_image sockets) map before anything coming from a Collector, and all of it is numbered separately per media type. Two Collector images become Image 1 and Image 2; they don't shift the videos.

The frontend grows extra sockets as you connect them, so you're not staring at 50 empty dots on drop.

The two fields you'll actually touch are names and label. names takes one assignment per line:

image_1=person
image_2=outfit
video_1=camera

Those become labels. Labels are what the {{ref:label}} prompt syntax resolves against, but only on endpoints that document numbered prompt tokens - currently Wan 3.0 Reference to Video. On other endpoints named aliases are rejected outright rather than silently ignored, which is the honest failure mode: better a stopped request than a wrong one. Braces aren't allowed in names, duplicate keys are an error, and labels must be unique per media item.

label is the legacy single-label field kept so old workflows still open. Use names for anything new.

Output

One output: references. Wire it into the references input of a generator (Text to Video, Image to Video, Reference to Video, Image Generate & Edit, Video Edit, Video Extend) or into Reference Preview. Model limits - how many references that endpoint accepts and of which type - are checked by the generator, not here. The Collector will happily build you eight images for a model that allows two; you'll get a validation error before anything uploads.

Install

Manager: search PRYX ComfyUI Higgsfield, install, restart. Or:

cd ComfyUI/custom_nodes
git clone https://github.com/PRYX-STUDIO/pryx-comfyui-higgsfield.git pryx-comfyui-higgsfield
python -m pip install -r pryx-comfyui-higgsfield/requirements.txt

Portable Windows: .\python_embeded\python.exe -m pip install -r .\pryx-comfyui-higgsfield\requirements.txt. ComfyUI 0.35.0+, frontend 1.53.6+, Python 3.10–3.13. No model downloads - just higgsfield-client, httpx and jsonschema. Your Higgsfield key goes in Settings → PRYX ComfyUI Higgsfield → Credentials (key-id:key-secret), or via HF_KEY for headless.

Note that the collector itself never uploads anything. Uploads happen later, in the generator: local media gets converted, pushed through Higgsfield's presigned upload flow, and only then referenced by URL. That's why an estimate-only run can still touch the network.

Traps worth knowing

• external_url must be public HTTPS already. Everything else in this node is a local file the pack will upload for you - that one field is not.
• Reordering means renumbering. Move a reference to a slot you think is earlier and you may have changed nothing; the Preview node shows the real mapping. Run it after touching media, labels or the model.
• The model still has the final say. A video-only reference type on an image-only endpoint fails validation before upload, not after you've paid for anything.