Sapiens2 Inference

Everything Sapiens2 does in ComfyUI funnels through this node. Feed it a SAPIENS2_MODEL from the Sapiens2 Model Loader plus an IMAGE, and out come three things: a visualization, a binary mask, and a JSON blob of metadata. The pack is just those two nodes, so once you understand this one you understand the whole install.

What would you use it for? This is the "human, specifically" toolbox. The usual suspects in ComfyUI are OpenPose/DWPose for pose and the ControlNet auxiliary preprocessors for segmentation - good, general-purpose, trained on everything. Sapiens2 is a transformer family pretrained on a billion human images, so for people shots it's a genuinely stronger source for the same jobs: hair or clothing masks for inpainting and compositing, a pose skeleton to drive a pose ControlNet, surface normals for relighting. The depth-estimation crowd already treats Sapiens as a serious entry; this is its modern successor wrapped for a graph you can actually run.

How it works

Mechanically it's simple under the hood. Dense tasks (seg, normal, pointmap) get resized to Sapiens2's 1024×768 input with ImageNet normalization, run through the model, then upsampled back to your original resolution. Pose is different and neat: the 308-keypoint heatmap head with UDP-style decoding, and it treats your whole image as the person crop - which means no DETR person detector bolted on like the upstream demo scripts. It processes IMAGE batches frame by frame, so a video loader that decodes to an IMAGE batch just works; the node itself never takes a native video object.

The inputs you actually set

• sapiens2_model - from the Model Loader. Match the task you loaded, obviously: a pose loader feeding a node wanting seg output is a mistake.
• image - any ComfyUI IMAGE. Batches and video frames included.
• segmentation_mask_class - the dropdown you'll touch most. Default -1: All foreground merges every non-background class into one person mask. Want only hair? 4: Hair. Only the top: 23: Upper_Clothing. There are 29 classes plus the -1 option. It only meaningfully applies to the seg task.
• blend_alpha - 0.55 default. How opaque the colored overlay is over the original photo. Lower it if you want to actually see the source through the rainbow.
• pose_threshold - 0.30 default. Keypoints below this confidence get dropped from the skeleton and the keypoint mask. Raise it if the pose output looks like static.
• pose_draw_links - whether the skeleton lines between keypoints get drawn, or just the dots.

Outputs and where they go

IMAGE is the visualization - the colored parsing overlay for seg, the skeleton drawing for pose, normal RGB, or a depth-style turbo map for pointmap. MASK is the star: for seg it's the selected class as a clean binary mask (perfect for inpainting, compositing, or masking nodes), for pose it's the keypoint mask, for pointmap the valid-point mask, and for normal a full mask. metadata_json carries the task, checkpoint, and per-image class counts, keypoint scores, and statistics - genuinely useful when you're scripting or debugging rather than eyeballing.

Installing

Same story as its sibling, since they ship in one pack: ComfyUI Manager (search "ComfyUI-Sapiens2"), or:

cd ComfyUI/custom_nodes
git clone https://github.com/starsFriday/ComfyUI-Sapiens2.git
cd ComfyUI
python -m pip install -r custom_nodes/ComfyUI-Sapiens2/requirements.txt

Dependencies are small - numpy, Pillow, safetensors, huggingface_hub. Then grab at least one set of weights before running, because with no checkpoint this node has nothing to say:

python custom_nodes/ComfyUI-Sapiens2/scripts/download_models.py --tasks seg --arches 0.4b

An example workflow ships in examples/Sapiens2.json - drag it onto the canvas, swap in your own image, and you're running. The included demo shows one loader feeding two inference nodes with different mask classes, which is the trick worth stealing: load once, mask hair and clothing in the same pass.

Where people get burned

• The mask means different things per task. -1: All foreground gives you a full person mask on seg - but on pose you get keypoints, not a silhouette. Don't assume a mask is a mask.
• VRAM. 1024×768 dense processing plus a big batch or 5B weights and you'll meet your GPU's limits. Process fewer frames at a time; the README calls this out.
• Video isn't a video. Feed it an IMAGE batch from a video loader, not a video path, and handle FPS/container stuff on your video combine node - Sapiens2 only sees frames.
• Task mismatch. Loader says pose, inference wants a person mask. The loader's load_info_json output is your friend here - preview it to confirm what you actually loaded.

Solid little node. It won't turn your GPU into a rig for motion capture, but for pulling clean human masks and skeletons out of an image without a dozen preprocessing nodes, it's about the fastest path there is.