SubstituteBackendLoadImageMask

SubstituteBackendLoadImageMask is the mask-flavored sibling of SubstituteBackendLoadImage, and it has the same trick up its sleeve: the image input is not a file path. It's an opaque authorization token minted by the Substitute BackEnd extension, the ComfyUI-side companion for the SugarSubstitute front-end (an alternative ComfyUI client in Qt from the same author, in beta since mid-2026).

When SugarSubstitute needs a mask out of a local image - say you drew a mask on the canvas, or you're feeding an existing PNG's transparency into an inpainting workflow - it authorizes the file through /substitute/v1/local-assets/authorize and gets back a token plus the class of the node that should execute it. This node is that execution class for mask loading. The difference from the plain loader is one extra dropdown and a single output type: it hands you the exact channel you asked for as a MASK, nothing else.

How it works

The mechanics are shared with its sibling: tokens expire after roughly an hour, the file is re-verified by size/mtime/inode at every use, and the cache key (IS_CHANGED) is the file's content hash plus the chosen channel - so switching from red to blue re-runs the node, and re-running it costs nothing if the file and channel are unchanged. The decoder is the same PIL pipeline: EXIF-transposed, converted to RGB, frames batched. Then, instead of returning the image and an alpha mask, it pulls one channel out as a single MASK tensor.

The inputs that matter

• image (STRING) - the authorization token, not a path. Same story as the image loader: type a path here and validation fails on purpose.
• channel (enum: alpha, red, green, blue) - which channel becomes the mask. alpha is the one you'll reach for with transparent PNGs: it's the inverted alpha (1.0 - alpha), so 1 = opaque, exactly what core LoadImage and LoadImageMask emit. Red/green/blue grab that color channel from the RGB image instead - handy when the mask is baked into a color channel, a trick people use to smuggle masks through image hosts that strip alpha.

Output

• MASK - a single-channel tensor you wire into anything that eats a mask: VAE Encode (for Inpainting), a detailer, Latent Composite, the mask input of a paste node. Standard semantics, so your existing mask-blur and mask-dilate nodes between this and the sampler all work unchanged.

Install

Same pack, same steps. ComfyUI Manager → search "Substitute BackEnd", or:

cd ComfyUI/custom_nodes
git clone https://github.com/Artificial-Sweetener/Substitute-Backend.git
cd Substitute-Backend
# into your ComfyUI venv
python -m pip install -e .

Needs Python 3.12+; deps are just aiohttp, requests, and sugar-dsl - no model downloads, nothing heavy. Restart ComfyUI.

Gotchas

• Again: if you don't run SugarSubstitute, you don't need this. For hand-built workflows, core LoadImageMask gives you the same channel-picking behavior with a path widget you can actually type into.
• "Invalid or expired" means the token aged out or the file changed after authorization - re-select the image in the front-end to get a fresh token.
• The channel must be one of the four enum values; anything else fails validation with "Unsupported local mask channel." (You won't hit this through the UI.)

It's a tiny, single-purpose node - a channel extractor wearing an authorization badge. That's the whole job, and it does it cleanly.