Full-featured ComfyUI custom-node pack for fal.ai image generation (FLUX Dev / Pro / Schnell / Kontext / Redux / Schnell-Redux) with queue polling, automatic retry, timeout handling, safety toggles and native ComfyUI image I/O.

Features

Text-to-Image: FLUX Dev, FLUX Pro v1.1, FLUX Pro New, FLUX Schnell
Image-to-Image: FLUX Pro Kontext, FLUX Kontext Dev, FLUX Pro Kontext Multi, FLUX Schnell Redux (fal-ai/flux/schnell/redux)
Model Select Drop-down: automatic model-id mapping
Queue Polling: non-blocking requests with configurable timeout & retry
Safety Controls: enable/disable checker + tolerance per request
Context Store: pass request-ids between nodes for Kontext workflows
Native I/O: transparent URL ↔ numpy array conversion (HWC, 0-1)
Config File: optional INI or ENV variable for API key

Installation

Clone or download this repository into ComfyUI's custom_nodes folder:

cd ComfyUI/custom_nodes
git clone https://github.com/Paddel87/ComfyUI_fal_image.git

Install Python dependencies:

pip install -r ComfyUI_fal_image/requirements.txt

Provide your fal.ai key:
- Environment (recommended):
  Windows PowerShell: $env:FAL_KEY="YOUR_KEY"
  Linux/macOS: export FAL_KEY="YOUR_KEY"
- Config file: copy config.example.ini to config.ini and add your key.
Restart ComfyUI – new nodes appear under fal.ai/Image.

Windows Portable / python_embeded

If you use the ComfyUI standalone build, use its bundled interpreter:

# in ComfyUI root
cd python_embeded
python.exe -m pip install -r ../custom_nodes/ComfyUI_fal_image/requirements.txt

Node Overview

| Node | Description | |------|-------------| | FAL Model Select (Image) | Pick model from drop-down; outputs model-id string. | | FAL Text2Image | Prompt + size + seed + safety → IMAGE + URL + context_id. | | FAL Image2Image | Reference image + prompt + strength → edited IMAGE + URL. | | FAL Context Store | Stores/returns a context_id for multi-step Kontext workflows. |

Minimal Workflows

T2I: Model Select → Text2Image → Save Image
I2I: Load Image → Image2Image → Save Image
Kontext: T2I → Context Store → (optional) I2I with same context

Ready-made JSON: workflows/minimal_kontext_img2img.json – import via ComfyUI "Load" button.

Example workflows: example_workflows/

Advanced Settings (Text2Image / Image2Image)

| Socket | Type | Default | Note | |--------|------|---------|------| | timeout_sec | INT | 60 | Queue polling timeout (10-600). | | retries | INT | 2 | Max retry attempts on transient errors. | | safety_mode | ENUM | auto | enabled / disabled / auto (model decides). | | context_id | STRING | optional | Feed previous request-id for Kontext models. | | seed | INT | 0 | 0 = random. | | guidance | FLOAT | 3.5 | Guidance scale (FLUX: 2-5). | | steps | INT | 28 | Inference steps (FLUX Dev: 20-40). | | num_images | INT | 1 | Batch size (1-4). | | width/height | INT | 1024 | Output resolution (64-2048). | | strength | FLOAT | 0.75 | I2I denoise strength. |

Safety Configuration

The node exposes three safety modes: auto, enabled, disabled.

auto (default): lets the fal endpoint decide.
enabled: always requests safety filtering.
disabled: requests no filtering; maximum safety_tolerance is used.

Server-side enforcement: certain endpoints ignore the client flag and always enable filtering. When this happens the node continues generation and reports the effective mode via the safety_applied output field.

Testing / Verification

Verified behaviour:

Context-ID reuse maintains identity across runs
Img2Img low-strength (0.2-0.4) preserves core features
model_id, seed, safety_applied logged for every request

Run: python ComfyUI_fal_image/tests/demo_flux.py (requires FAL_KEY)

Examples

Environment Launch (Windows)

$env:FAL_KEY="fal-..."; python main.py

Python Test (outside ComfyUI)

import os, sys, ComfyUI_fal_image as m
os.environ["FAL_KEY"] = "fal-..."
from ComfyUI_fal_image.fal_client import FalClient
client = FalClient(os.environ["FAL_KEY"])
payload = {"prompt":"cyberpunk cat","image_size":{"width":768,"height":512}}
result, request_id, status = client.run_with_polling("fal-ai/flux/dev", payload, 90, 2)
# request_id can be used as context_id for Kontext workflows
print(result["images"][0]["url"])

Config File (`config.ini`)

[fal]
key = fal-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
timeout_sec = 120
retries = 3

Troubleshooting

"FAL_KEY missing" → set environment variable or create config.ini.
Timeout errors → increase timeout_sec (slow models / large batches).
Queue status ERROR → retry count exhausted; check prompt / safety flags.
ImportError → re-run pip install -r requirements.txt inside ComfyUI's python env.

Links

fal.ai – get your key
ComfyUI
Repository

Happy generating!

ComfyUI_fal_image

Nodes (4)