Higgsfield - Reference File

ComfyUI's IMAGE type can't carry a video or an audio file, which means the Reference Images node can't either - it only speaks tensors. HFReferenceFile covers the gap with the least glamorous input in the pack: a text field holding a path. Type or paste the location of a local PNG, JPEG, WebP, MP4 or WAV, chain it like any other reference, and it gets uploaded when a generation runs.

You need this node for one job in particular: Seedance 2.5 Reference to Video, which accepts image, video and audio references. Audio is a WAV reference. Video is an MP4 reference. Neither of those has any other route into the pack, so this little path field is standing between you and the route's whole feature set.

How it works

The node looks at the file extension to decide what it's holding: .mp4 becomes a video reference, .wav becomes audio, anything else is treated as an image (PNG, JPEG, WebP). If the file doesn't exist, or the extension isn't one of those, you get an error naming the accepted formats. It then hashes the file in blocks - cancellable, so a middling ComfyUI stop button press still works - and stores that digest with the reference.

Nothing is uploaded at this point. Upload happens when a generation actually runs, through a signed upload URL that deliberately does not carry your API credentials. Right before the upload the file is hashed again, and if it changed since you queued the workflow, the node aborts rather than quietly sending something different from what the request was fingerprinted against. Editing the file also trips the node's change detection, which keys off the file's modification time and size, so a re-queued workflow picks up your new version.

Two limits are baked in: 1 GiB per reference file, and one generation per submission.

Inputs and output

file_path is the whole node - a string, empty by default. Paste an absolute path; surrounding quotes are stripped, so copying "Copy as path" out of Windows Explorer works fine. previous (optional) links this into a longer chain with Reference Images or another Reference File. Output is references, exactly like the other reference node.

Because references are ordered by the chain, a Reference File at the head of the chain is reference 1. If you're doing start-frame/end-frame work, the order you assembled is the order the API sees.

Install

Nothing node-specific; install the pack once:

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

Restart, then find it under Higgsfield/References (or search "Higgsfield" in ComfyUI Manager and let it do the same thing). One dependency, requests, already present in any normal ComfyUI environment. Credentials - the Windows Configure API.bat helper, or HF_API_KEY_ID / HF_API_KEY_SECRET in the backend environment - are only needed by the generate nodes further down the graph, not by this one.

Where people get burned

• A .mov file. It's not on the allowed list. The accepted video container is MP4, full stop, so remux first (ffmpeg -i clip.mov -c copy clip.mp4) rather than renaming the extension - a renamed file still gets classified as a video reference but the API may not accept the container.
• Huge files. Over 1 GiB and the node refuses before uploading anything, which is a mercy given how long that upload would take on a home connection.
• "Reference file changed during execution." You edited or replaced the file between queueing and upload. Queue again - the guard did its job.
• A path that only works from your shell. Relative paths resolve against ComfyUI's working directory, not your home folder, and network shares can be slow enough to look like a hang. Absolute paths are the boring, reliable answer.
• Swapping the file for a different one silently costs a generation. The content hash is part of the request identity, so a different reference means a different request, which means new billing. Expected, but worth knowing before you burn credits on a typo'd filename.