Beeble SwitchX Video

The video half of Beeble SwitchX, and the one that actually earns the API

Beeble SwitchX Video is the production video node from comfyui-beeble-switchx. Beeble's whole identity is inverse rendering - their SwitchLight tech converts footage into PBR maps, depth, normals, and alpha for relighting - so this is the node that brings that matting muscle into a ComfyUI graph. You feed it a video, it does subject-aware editing against your prompt or a reference image, and it hands back the edited clip and the alpha video it extracted, frame by frame.

Same deal as the image node, plus one crucial difference: this is a closed commercial pipeline, so nothing runs locally. The video, the prompt, and your reference image all go up to api.beeble.ai, get billed against your Beeble account, and the render comes back down. It's an API-wrapper node in the external-api-nodes mold - capability you can't download at per-call cost, with your footage on someone else's server. If you need the subject changed, a local Wan/LTX re-draw loop is the no-cloud alternative; if you need it keyed and relit like SwitchLight, this is the node that's honest about where that quality lives.

How it works

The pipeline is upload → start → poll → download, just like the image node:

1. The VIDEO input is saved to a temp .mp4 and uploaded via a presigned URL, returning a beeble_uri.
2. POST /v1/switchx/generations starts the job with generation_type: video.
3. The node polls the job status until it's completed, failed, or cancelled.
4. It downloads the render and, when Beeble returns one, the alpha video - loaded as ComfyUI VIDEO via the engine's native video input support.

A couple of mechanism details worth knowing. First, video results are written to a runtime/ folder inside the pack (deliberately not held in memory) that gets wiped on the next ComfyUI start - don't rely on it for persistence. Second, if Beeble doesn't return a separate alpha video, the node quietly reuses the render as alpha_video and logs a warning, so an alpha_video output that looks exactly like your render is the fallback, not a matte.

The inputs that matter

• video - your source clip. Requires a ComfyUI build with the native VIDEO type.
• prompt - multiline text. Provide this or connect reference_image; the API rejects a job with neither.
• alpha_mode - how the subject is isolated:
  • auto - Beeble detects the subject automatically.
  • fill - keep the scene, no matting.
  • select - you provide a single-frame mask via alpha_keyframe_mask, and alpha_keyframe_index says which frame that mask came from (0 = first).
  • custom - you provide a full frame-by-frame alpha_video.
• seed - Beeble-side seed; vary it to vary the result.
• max_resolution - 720 or 1080.
• timeout_seconds (600) and poll_interval_seconds (2.0) - the polling knobs.

Outputs: video (VIDEO) and alpha_video (VIDEO). Wire the alpha_video into a compositing or alpha-over step if you want to put the edited subject onto a new background.

Wiring it up

The README's recommended select flow shows the slightly fiddly part - you need to grab a frame out of your video to paint the mask on:

LoadVideo -> GetVideoComponents -> ImageFromBatch -> mask editing -> Beeble SwitchX Video -> SaveVideo

For custom, connect your alpha_video directly. The repo's test_workflows/12_switchx_image_video_demo.json has both branches wired up.

Install and the API key

No extra Python dependencies (requirements.txt is empty); the pack needs ComfyUI's built-in video input support, so keep ComfyUI current. Install via ComfyUI Manager (search "Beeble" or "SwitchX") or:

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

Then set the key and restart:

cd ComfyUI/custom_nodes/comfyui-beeble-switchx
cp .env.example .env   # add BEEBLE_API_KEY=your_key_here

ComfyUI Desktop users can set BEEBLE_API_KEY as an instance environment variable instead. The pack reads .env first, then the environment.

Where people get burned

• Frame cost sneaks up. Beeble is coin-priced, and community reports put SwitchX video around a 240-frame cap per job. Check your plan before feeding it a long clip - a 30-second job at 30fps is already at the ceiling.
• select with no mask - alpha_keyframe_mask must actually be connected, not bypassed.
• custom with no alpha video - alpha_video must be connected; the API won't run custom mode without it.
• alpha_video == video - that's the fallback kicking in because Beeble returned no separate alpha. It's not a matte; treat the result as "no key was delivered."
• No VIDEO socket at all - your ComfyUI build predates native video input support. Update before blaming the pack.