Fal Kontext[Max] Multi-Image API

The one thing to know

The single-image node in this pack is a friendly on-ramp. This one is the point. FalKontextMaxMultiImageNode is a cloud wrapper around BFL's Kontext Max tier - the top, API-only member of the Flux Kontext family, the one the open-weights Dev model is measured against and falls short of. It feeds up to four reference images into the model at once, along with one prompt, and Max figures out who's who and what goes where.

That's its whole reason to exist. Kontext's in-context design already holds a subject across edits better than adapter-based approaches, and Max is the strongest version of that. Feed it a style shot, a face, and a pose, write "using this style, a bunny, a dog and a cat are having a tea party," and you get one coherent image instead of four collisions. No 12B weights on your disk, no VRAM gymnastics - just a fal.ai key and a per-call fee.

How it works

Same skeleton as its sibling: every input tensor becomes a PIL image, each one is resized to fit under 1.25 megapixels and uploaded to fal's storage, then the pack calls the fal-ai/flux-pro/kontext/max/multi endpoint with sync_mode on and waits. The result comes back as a tensor named images - but don't let the plural fool you: the node hardcodes num_images to 1, so you get one output image per run, not one per input.

Where this node earns its keep over the single version is the knob set. It exposes what the other one hides - guidance scale, image prompt strength, step count, output format, and the safety dial are all right there on the widget. Note this node lands under Fal/Kontext in the menu while its sibling sits under image/generation, so search for "Kontext" if you can't find it.

Inputs and outputs that matter

• image1 is required; image2, image3, image4 are optional. The more references, the more the model has to reconcile - start with two.
• image_prompt_strength - how hard the reference images push on the result. Default 0.1 is gentle guidance; crank toward 1.0 when you need the subject to actually match.
• guidance_scale - prompt adherence, default 3.5. Dial it up when the instruction isn't landing.
• safety_tolerance - the NSFW filter, 1 (strictest) through 6 (default, most lenient). Even at 6, Kontext's weights are censored, so this is a filter dial, not an unlock.
• num_inference_steps (default 30), output_format (jpeg/png), aspect_ratio (match the input, or force 1:1, 16:9, etc.) - set and forget.

seed is where it gets slightly awkward. The single node swaps -1 for a random seed before sending; here the code passes your seed straight through to the API. The README claims 0 means random, but that substitution isn't implemented in this node - so if reproducibility matters, set a real number.

The three outputs are the same as the sibling: images (your result, into SaveImage/PreviewImage), info (request ID, seed used, and a per-image safety check breakdown - genuinely useful with multiple references), and passed_nsfw_filtering, a boolean you can route into a "save on true" node so blocked output never touches disk.

Installing it

Shared with the pack - ComfyUI Manager ("ComfyUI-Kontext-API"), or:

cd ComfyUI/custom_nodes
git clone https://github.com/SanDiegoDude/ComfyUI-Kontext-API
cd ComfyUI-Kontext-API
pip install -r requirements.txt

Light dependencies - fal-client, requests, Pillow, numpy - and no model downloads. You do need a fal.ai key: set FAL_KEY as an environment variable, or put a bare key in a .fal_key file inside the pack's directory.

Things that will bite you

• A black image isn't a crash. When the API fails, this node returns a black tensor of the same size as your input with the error text stuffed into info and passed_nsfw_filtering set to False. If your output is suddenly a black frame, that's the error path - read info.
• "FAL API KEY NOT FOUND!" - the .fal_key file belongs in custom_nodes/ComfyUI-Kontext-API/, not the ComfyUI root, and must contain exactly one key with no quotes.
• Upload errors usually mean empty fal credits, a dropped connection, or an old fal-client. pip install --upgrade fal-client is the usual fix.
• The meter runs. Every queue execution is a billed API call, and multi-image requests cost more than the single version. Batch your edits instead of iterating one prompt tweak at a time.
• Anatomy under pressure. Kontext's known weakness is small subjects in frame - full bodies at 1024px artifact, heads and hair go soft. That's the model, not the node, and multiple references make it more noticeable, so keep people large in the frame.

The workflow cost is real, but for multi-reference editing this is the cheapest way to touch Kontext's best tier. If you're serious about character consistency from several images at once, it's the node this pack exists for.