Beeble SwitchX Image

The one node that turns your graph into a Beeble customer

Beeble SwitchX Image is the production image node from the comfyui-beeble-switchx pack. Beeble (beeble.ai) is a commercial cloud platform - the same company behind SwitchLight, the inverse-rendering tech that turns video into PBR material maps and clean alpha for relighting. SwitchX is the cloud editing API that carries that lineage: you send it a subject shot, it does subject-aware editing against your prompt or a reference image, and it hands back the edited render plus the alpha matte it cut the subject with.

If that sounds like inpainting, it's inpainting with a phone bill. This node runs no model locally - it's an API wrapper, the exact pattern the external-api-nodes doc in the KB covers. Your image and prompt leave the machine for api.beeble.ai, get billed against your Beeble account, and the render drops back into the graph as if a local sampler made it. That's the deal: output from a closed pipeline you can't download, at per-call cost, with your source data on someone else's server. If that's not your jam, stay local - the community's center of gravity is genuinely split on exactly this trade.

How it works

Under the hood it's a five-step pipeline, the same one the pack's test nodes expose one step at a time:

1. Upload - the node saves the first frame of the IMAGE tensor to PNG, asks Beeble for a presigned upload URL, PUTs the file, and gets back a beeble_uri.
2. Start - POST /v1/switchx/generations with the URI, prompt, seed, resolution, and alpha mode.
3. Poll - it hits the job status endpoint every poll_interval_seconds until the job is completed, failed, or cancelled.
4. Download the render PNG.
5. Download the alpha PNG and load it as a MASK.

Transient network and SSL errors get a few automatic retries, so a blip mid-upload doesn't kill the run.

The inputs that matter

• image - your source. Only the first frame of a batch is sent, so don't feed it a batched set expecting one result per frame.
• prompt - multiline text. Provide this or connect reference_image; the API rejects a job with neither.
• alpha_mode - the dropdown that decides how the subject gets isolated:
  • auto - Beeble detects the subject itself.
  • fill - keep the original scene, no matting.
  • select / custom - you supply the mask (saved as a grayscale PNG under the hood).
• seed - the Beeble-side seed; change it to vary the result, same mental model as a local KSampler.
• max_resolution - 720 or 1080, the cap sent to the API.

timeout_seconds (default 600) and poll_interval_seconds (default 2.0) tune the polling loop - raise the timeout if Beeble is under load. mask is the optional MASK input and is required for select/custom.

Outputs: image (IMAGE) and alpha (MASK). That alpha is a real matte, not a hard silhouette - fractional values survive, which is the difference between a cutout that composites cleanly and one that crumbles. Wire alpha into a mask-to-image or composite step to drop the subject onto a new background.

Wiring it up

The README's canonical flow:

LoadImage -> Beeble SwitchX Image -> PreviewImage / SaveImage

For select/custom, also connect a MASK into the mask input. The repo ships a combined image+video demo at test_workflows/12_switchx_image_video_demo.json you can open and remix.

Install and the API key

No new Python dependencies - requirements.txt is empty, and the node rides on ComfyUI's own torch, numpy, and Pillow. Install through ComfyUI Manager (search "Beeble" or "SwitchX") or:

cd ComfyUI/custom_nodes
git clone https://github.com/albert999-pixel/comfyui-beeble-switchx

Then configure the key and restart ComfyUI:

cd ComfyUI/custom_nodes/comfyui-beeble-switchx
cp .env.example .env   # then put BEEBLE_API_KEY=your_key_here in it

ComfyUI Desktop users can instead set BEEBLE_API_KEY as an instance environment variable (Instance → Startup Args → Environment Variables). The key is read from the pack's .env first, then the environment. Never paste it into a workflow JSON - that's how keys get shared and leaked.

Where people get burned

• Black alpha output - if Beeble doesn't return a matte, the node outputs an all-zero (black) mask rather than erroring. Black alpha means "no matte came back," not "your subject is black."
• "mask is required" - select/custom with nothing connected to the mask input. And the reverse: a mask connected while alpha_mode is auto/fill is silently ignored (there's a warning in the logs).
• 401 errors - the key is missing or wrong; check .env and the environment.
• "provide a prompt or reference image" - both are empty. Leave one in.