FeiHou-API Media

FeiHou-API Media is a gallery node - a reference shelf that holds up to 9 images, 3 videos and 3 audio files. Drop files in, and the panel gives you thumbnails you can swap, delete, reorder within a type, plus audio you can trim. Then type @ in the API node's prompt and pick which slot you mean.

That's all it does. It generates nothing, uploads nothing, and needs no key. Its one job is to make "these five pictures, in this order, are the references" something you can see and click instead of a pile of LoadImage nodes you re-wire every session.

It matters more than it sounds. Reference-driven generation is where 2026 went: the old embedding stack gave way to edit-and-reference models that just look at your images, and the friction is now keeping track of which reference is which. Multi-character work is the clearest case - features bleed between subjects unless each one has its own clearly labelled input. A numbered shelf plus @image 2 in the prompt is that, minus the spaghetti.

How it works

There's one input, media_files, a string of JSON that the pack's frontend hides and replaces with the gallery. Each record is a slot: media type, ordinal, storage location (input/temp/output - normally input), subfolder, filename, and for audio an optional trim.

So the node is a manifest, and a strict one. At execution it resolves every record against ComfyUI's own media directories and throws if a file is outside the root, missing, or the wrong extension for its type - png/jpg/jpeg/webp/bmp/gif, mp4/webm/mov/mkv/avi/m4v, wav/mp3/flac/ogg/m4a/aac. It fingerprints path, mtime and size too, so swapping a file at the same path re-triggers the workflow instead of quietly reusing old work.

The transfer happens later, in the API node: it reads each resolved file, uploads it to the provider, and rewrites @image 2 into whatever that model expects (图片2 for most, @Image 2 for Seedance). That's why the syntax is loose - @图片 1, @image 1 and @图 1 all land the same place.

The output is one socket, media, of the pack's FEIHOU_API_MEDIA type. Wire it into the media input of FeiHou-API Images or FeiHou-API Video, then type @ in that node's prompt. Records survive node duplication and workflow saves; the files themselves stay in your ComfyUI input directory.

One design note that saves headaches: media is a wildcard socket, so the loader is a convenience, not a requirement. A single IMAGE or AUDIO wire plugs straight in. Reach for the loader when you want the visual menu, more than one reference, or mixed types.

How to install it

ComfyUI Manager: search ComfyUI-FeiHou-Toolbox, install, restart. Manual:

cd ComfyUI/custom_nodes
git clone https://github.com/FX-FeiHou/ComfyUI-FeiHou-Toolbox.git

Restart and hard-refresh the browser - the gallery is frontend JS and CSS, and a stale page shows an empty node with a confusingly blank widget. No dependencies, no downloads.

Common issues

• "Media file is missing or invalid: image 3." The file moved or got renamed. The shelf points into the input directory, so cleaning up ComfyUI/input is what usually causes it. Re-add the file in the panel.
• "Prompt references an empty media slot: @image 3." You referenced a slot that isn't loaded. That's a feature - it stops you spending a call on a reference the model never received.
• "This image API does not accept video or audio references." Provider limits, per model. The loader happily holds a mixed shelf; the API node enforces the rules. The ones you'll actually hit: Seedance -t2v takes no references at all (use an -i2v or -multi variant), -i2v wants one first-frame image and optionally one last frame, -multi wants at least one reference, Qwen Image caps at three images, and only genuinely multimodal models take audio.
• Order is meaning. Reordering the gallery changes what @image 2 points at. First-frame/last-frame conventions are real on some video models, so if output looks like a blend of two shots, check shelf order before blaming the prompt.
• Test here first. Loading and resolving is entirely local; if the shelf looks right and the run still fails, the problem is on the API side.