Flux Kontext Max

First, the trap hiding in plain sight: despite living in a pack called "geminiapi", this node has nothing to do with Gemini. It calls Replicate. The api_key field is where you paste your Replicate API token, and the request goes to the black-forest-labs/flux-kontext-max model. Get that wrong and every run silently returns a black image. Nobody reads this far before wiring in a Gemini key, so consider yourself warned.

What you're actually getting is the API-only top tier of Flux Kontext - Black Forest Labs' instruction-based editor. Feed it an image and a sentence ("make this a 90s cartoon" is the node's default prompt), and it edits that specific image: swap the background, change the clothing, remove the watermark, keep the person recognizable. Kontext works in-context rather than through adapter embeddings, which is why it holds identity across successive edits better than the IP-Adapter crowd ever did. Max is the experimental premium tier - BFL positions it as the one with the best prompt adherence and typography, at no speed cost claimed. If you've been doing turnaround sheets and character-consistency work in ComfyUI, this is the API shortcut to the model the local 12B Dev weights only approximate.

How it works

The node takes your IMAGE tensor, converts it to a PNG in memory, and hands it to Replicate along with prompt, aspect_ratio, output_format, and safety_tolerance. Replicate runs the model in the cloud, hands back a URL, and the node downloads the result and converts it back to a tensor. No weights, no VRAM, no local sampler - the price is per-API-call, and the model is heavily censored at the source.

One thing to know before you get excited about the character-consistency hype: Kontext's entire story is tangled up in BFL's license crackdown. The API tiers enforce content restrictions, and any attempt to route around them is a license violation. Qwen-Image-Edit is the unrestricted local rival if that's the job you actually have.

Inputs and output

The required inputs are all you get - no optional ports here:

• image - the picture you're editing.
• prompt - the instruction. This is the whole game; be specific.
• api_key - your Replicate token (yes, really).
• aspect_ratio - defaults to match_input_image, which is the right call most of the time. The other 13 choices are the usual ratios.
• output_format - jpg or png.
• safety_tolerance - 0–6, default 2. This is the content filter dial.

Output is a single image of type IMAGE, ready to wire into a preview, an upscaler, or the next edit in a chain.

Installing and the failure mode

Same pack as the rest of this repo - install once via ComfyUI Manager (search "Comfyui-geminiapi") or:

cd /path/to/ComfyUI/custom_nodes
git clone https://github.com/zhanglongxiao111/Comfyui-geminiapi.git
cd Comfyui-geminiapi
python -m pip install -r requirements.txt

Then restart and look under ExternalAPI/Image/Edit. Dependencies include the replicate and pillow packages, which pip handles.

Now the failure mode that will bite you: if anything goes wrong - bad token, rate limit, prompt rejected - the node catches the exception and returns a solid black 512×512 image, and it does it silently. A black output is not a generation choice, it's the node telling you to check the console for the real error. The sibling Flux Kontext Pro node in the same pack is byte-for-byte the same code with flux-kontext-pro swapped in - Pro is the faster API workhorse, Max the typography/quality experiment. Start with Pro if you're cost-sensitive; this one if you want the flagship.