Video Head Swap · Video Edit

Where the swap lands

The analysis pass found and numbered every head. This node replaces the ones you choose - one to three reference photos each, up to ten heads per request, from $0.064 per second. Body, motion and the original audio stay as shot, at 480p or 720p.

The distinction from the face-swap video node is the same as in the image pair: this one takes the whole head, hair and silhouette included, which is what you want when the target's hairstyle has to change, and what you don't want if the target's hair was the point.

How it works

The node calls spicyapi/head-swap-video-v1/video-edit with the analysis task id, your target list, a matching resolution and a seed. It returns an MP4 as a ComfyUI VIDEO. Everything runs server-side - no local model, no tracker to install, no per-frame post-process to smooth afterwards.

That last point is the real argument over a local swapper: tracking happened once, in the analysis pass, and the swap is conditioned on it, so identity doesn't have to be re-guessed frame by frame. Jitter is the classic failure of frame-by-frame face replacement, and this architecture sidesteps it.

Inputs

analysis_task_id (STRING) - the task id from the analysis node. Wire it across rather than retyping. It stays usable for 24 hours, and its preview stills are listed in the same order as the object_index values you're about to write.

swap_targets (STRING, JSON) - one entry per head you want replaced. Each entry is an object with "image_urls" (one to three reference photos) and "object_index" (the 0-based head number from the analysis previews). Heads you leave out aren't touched, so a six-person shot where you only need one swap is a one-entry list. This is the field that justifies the two-node design.

resolution - 480p or 720p. Must match the analysis value or the request is rejected, and it sets the price tier.

seed - fixed by default, with control after generate. Randomize and you pay again.

video_url (optional, VIDEO) - leave it out and the video from the analysis task is used. If you do connect it, it must be the same video, or rejection. Simplest habit: don't connect it.

Outputs: video (VIDEO) and task id (STRING).

Install

Manager → search SpicyAPI, or:

cd ComfyUI/custom_nodes
git clone https://github.com/spicyapi-ai/comfyui-spicyapi

Restart, and you're done - no pip install, no weights, no GPU requirement, because the pack declares zero dependencies and every model is hosted. Python 3.10+ and a ComfyUI with the V3 node API. Set the key in Settings > SpicyAPI or SPICY_API_KEY, restart once so the model list comes from your account, and set Max cost per run.

Cost, honestly

$0.064/second is not a rounding error. A 20-second clip with two heads replaced is about $2.56 before you've iterated once. Do the whole chain - analyse, swap - on a 5-second trim, settle the reference photos and the target indices, and only then run the full clip. The price is quoted on the node before the run, and the guardrail in Settings will refuse anything above your ceiling instead of quietly charging it.

Where it snags

• Stale or expired task id. New analysis run, new id. Old id, or one older than a day, and the edit node has nothing to point at.
• Reference photos are everything. Two or three clean, frontally lit shots. There is no prompt on this node; the photos are the whole instruction, and a reference head with dramatic hair will transplant that dramatic hair.
• Audio stays as shot. Usually a bonus on a dance or action clip, occasionally a problem when the new identity should sound different.
• Cancelling just stops your wait. If the job finishes server-side, it's billed and the output waits in your console for up to 14 days.
• You are the consent layer. Head-swapping real people into clips is squarely in the territory that gets platforms and providers in trouble, and the endpoint has no guard for it.