Flux 3 Image (API)

Flux 3 Image (API) is not a sampler. It loads no checkpoint, touches no VRAM, and doesn't care what GPU you have. It sends your prompt to Black Forest Labs' flux-3-image endpoint, waits, then drops the returned picture back into the graph as a normal IMAGE, ready for your masking, upscaler or save node. The name is the honest part: it really does call an API, and it really does need a key.

Why you'd reach for it

FLUX 3 is BFL's July 2026 multimodal turn - one model over image, video, audio and robot action, shipped gated. Video came first as early-access API; the open-weight FLUX 3 Dev backbone is still "coming soon". That's the bit that matters: there are no FLUX 3 weights to download, so calling the model is the only door, the same spot Nano Banana puts you in. You're not picking an API because you're lazy; there's no local to pick.

The flip side is the standard API-node tax: per-call cost, and everything you send goes to a server you don't control, subject to a BFL filter you can't route around.

How it works

The node builds a JSON payload from the widgets plus any reference images, POSTs it to https://api.bfl.ai/v1/flux-3-image, gets back a task with a polling_url, and polls until the status reads Ready. Then it downloads the signed result URL and turns the bytes into an image tensor.

There's no mode field: text-to-image, edit, restyle and combine are one call, so what you get depends on whether images is connected and how you phrase the prompt. generate is async too, so several Flux nodes in one graph run at once instead of queueing. Requests retry with backoff, and the download retries 4× since the delivery URL is signed and expires.

The inputs that matter

prompt - free-form, multiline, and it doubles as the mode switch. Editing? Describe the relationship: "Turn Image 1 in the style of Image 2". Layouts? Name elements as <id> and end with a JSON row list, bbox = [top, left, bottom, right] on a 0–1000 scale. Empty prompts throw.

images - the optional reference batch: 1–10 images of 256×256 to 16 MP, addressed in the prompt as Image 1… or <ref_image_0>. More than ten and the node warns and forwards the first ten.

aspect_ratio - auto means the aspect ratio of your first reference image, or 1:1 with none connected; otherwise a 16-value pick from 21:9 down to 9:21. resolution is 768sq, 1k (default), 2k or 4k - 4k can take several minutes, and the exact pixel count lands in metadata as output_mp.

grounding - on by default, and it makes the model web- and image-search your prompt first. Great for "that specific building" prompts; switch it off when you want repeatable output instead of researched output.

safety_tolerance - 0 to 4, default 2. 0 is the strictest, which catches people out; input and output are moderated.

seed - the trap: the API has no seed, so this is never sent. It only forces the node to re-run.

timeout_minutes defaults to 45 (max 240), since ComfyUI has no execution timeout of its own. If it expires, only the node aborts - the job keeps running at BFL and still costs credits, which is why the error prints the polling_url. api_key is optional; empty means BFL_API_KEY from the pack's .env, then the environment.

Outputs are image and metadata - the latter a STRING dump with the endpoint, task id, polling URL, cost and output_mp. Wire it to Show Any; it's the only place a run's price is visible.

Install

ComfyUI Manager: search the pack title Flux 3 API (registry id flux-3-api). Or manually:

cd ComfyUI/custom_nodes
git clone https://github.com/DenRakEiw/flux_3_api

Restart, copy the shipped .env.example to .env beside the nodes, and add BFL_API_KEY=bfl_.... No model downloads, and requirements.txt is one line: requests>=2.28. torch is deliberately left out so ComfyUI Manager can't reinstall it and break your CUDA build.

Troubleshooting

"No BFL API key found" - lookup order is the node's api_key field → .env → environment variable, and the .env must sit in the pack folder itself. On a 401/403 the node fingerprints the key it used, so you can tell two keys apart without printing either.

A long run that looks hung isn't. Status logs every minute, and the poll interval stretches from 2s toward 10s as the wait grows. Drop the resolution before you assume it's stuck.

The API rejected your images. Reference images are base64-encoded into the request body, so a batch of big ones gets bulky fast; the pack logs a hint on a 400/413 over 5 MB. Downscale before feeding in ten full-res photos.

Read the source before you paste a key. An API-wrapper node holds a credential and calls the network by design - the shape of the thing that got weaponized once already in this ecosystem. This image node is about eighty lines. Skim it.