ComfyUI Extension: ComfyUI-Kontext-API
A custom ComfyUI node for integrating with the Fal Kontext API for advanced image editing and generation.
Custom Nodes (0)
README
ComfyUI-Kontext-API
A custom ComfyUI node for integrating with the Fal Kontext API for advanced image editing and generation.
SINGLE IMAGE NODE
MULTI-IMAGE NODE
Features
- Image-to-Image Generation: Transform images based on text prompts using Fal's Kontext model
- Single Image Output: Generates one image per request for optimal ComfyUI compatibility
- Seed Control: Use specific seeds for reproducible results or -1 for random
- Prompt Enhancement: Optional AI prompt enhancement (can be disabled)
- Multi-Image Support: Process multiple images (1 required, up to 3 optional) with the Kontext Max model
- Automatic Image Resizing: Large images are automatically resized to fit under 1.25MP
- Fal Storage Integration: Images are automatically uploaded to Fal's storage service to avoid API size limits
Installation
- Clone this repository into your ComfyUI custom nodes directory:
cd ComfyUI/custom_nodes
git clone https://github.com/SanDiegoDude/ComfyUI-Kontext-API.git
- Install required dependencies:
cd ComfyUI-Kontext-API
pip install -r requirements.txt
- Set up your Fal API key (REQUIRED):
Getting a Fal API Key
- Sign up at https://fal.ai/
- Go to your dashboard
- Generate an API key
Setting up the API Key
Choose one of these methods:
Option 1: Create a .fal_key file (Recommended)
- Create a file named
.fal_key
in theComfyUI-Kontext-API
directory - Put your Fal API key in this file (just the key, nothing else)
- The file should contain only your API key, for example:
fal_1234567890abcdef
- Note: The
.fal_key
file is already in.gitignore
for security
Option 2: Set environment variable
export FAL_KEY="your_fal_api_key_here"
Usage
- Find either node in the
image/generation
category:- Fal Kontext API: For single image processing
- Fal Kontext Max (Multi-Image): For processing multiple images
- Connect your input image(s):
- Single node: Connect one image to the
image
input - Multi node: Connect 1-4 images to
image1
throughimage4
inputs
- Single node: Connect one image to the
- Enter your prompt describing the desired transformation
- Adjust settings as needed
Technical Details
Image Upload System
To avoid API size limits when processing multiple images, this node automatically:
- Resizes images to fit under 1.25MP (1,250,000 pixels)
- Uploads images to Fal's storage service using
fal_client.upload_file()
- Uses the returned URLs instead of base64 data in API calls
- Cleans up temporary files after upload
This approach ensures reliable processing of multiple images without hitting the 4MB payload limit.
Node Inputs
Fal Kontext API (Single Image)
- prompt (STRING): Text description of the desired image transformation
- image (IMAGE): Input image to transform
- seed (INT): Random seed (-1 for random, default: -1)
- disable_prompt_enhancement (BOOLEAN): Disable AI prompt enhancement (default: False)
Fal Kontext Max (Multi-Image)
- prompt (STRING): Text description of the desired image transformation
- image1 (IMAGE): Required input image
- image2 (IMAGE, optional): Additional input image
- image3 (IMAGE, optional): Additional input image
- image4 (IMAGE, optional): Additional input image
- aspect_ratio (COMBO): Output image aspect ratio
- seed (INT): Random seed (0 for random, default: 0)
- guidance_scale (FLOAT): How closely to follow the prompt (default: 3.5)
- output_format (COMBO): Output image format (jpeg/png)
- disable_prompt_enhancement (BOOLEAN): Disable AI prompt enhancement (default: False)
- image_prompt_strength (FLOAT): Strength of image influence (0-1, default: 0.1)
- num_inference_steps (INT): Number of generation steps (default: 30)
- safety_tolerance (COMBO): NSFW filter tolerance (1-6, default: 6)
Node Outputs
Both nodes provide:
- image (IMAGE): Generated image(s) as tensor(s)
- info (STRING): API response information including:
- Request ID
- Seed used for generation
- Safety check status (✓ passed or ⚠️ blocked)
- Any error messages or warnings
- passed_nsfw_filtering (BOOLEAN): True if content passed safety checks, False if blocked
- Designed to work with "save on true" nodes in ComfyUI
- Returns True for safe content that should be saved
- Returns False for blocked content that should be skipped
Example Prompts
- "Change the car color to red"
- "Convert to pencil sketch with natural graphite lines"
- "Transform to oil painting with visible brushstrokes"
- "It's now snowing, everything is covered in snow"
- "Using this style, a bunny, a dog and a cat are having a tea party"
Testing
You can test the upload functionality using the included test script:
cd ComfyUI-Kontext-API
python test_upload.py
This will verify that:
- The API key is properly configured
- Images can be uploaded to Fal storage
- Tensor conversions work correctly
Troubleshooting
Debug Mode
The node includes detailed debug logging to help diagnose issues. To disable debug output once everything is working:
- Open
nodes.py
- Change
DEBUG = True
toDEBUG = False
at the top of the file
Image Handling Errors
The node properly handles ComfyUI's tensor format (B, H, W, C) and converts between PIL images and tensors automatically.
API Key Issues
Ensure your Fal API key is properly set either as an environment variable or in the .fal_key
file.
If you see an error like "FAL API KEY NOT FOUND!", follow these steps:
- Make sure you have created the
.fal_key
file in theComfyUI-Kontext-API
directory (not in ComfyUI root) - Check that the file contains only your API key with no extra spaces or quotes
- Verify the key is valid by testing it on fal.ai
Upload Issues
If you encounter upload errors:
- Ensure you have a stable internet connection
- Check that your Fal API key has sufficient credits
- Verify the fal-client package is up to date:
pip install --upgrade fal-client
Dependencies
Make sure you have installed all required packages:
pip install fal-client Pillow numpy torch
License
This project is licensed under the MIT License - see the LICENSE file for details.