JSON Regions to SAM3 Boxes API

First, the name is a lie. "SAM3 JSON Boxes API" sounds like something that phones home for a key and a credit card. It doesn't. This is a tiny, dependency-free node that parses a blob of JSON you paste in and turns it into the SAM3_BOXES_PROMPT format that ComfyUI-SAM3 expects. No API, no network, no model download. It exists for one reason: SAM 3's box prompts are easy to click but annoying to script, and if your boxes arrive as data instead of as clicks, you need a bridge.

Why you'd reach for it

SAM 3 is Meta's promptable concept segmentation model - the one that took ComfyUI by storm after November 2025, because a short phrase or a box gets you clean masks for every matching instance at once. The standard way to prompt it is the box prompt: draw rectangles over the image, get masks, feed those to inpainting or regional editing. That's great when you're pointing at a screen.

But the moment your boxes come from somewhere else - a detection script, an object tracker, an external "API" that hands you JSON regions, a batch job where every frame's regions were computed outside ComfyUI - you need to convert that data into the exact structure SAM3 wants. That's this node. It's the data-injection seam between whatever produced your boxes and the SAM3 masking step.

How it works

You give it an image and a JSON string; it reads the image's dimensions, parses your regions, normalizes every box to SAM3's centered format (center_x, center_y, width, height, all 0–1 relative to the image), and labels them positive or negative. The image input exists only to supply those dimensions - it isn't segmented here, just measured.

The genuinely useful part is how tolerant the parser is. It accepts four coordinate conventions per region:

{ "regions": [{ "x1": 78, "y1": 0, "x2": 312, "y2": 119 }] }
{ "regions": [{ "x1": 78, "y1": 0, "width": 234, "height": 119 }] }
{ "regions": [{ "x": 78, "y": 0, "w": 234, "h": 119 }] }
{ "regions": [{ "x": 78, "y": 0, "width": 234, "height": 119 }] }

It even accepts a bare list of regions with no wrapper object, or four-number arrays. Negative regions come from a negative_regions or negative_boxes key - that's your "keep SAM3 away from here" list.

The inputs that matter

• json_text - the whole game. A multiline string holding your regions. The default is a working example, so if you're lost, paste the defaults and hit run.
• image - required, but only used for width/height so boxes get normalized correctly. Feed it the image you're masking.
• padding - pixels to expand each box by (0–512). Handy when a detector's box hugs the object too tightly; the node clamps to the image edges and silently skips any box that collapses to zero size.

Outputs are positive_boxes and negative_boxes (both SAM3_BOXES_PROMPT, wired straight into the SAM3 box-prompt input) plus debug_info, a plain string that tells you image size, how many regions became boxes, and the padding applied - genuinely useful when a box silently vanishes.

Install

Easiest via ComfyUI Manager - search "JSON Regions to SAM3 Boxes API" - or clone it manually:

cd ComfyUI/custom_nodes
git clone https://github.com/daminik124124-ops/ComfyUI-SAM3-JSON-Boxes-API

Then restart ComfyUI. That's it: the pack ships with zero Python dependencies, so there's no venv surgery and no model to babysit. You do need ComfyUI-SAM3 installed alongside it, because that's where the SAM3_BOXES_PROMPT type actually lives.

Where people get burned

Two things. First, coordinates must be in pixels relative to the image you feed in - if your JSON came from a differently-sized source, everything will be misaligned and SAM3 will mask the wrong places. Second, remember SAM3's license: SAM 3 ships under Meta's SAM License, not the permissive Apache terms of SAM/SAM 2, so read it before you ship a product on top of this. For a local workflow you're fine. For a utility node that's the whole story - paste JSON, get boxes, mask.