ComfyUI Beeble AI

ComfyUI custom nodes for the Beeble AI API.

Currently exposes the SwitchX video-to-video / image generation model. The package is named generically so future Beeble models (e.g. background removal) can live alongside SwitchX without a rename.

Heads up: SwitchX is a paid API — every generation bills your Beeble account. You are responsible for your own usage costs. Check current rates at developer.beeble.ai before running long inputs. This package is an unofficial API wrapper; see License.

Maintenance: This is a self-serve project. It works for me and I'm sharing it as a starting point — feel free to use, fork, or copy the code (MIT). I'm not actively maintaining it: bug reports + PRs may sit unanswered, and Beeble API changes may take a while to land here (or never). If you depend on it, plan to maintain your own fork.

What it does

SwitchX is Beeble's flagship video-to-video model. Given a source video (or image), an optional alpha mask, an optional reference image, and a prompt, it re-generates everything outside the masked subject while preserving the original pixels inside it -- and relights the subject to match.

This package wraps the API in four nodes:

| Node | Purpose | |---|---| | Beeble SwitchX | The main one: upload source/alpha/reference (or pass URIs), submit a generation, poll until done with an on-canvas progress bar, return frames + alpha as IMAGE tensors. | | Beeble Upload | Pre-stage an asset on Beeble storage, return its beeble_uri. Use when running many SwitchX variations off the same source/reference -- one upload, N generations. | | Beeble Account Info | Show current rate-limit usage, concurrency, and spending limit. With include_billing ON, also fetches the period total + per-meter usage in USD. | | Beeble List Jobs | List recent SwitchX jobs (status, progress, type, timestamps). Useful for confirming concurrent-limit headroom or recovering after a cancelled workflow (the underlying API job keeps running and is billed). |

All nodes appear under the Beeble AI category in the ComfyUI node menu.

Installation

Via ComfyUI-Manager (once published to the Registry)

Search for comfyui-beeble-ai in ComfyUI-Manager and click Install.

Manual

cd ComfyUI/custom_nodes
git clone https://github.com/am-pipeline-prod/comfyui-beeble-ai.git
cd comfyui-beeble-ai
pip install -r requirements.txt

Restart ComfyUI. You should see "Beeble AI" in the node menu.

API key setup

Get your key at developer.beeble.ai/api-keys. The node looks for it in this order; the first one that resolves wins:

1. Environment variable (preferred for scripted / containerised setups)

export BEEBLE_API_KEY="bbl_sk_..."

2. Per-user config file (most users)

Create the file:

• Linux / macOS: ~/.config/comfyui-beeble-ai/config.toml
• Windows: %APPDATA%\comfyui-beeble-ai\config.toml

with this single line:

api_key = "bbl_sk_..."

Why not a node-input widget? Widgets get baked into saved workflow JSON files and into screenshots people post on Discord. Reading from env / config file keeps the key out of the workflow surface.

Quick example

The simplest possible SwitchX workflow:

1. Drop a Load Video (e.g. from VideoHelperSuite) → wire to Beeble SwitchX source.
2. Drop a Load Image with your reference look → wire to Beeble SwitchX reference_image.
3. Set:
   • generation_type = video
   • alpha_mode = auto (Beeble auto-detects the foreground)
   • max_resolution = 1080
   • prompt = "A young woman walking through a sun-dappled Korean palace courtyard."
4. Wire the SwitchX output to a Video Combine (VHS) or AM Write Video (am-pipe-media-io) node.
5. Queue Prompt -- the node shows a live progress bar while polling.

Two ready-to-load workflow JSONs live in examples/.

Alpha modes

| Mode | When to use | |---|---| | auto | Easiest. Beeble auto-detects the foreground subject. | | select | You provide a clean alpha for the first frame only; Beeble propagates it. | | fill | Keep the whole frame as-is -- no masking. Useful for global re-lighting / re-styling. | | custom | You provide a full per-frame alpha. Maximum control. |

When alpha_mode is select or custom, you must wire alpha (or set alpha_uri); the API rejects the request otherwise. With select, the alpha must be a single image even when generating video -- the node enforces this automatically when you wire an IMAGE input.

About IMAGE inputs and naming. ComfyUI's IMAGE type is always a batch [B, H, W, C]. The source and alpha sockets accept either a single still (image jobs / first-frame alpha) or a multi-frame batch (video jobs). reference_image is always a single still -- the Beeble API hardcodes it to one image; there is no array form and no per-frame targeting parameter.

Inputs reference

See docs/beeble-api-llms-full.txt for the full upstream API documentation (verbatim copy of https://developer.beeble.ai/docs/llms-full.txt at the time of writing). The most commonly tweaked fields:

• max_resolution -- 720 or 1080. Defaults to 1080 (the Beeble API's own default). Higher costs more and runs slower.
• prompt -- recommended even with a reference image. At least one of prompt or reference_image must be provided (API requirement, enforced client-side by the node).
• fps -- only used when encoding a wired source/alpha frame batch as MP4 in video mode. Ignored otherwise.
• poll_interval_seconds -- defaults to 15 s. Read endpoints are capped at 5 RPM per account, so going below ~12 s risks 429s.

Outputs

Each Beeble SwitchX execution returns:

• output (IMAGE) -- the rendered media. Single frame for image jobs, full frame batch for video jobs.
• output_alpha (IMAGE) -- the alpha track as the API saw it (1×1 black placeholder when no alpha is returned, e.g. with alpha_mode=fill).
• job_id (STRING) -- the SwitchX job id (e.g. swx_abc123).
• render_url (STRING) -- direct CDN URL to the rendered media. Expires after 72h -- re-fetch via GET /v1/switchx/generations/{id} if needed later.
• raw_json (STRING) -- pretty-printed final job document for debugging.

Limits and pricing

The SwitchX API enforces (per the Beeble docs):

• Source resolution: ≤ 2,770,000 pixels (W × H).
• Video length: ≤ 240 frames.
• Concurrent generations: 10 per account.
• Rate limit (write): 5 RPM.
• Rate limit (read, status polling): 5 RPM.
• Spending limit: configurable per account, default $5,000/period.

Pricing is metered per generation in USD -- Beeble does not expose any other currency. Use the Beeble Account Info node (with include_billing ON) to see current period spend, per-meter usage, and remaining budget. The API does not expose a per-job price quote, so the node cannot predict cost before running -- check developer.beeble.ai for current rates.

Troubleshooting

No Beeble API key found -- see API key setup above.

SOURCE_TOO_LARGE / VIDEO_TOO_MANY_FRAMES -- downsample or trim upstream of SwitchX before hitting the node.

CONCURRENT_LIMIT_EXCEEDED -- you have 10 SwitchX jobs in flight on this account already. Wait for one to finish or check the Beeble dashboard.

RATE_LIMIT_EXCEEDED while polling -- the node retries with exponential backoff; this is logged and recovers automatically. If it happens often, raise poll_interval_seconds.

Job hangs in in_progress -- the default timeout is 30 minutes per job. Long video jobs can exceed that; raise poll_timeout_seconds if needed.

Development

git clone https://github.com/am-pipeline-prod/comfyui-beeble-ai.git
cd comfyui-beeble-ai
pip install -r requirements.txt
# Run unit tests (no live API calls):
python -m pytest tests/

Architecture notes: docs/ARCHITECTURE.md.

License

MIT. Beeble is a trademark of its respective owner; this project is community-built and not affiliated with Beeble AI.