Video Head Swap · Video Analysis

A tracking pass, not an edit

This node does one thing: it watches your clip at 480p or 720p, tracks every head in it, and hands back one numbered preview still per head. It does not change the video. $0.08 per run, and for that you get the information you need to make the swap call deliberate instead of hopeful.

Does that extra step feel annoying? A little. It's also the reason the head-swap chain is controllable at all - with a crowd, a background extra or a reflection in shot, "swap the head" is a coin flip. Here you see the numbered heads, pick which ones to replace in the second node, and pay attention only where you want it.

How it works

The clip gets uploaded (90 MiB ceiling) and the node calls spicyapi/head-swap-video-v1/video-analyze. Tracking runs entirely on SpicyAPI's servers - nothing local, no dependency install, and the resolution of the tracking pass doesn't affect what this call costs. What it definitely affects is the second call, because the swap has to run at the same resolution.

Outputs are the payload:

• previews (IMAGE) - one numbered still per detected head, in detection order. These are your visual index; object index 0 in the next node is the first preview here.
• text (STRING) - the readout from the analysis. Useful for logging what the model actually found, and for telling an empty result from a failed one.
• task id (STRING) - wire this into the Video Head Swap · Video Edit node's analysis_task_id field. It's valid for 24 hours.

Inputs

video_url (VIDEO) - the source clip, 5 to 30 seconds, MP4. Upload it with the core Load Video node or pass a public MP4 URL. Whatever you use here, the swap call must see the same video - so keep the same Load Video node in the graph rather than re-importing the file.

resolution - 480p or 720p, default 720p. Read the tooltip before changing it: the swap must run at the same value, so pick the resolution you want the finished clip to have. Choosing 480p to save on tracking gains you nothing and locks your output down.

Install

Manager → search SpicyAPI, or:

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

Restart. The pack ships no dependency install and no model files - its dependency list is literally empty - so this works on a machine with no GPU at all. You need Python 3.10+ and a ComfyUI recent enough to expose the V3 node API. Then a key in Settings > SpicyAPI (or SPICY_API_KEY) and one more restart so the node list is built from your account. Set Max cost per run before you queue anything in the video category.

Traps

• Three seconds, or forty. The 5-to-30-second window is enforced, and clips outside it are rejected before you're charged. Trim first.
• Stale task ids are the #1 failure. Re-running analysis mints a new id. If the edit node still holds the old one, your target indices point at a different video's detection order. Rewire it every time, and remember the 24-hour expiry.
• Resolution must match downstream. Not a suggestion; a mismatch is a rejected request.
• A head that isn't detected can't be swapped. Reflections, deep background figures, people who appear for half a second - check the previews count against what's actually in your clip before assuming the swap failed.
• Cancelling releases you, not the job. If the run completes server-side it's charged, and the result sits in your console for up to 14 days.