🎭 Gemini Segmentation

Gemini Segmentation gives you proper per-object pixel masks from a natural-language description, which sounds like a superpower until you read the fine print: the model dropdown decides whether you get masks at all. That's the single most important thing about this node, and it's exactly where people get burned.

The model trap

Read the tooltip on model - it's the author being honest with you. Gemini 2.5 Pro and 2.5 Flash return native pixel masks (2.5 Pro is the default and the recommended pick). Gemini Robotics-ER 1.6 is Google's specialized spatial model and also does strong mask fidelity. But Gemini 3.x does not return pixel masks - boxes only. Pick 3.5 Flash or any of the 3.x names and your mask outputs come back empty. The 3.x models are in the list anyway, presumably as a convenience or a mistake, but for segmentation you want gemini-2.5-pro and you want it set to fixed in control-after-generate so nothing silently bumps it.

How it works

Send an image and a segmentation_prompt ("Segment all people and vehicles") to the API, get masks back, and the node binarizes them into ComfyUI MASK tensors using mask_confidence_threshold (default 127, the midpoint of 0–255 - raise it if masks come out noisy, lower it if they come out anemic). Then it draws the visualization image for you, with real choices: overlay, masks_only, side_by_side, or all. The overlay is tinted per segment with a color_mode (random, class_based, or single_color), and you can toggle draw_boxes and draw_labels on the visualization independently of the masks themselves.

The seed behaves like the rest of this pack's API nodes: image bytes + seed + params are hashed, so identical input means a cache hit and no API call. Free reruns while you fiddle with the visualization settings - a genuinely nice touch.

Outputs and what to wire them into

• visualization - the colored annotated image, for previewing or saving.
• raw_masks - the per-segment masks laid out as an IMAGE, if you want to inspect them.
• comfy_masks - the actual MASK batch, one mask per segment. This is the workhorse output.
• union_mask - everything unioned into one mask, handy for background removal.
• segments_json and summary - structured labels + a text summary.

Wire comfy_masks into Gemini Mask Crop and you're running the automated detailing loop from the KB - crop each segment, refine it, stitch it back. That loop is usually driven by local YOLO/SAM detectors; this is the cloud version that needs no weights and understands arbitrary classes.

Install and the bill

ComfyUI Manager (search "ComfyUI_Gemini") or git clone into custom_nodes, then pip install -r requirements.txt. Dependencies: google-genai - not google-generativeai, the classic wrong-package trap - plus python-dotenv and scipy. The pack auto-fixes a wrong google-generativeai install at startup. API key goes in the pack's .env (GOOGLE_API_KEY) or an environment variable; leave the node field empty so workflows stay shareable.

Costs are real: every unique image is a paid API call, and segmentation at 2.5 Pro is one of the pricier Gemini jobs. This is a small single-author pack (barely any community footprint by name), so treat the detailed console logs as your primary support channel. And remember the model rule: 2.5 for masks, 3.x for boxes-only.