PVL Moondream3 Segmentation (fal.ai)

Moondream is the tiny vision-language model that keeps showing up where you least expect it, and this node wraps its fal.ai-hosted segmentation endpoint. You hand it an image and the word mango (the default, and honestly a weird default), and it hands back a mask of wherever the mango is. No SAM checkpoints on disk, no 12GB VRAM budget, no class labels to learn - just an object name and a mask output you can wire into an inpaint or a composite.

The appeal is obvious if you've ever watched a local SAM setup eat half your RAM for one mask. This is the "rent the heavy model instead of owning it" trade, and for a one-off segmentation job it's hard to beat.

How it works

The node base64-encodes your image and POSTs it to fal-ai/moondream3-preview/segment on fal's API. Your object string is the prompt the model segments against. If you feed it a whole batch of images, it doesn't wait around: it submits every request first, then polls for all of them in parallel, which is a genuinely nicer pattern than the submit-wait-submit-wait you get in a lot of these API packs.

The optional spatial_references_json is the power move - you can pin the search with normalized coordinates. Points like [{"x": 0.64, "y": 0.40}], or a box like [[0.10, 0.20, 0.40, 0.50]] as x1,y1,x2,y2. Handy when the model keeps finding the wrong object.

The inputs that matter

• object - the thing to find. Change it from mango; that's just the author's example.
• preview - true by default; gives you a viewable mask image as well as the raw mask.
• temperature, top_p, max_tokens - sampling knobs for the language side. Leave them alone until the mask is clearly wrong.
• sync_mode - false by default. Flip to true only if you're debugging latency.

The outputs are the interesting part: mask_preview (IMAGE) and mask (MASK) feed straight into inpaint or composite nodes, but you also get path (the mask as SVG path data), bbox_json, finish_json, and usage_json - useful if you're building automation and need geometry or token accounting rather than just a mask.

Installing it

This node ships in the pvlprk "ComfyUI Assistant Node" pack, so you get the whole grab-bag at once:

cd ComfyUI/custom_nodes
git clone https://github.com/pvlprk/comfyui-pvl-api-nodes

Restart ComfyUI. You also need a fal.ai key - the node reads FAL_KEY from your environment (it also checks FAL_API_KEY and FAL_CLIENT_KEY). Set it before launching ComfyUI:

export FAL_KEY="your-key-here"

No model files download. That's the whole point.

Common issues

The usual failure is "FAL_KEY environment variable not set" - the node is strict about this and it throws rather than quietly failing, which is a blessing. The subtler issues: remember your image is leaving your machine (base64 into fal's servers), so don't send things you'd rather keep local. And Moondream is a small model - on a cluttered scene it will cheerfully segment the wrong thing; that's what spatial_references_json is for. Costs are per-request on fal's side, so a 32-image batch isn't free. Start with one image, get the object name right, then scale.