PVL Segment (fal.ai)

PVL Segment (fal.ai) is a text-promptable segmentation node that runs entirely in the cloud. You give it an image and describe the thing you want - "the red car," "the person in the yellow shirt," "the building on the left" - and it returns a mask of that thing. No local model, no VRAM hit, no segmentation checkpoint to download. If you've got a GPU that struggles to run SAM-class models locally, or you just don't want another multi-gigabyte model sitting in models/, this is the convenient path.

It wraps fal.ai's evf-sam endpoint - EVF-SAM is one of the open-vocabulary SAM variants that fuses a vision-language encoder into SAM so you can segment by text description rather than by clicking points. On fal's infrastructure, the whole thing runs server-side. The node itself is part of the ComfyUI Assistant Node pack, which despite the name is really a large collection of cloud API wrappers plus local utilities.

How it works

The node base64-encodes your image as a data URI and posts it to the fal queue API, then polls until the job completes and downloads the result back as a normal ComfyUI IMAGE tensor. It handles batches too - a batch of images gets submitted in parallel threads with one request each, and results come back ordered. Set debug on if you want the console to tell you what it's doing at each step.

The two switches that define what comes back:

• mask_only (default on) - return just the mask. Off, you get the segmentation visualization.
• use_grounding_dino - run Grounding DINO first to detect the object your text names, then have the segmenter cut it. Good for getting a precise box first. Default off, because a plain text prompt is usually enough.

There's a stack of mask post-processing you can apply in the same call: revert_mask inverts it, blur_mask feathers it (the API enforces an odd kernel size, so it nudges even values up by one), expand_mask grows it by pixels, and fill_holes closes gaps. semantic_type toggles between semantic segmentation and the click-type mode, and seed only matters when the model has any randomness, which is rarely. negative_prompt is there for describing what you don't want included.

The input that matters

Just two, really: image and prompt. Everything else has sane defaults. Write the prompt as a plain description of the object - not a Stable Diffusion prompt, a sentence.

Output is a single IMAGE - the mask (or segmentation render), ready to feed into a crop node, an inpainting node, or a composite.

Installing it

It's part of pvlprk/comfyui-pvl-api-nodes. Install through ComfyUI Manager (search "ComfyUI Assistant Node") or:

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

Then the real requirement: a fal.ai API key. Set it as an environment variable named FAL_KEY (the code also accepts FAL_API_KEY or FAL_CLIENT_KEY) and restart ComfyUI so it picks it up. You'll need to top up credits at fal.ai - this is a paid cloud service, so every mask costs a little money, which is the tradeoff for not running it locally.

Where people get burned

The most common failure is the "FAL_KEY environment variable not set" error - either you never set it, or you set it after ComfyUI started. Set it in the same environment you launch ComfyUI from. On API errors the node prints to the console rather than failing the graph cleanly, so if a run "succeeds" but gives you a blank result, check the terminal output. And remember each call is a billable request - batch your images instead of running the node five times when you can feed it five frames in one go.