Pixverse Swap (fal)

You've got a clip and you want to drop a different face - or a different object, or a whole different backdrop - into it without rotoscoping frame by frame. That's what this node is for. It calls Pixverse's video-swap endpoint on fal.ai and does the whole job in the cloud, so nothing renders on your machine.

The important thing to understand up front: this is a thin client, not a local model. The node uploads your inputs to fal, fal's Pixverse model does the work on their GPUs, and you get a URL back. No weights land on your disk, there's no VRAM ceiling to hit, and every run costs a bit of your fal balance. That's the whole bargain with this pack.

How it works

You feed it a source video and a reference image, tell it what in the video you're replacing with the mode switch, and it re-renders the clip with the swap baked in. Under mode: person it's a face/body swap; object swaps a thing in the scene; background replaces the environment behind the subject. The model tracks the target across frames so the replacement moves with the shot instead of sitting there like a sticker.

The inputs and outputs that matter

The three you'll actually think about:

• image (IMAGE) - the reference you're swapping in. A face for person mode, a product shot for object, a scene for background.
• mode - person, object, or background. This is the whole behaviour of the node; pick wrong and you'll wonder why the wrong thing changed.
• the source video - supply it either as a video (VIDEO) socket from another node, or as input_video_url (a string URL already on fal). Both are optional in the schema, but you need one of them or there's nothing to swap into.

The rest are quality dials: quality (360p / 540p / 720p, default 720p - higher costs more and takes longer), keyframe_id (which keyframe the swap anchors from, default 1), and original_sound_switch (default on - keep the source clip's audio).

Output is a single video_url STRING. That's a link to the finished clip on fal's servers, not a VIDEO you can scrub in the node. To see or save it, wire that string into the pack's Fal Save Media from URL node, which downloads it to your output/ folder. Those URLs expire, so grab anything you want to keep.

How to install it

It ships in gokayfem's ComfyUI-fal-API pack (same author behind the well-known ComfyUI_VLM_nodes). Easiest route: ComfyUI Manager, search ComfyUI-fal-API, install, restart. By hand:

cd ComfyUI/custom_nodes
git clone https://github.com/gokayfem/ComfyUI-fal-API.git
pip install -r ComfyUI-fal-API/requirements.txt

Then the step people skip: you need a fal API key. Copy config.ini.example to config.ini inside the pack folder and paste your key from fal.ai/dashboard/keys, or export FAL_KEY=your_key in your environment. Restart ComfyUI. On Windows Portable you may also need .\python_embeded\python.exe -m pip install fal-client. There's no model download - the model lives on fal.

Common issues & troubleshooting

"Insufficient funds" or the node errors before generating. fal is a paid credit service and you're billed per call. It's a legitimate platform (a well-funded one), but its billing has occasionally lagged for people - credits showing late, invoice hiccups. If a top-up hasn't landed, wait for it to settle rather than paying twice, and keep an eye on your balance in the fal sidebar.

The wrong thing got swapped. Check mode. Person, object, and background are three different jobs and the node does exactly the one you named.

The video socket is empty or shows None. Native VIDEO types need a recent ComfyUI - update it. If you're pulling the clip from a URL instead, use input_video_url.

Content-policy refusal. fal returns its actual error text straight into ComfyUI. If it's a policy block, the message says so; swaps involving real people are the usual trigger.