OmniHuman 1.5 Subject Detection

What it is

A one-input helper node that exists to serve its sibling. Give it a portrait, it detects subjects and returns a mask image. That mask is what the OmniHuman 1.5 node's mask_url field wants when you need to specify which person in the frame gets animated.

Read the OmniHuman node's own tooltip and it says the quiet part out loud: "To have a specific subject in the image speak, use 'Subject Detection' to get the corresponding mask image and pass it as input." That's the whole reason this node is in the pack. Without a mask, the avatar endpoint decides for itself; with one, you decide.

The wider context is that this is the API answer to a local problem - audio-driven portraits are a real category now (docs/knowledge/audio-generation.md § 3), and segmentation-and-masking is its own little ecosystem on the local side (docs/knowledge/masking-detection-detailing.md). Here you outsource both in one call.

How it works

The node is generated from KIE's request schema for the subject-detection endpoint, which has exactly one documented input: an image. Yours is uploaded to KIE's storage by the pack and the returned URL goes into the request. The job is submitted as a task and polled to completion or timeout_seconds, and whatever the endpoint returns comes back through the node's sockets.

One thing to be clear-eyed about: this is a detection endpoint, not a generator. It doesn't produce a clip. The node's outputs are the standard media-shaped socket set because it's generated from the same video family as its siblings - reach for url and raw_json for the useful payload, not the video socket.

Inputs and outputs

Required:

• image_url (IMAGE) - the source picture containing the person (or people) you want to mask.

Optional:

• timeout_seconds (default 1200) - this endpoint is quick, so you'll rarely touch it.
• callback_url - leave empty for normal ComfyUI use.

Outputs: video, url, all_urls_json, task_id, raw_json, credits_consumed, credits_left. In practice you want the mask's URL out of url (or all_urls_json if more than one came back) and you want to sanity-check the run via raw_json.

The workflow this belongs to

1. Load or generate your group photo, pipe it into OmniHuman 1.5 Subject Detection.
2. Take the returned mask URL - through a text node if you want to keep it tidy, or straight into the field.
3. Paste that URL into OmniHuman 1.5's mask_url field, alongside your portrait and your audio track.
4. The avatar animation is then constrained to that subject. Everyone else stays still.

That's a two-step setup for something you'd otherwise be doing with manual masking in an image editor.

Install

Manager: search KIE-Nodes-Next by felipederosilva, install, restart. Or:

cd ComfyUI/custom_nodes
git clone https://github.com/felipederosilva/ComfyUI-KIE-Nodes-Next

Then save your key once: Settings → KIE.ai Nodes Next → Connection → Paste / replace KIE.ai API key. The pack validates it before storing and shows a masked fingerprint plus your balance. KIE_API_KEY also works and wins for headless setups. Requirements: requests, Pillow, numpy, PyYAML - nothing exotic.

Note that "omni" spelled slightly differently appears on both a pack title and a node class here; if you're copying a class name from somewhere, this node is KIE_Next_omnihuman_1_5_subject_detection_6dbc0cc0, under KIE Next / Video / OmniHuman.

Where people get burned

Expecting a video. The name says detection, the sockets say video. The sockets are wrong for your purposes - this is a metadata endpoint, so use url/raw_json.

The mask is consumed by URL, not by socket. There's no IMAGE input for a mask on the OmniHuman node. You need the URL this node returns, pasted or wired as a string.

Garbage in, garbage mask out. The detection is only as good as the photograph - heavy occlusion, a tiny face, or three people overlapping will get you a mask that's worse than no mask at all. Test on a clean frame first.

Model churn. KIE's catalog is live; endpoints get added and retired. If this stops resolving, drop in KIE • Refresh Model Catalog and let the pack re-sync from KIE's docs.

Cheap, but not free. Detection calls are small compared to a 1080p avatar render, and credits_consumed will tell you exactly how small.