Fal Reference-to-Video

Sometimes one reference image isn't enough. You want the clip to start on this frame and end on that one, or you want the video to hold a subject's identity across the whole shot. That's what Fal Reference-to-Video exists for, and it's the most interesting node in the ComfyUI-Fal-Gateway pack because it's the one with a real UI idea behind it.

The reference models here come in two flavors. First-last-frame (FLF) models like Kling's take a start image and an end image and animate the transition - the reliable way to get a "scene evolves" shot without the model wandering. Subject-reference models like MiniMax's take a character image and keep that subject consistent through the motion. Different jobs, same node.

Inputs and outputs

• model_id - dropdown of the reference-capable endpoints (Kling FLF, MiniMax subject reference, and whatever else fal surfaces).
• prompt - what happens between the references.
• image_count - an INT counter, 1 to 4, with +/- arrows. Bump it and more image sockets appear; drop it and they hide. This is the pack's signature UX, reused by its sibling nodes.
• image_1 - required. image_2..image_4 - optional, shown by image_count. Wire LoadImage into each.

Outputs match the other video nodes: frames (IMAGE batch → VHS_VideoCombine), video_url (STRING), audio (AUDIO, None on silent clips), and info (JSON string).

How it works

The image_count counter is a frontend trick with a real backend: the web extension shows or hides sockets as you dial the count, and the node collects every wired image into an array that gets uploaded to fal and sent to the endpoint's multi-image parameter. So "how many references" is a property of the node, not of the model - you pick a model from the dropdown, and the node adapts to however many images that endpoint's schema wants. That schema-driven adaptation is the pack's whole thesis, and this node is where you feel it.

Install

Same as the rest of the pack:

cd ComfyUI/custom_nodes
git clone https://github.com/modbender/ComfyUI-Fal-Gateway
pip install -r requirements.txt
export FAL_KEY=your_fal_key

Restart ComfyUI; everything lands under Fal-Gateway. No model downloads - the references and the rendering all happen on fal's side.

Gotchas

• This is the expensive end of the catalog. Reference video runs the most complex endpoints fal has, and the title-bar cost badge will tell you so. Dial image_count up and watch the estimate move before you queue.
• Fewer images than the model's required minimum errors out - e.g. an FLF model that needs a start and end image will raise a "required image input not connected" style error if you only wire one. Add the second reference rather than fighting it.
• Fresh nodes show <no models available> until the catalog fetch warms; right-click → "Fal-Gateway: refresh catalog cache" if it sticks.
• FAL_KEY unset → hard error with the fix in the message.

Worth knowing before you commit: reference-to-video is the same identity problem the image side solves with IP-Adapter-style adapters locally - except here the closed video models handle it, which no amount of local adapters will get you for Veo or Kling.