InsightFaceBBOXDetect

What it is

InsightFaceBBOXDetect finds every face in an image and hands you back both a visual, numbered annotation and the raw coordinates as JSON - a detection-only node, not a face-swap or identity-preservation one. It's built on InsightFace, the face analysis library that quietly sits underneath nearly every no-training identity tool in the ecosystem (IP-Adapter FaceID, InstantID, PuLID, ReActor all lean on the same InsightFace/ArcFace backbone under different front ends). This node uses that same detection machinery for a narrower job: locate faces and describe where they are, full stop. No embeddings, no swapping, no identity transfer.

Where this earns its "EasyApi" placement: the bbox output is a plain JSON string - every face's corner coordinates in one serialized blob - exactly the shape you want if a workflow is driven programmatically and needs to hand detection results back to a caller, rather than ComfyUI's typed BBOX socket.

How it works

Run it on an image and it finds all the faces, draws a box (or circle) around each one in your chosen color, and optionally numbers them. The numbering options exist because "face #2" only means something if you can control what counts as #2 - num_pos places the number relative to each box, and num_sort decides the ordering (left to right, top to bottom, by size, or the detector's own native order). Get the sort order wrong and "face 0" downstream isn't the face you thought it was.

The optional INSIGHTFACE input/output pair lets you reuse an already-loaded model across multiple nodes rather than each one loading its own copy. Loading InsightFace models isn't free, so this matters if you're running detection more than once in a workflow.

Inputs and outputs

• image (IMAGE, required).
• shape (enum, default rectangle; choices: rectangle, circle) - the annotation shape drawn around each face.
• shape_color (STRING, default #FF0000) - hex color for the box/circle.
• show_num (BOOLEAN, default false) - whether to draw a number on each detected face.
• num_color (STRING, default #FF0000, optional) - hex color for the numbers, if shown.
• num_pos (enum, optional; choices: center, left-top, right-top, left-bottom, right-bottom) - where the number sits relative to the box.
• num_sort (enum, optional; choices: origin, left-right, right-left, top-bottom, bottom-top, small-large, large-small) - the order faces get numbered in.
• INSIGHTFACE (INSIGHTFACE, optional) - a pre-loaded InsightFace model to reuse instead of loading a fresh one.

Outputs: bbox_image (IMAGE - the original image with boxes/numbers drawn on), bbox (STRING - a JSON string of every face's corner coordinates), face_size (INT - how many faces were found), INSIGHTFACE (the loaded model, for chaining to the next node).

Installing it

Bundled in comfyui-easyapi-nodes. Through ComfyUI Manager: search "comfyui-easyapi-nodes", install, restart ComfyUI. Manual install:

cd ComfyUI/custom_nodes
git clone https://github.com/lldacing/comfyui-easyapi-nodes.git
cd comfyui-easyapi-nodes
pip install -r requirements.txt

This is the one node in the batch where pip install -r requirements.txt genuinely isn't optional - the requirements pull in the insightface package, historically one of the most painful installs in the ecosystem (it needed a C++ build toolchain for years, Visual Studio on Windows). InsightFace 1.0 (2026-05-23) finally dropped that requirement for the default install, so a fresh install today should be much less painful than older guides make it sound - but an old cached version is the first thing to upgrade if install is failing.

You'll also need the model weights, though there's nothing to fetch by hand for the common case: InsightFace auto-downloads its default buffalo_l pack on first use. Those weights are licensed non-commercial by InsightFace's own terms - fine for personal or portfolio work, worth checking before shipping anything you intend to sell.

Common issues

"Install fails on the insightface package." Update pip first, and check which insightface version the pack pulled - anything before 1.0 may try to compile from source, and on Windows that means needing Visual Studio build tools that 1.0+ no longer requires.

"No faces detected in an image that clearly has faces." Small, angled, occluded, or low-resolution faces are the usual suspects for any face detector. Try a higher-resolution source if the faces are tiny in frame.

"The numbers don't correspond to what I expected downstream." Check num_sort - it's easy to assume "face 0" means "leftmost face" when the detector's native (origin) order might be scan order or confidence instead. Pin it to left-right or whichever ordering your downstream logic actually depends on.

"Detection is slow the first time, then fast after." That's the model load on first run - expected, and exactly why the INSIGHTFACE output/input pair exists: reuse it instead of paying that cost again in a chained workflow.