🎨 Flux Kontext Creator for ComfyUI

A powerful ComfyUI custom node collection for text-based image editing and revolutionary multi image fusion using Black Forest Labs' Flux Kontext API. Transform and fuse your images with simple text instructions while maintaining character consistency and quality.

Multi image fusion process:

Single image regular process:

✨ Features

🎨 Standard Flux Kontext Creator

• 🖼️ Text-Based Image Editing: Modify images using simple text instructions
• 🎭 Character Consistency: Maintain character identity across multiple edits
• ⚡ Fast Processing: 3-5 second generation times
• 🎯 Local Editing: Target specific parts without affecting the rest
• 🎨 Style Transfer: Apply different artistic styles while preserving elements
• 📝 Text Editing: Modify text within images directly
• 🔄 Iterative Editing: Build upon previous edits step-by-step

🔥 NEW: Experimental Fusion Creator

• 👥 Character Fusion: Merge multiple people into one unified character
• 🌟 Multi-Image Combination: Combine up to 10 images with intelligent layouts
• 🎯 Force Fusion Mode: Advanced prompting system for seamless blending
• 📐 Layout Modes: Side-by-side, overlay, grid, and seamless blend options
• 🧠 Smart Preprocessing: Automatic image flattening and resizing
• ⚡ Breakthrough Fusion: Single-input fusion mode for impossible combinations

🚀 Supported Models

• FLUX.1 Kontext [pro]: Fast, iterative editing for production workflows
• FLUX.1 Kontext [max]: Maximum performance with enhanced typography and prompt precision

📋 Requirements

• ComfyUI (latest version recommended)
• Python 3.7+
• Black Forest Labs API key
• Required Python packages:
  • requests
  • Pillow (PIL)
  • torch
  • numpy

🛠️ Installation

Method 1: ComfyUI Manager (Recommended)

1. Open ComfyUI Manager
2. Search for "Flux Kontext Creator"
3. Click Install
4. Restart ComfyUI

Method 2: Git Clone

1. Navigate to your ComfyUI custom nodes directory:

cd ComfyUI/custom_nodes/

2. Clone the repository:

git clone https://github.com/ShmuelRonen/FluxKontextCreator.git

3. Install dependencies:

cd FluxKontextCreator
pip install -r requirements.txt

4. Restart ComfyUI

Method 3: Manual Download

1. Download the latest release from GitHub
2. Extract to ComfyUI/custom_nodes/FluxKontextCreator/
3. Restart ComfyUI

⚙️ Configuration

1. Get Your API Key

1. Visit Black Forest Labs API
2. Sign up for an account
3. Get your API key from the dashboard
4. You'll receive 200 free credits to start

2. Create config.ini File

Step-by-step instructions:

1. Navigate to the node directory:

   ComfyUI/custom_nodes/FluxKontextCreator/
   

2. Create a new file called config.ini (use any text editor)

3. Copy and paste this template:

   [API]
   # Your Black Forest Labs API key
   X_KEY=your-actual-api-key-here
   
   # API endpoint (use api.bfl.ai, not api.bfl.ml)
   BASE_URL=https://api.bfl.ai
   
   [SETTINGS]
   # Default timeout for API requests (seconds)
   TIMEOUT=60
   
   # Default safety tolerance (0-6)
   SAFETY_TOLERANCE=4
   
   # Default output format (png/jpeg)
   OUTPUT_FORMAT=png
   

4. Replace your-actual-api-key-here with your real API key

5. Save the file as config.ini

📁 File Structure Example

After installation, your directory should look like this:

ComfyUI/
└── custom_nodes/
    └── FluxKontextCreator/
        ├── __init__.py
        ├── flux_kontext_creator.py
        ├── flux_kontext_creator_exp.py    ← NEW FUSION NODE
        ├── config.ini                     ← YOU CREATE THIS
        └── README.md

🔑 Real config.ini Example

If your API key is bfl_12345abcdef, your config.ini should look like:

[API]
X_KEY=bfl_12345abcdef
BASE_URL=https://api.bfl.ai

[SETTINGS]
TIMEOUT=60
SAFETY_TOLERANCE=4
OUTPUT_FORMAT=png

⚠️ Important Notes

• Use api.bfl.ai (the actual API) not api.bfl.ml (the documentation site)
• No quotes around the API key
• No spaces around the = sign
• The file must be named exactly config.ini
• Keep your API key private - don't share it publicly

🎯 Usage

🎨 Standard Flux Kontext Creator

Basic Workflow

1. Load Image: Use "Load Image" node to import your source image
2. Add Flux Kontext Creator: Add the "🎨 Flux Kontext Creator" node to your workflow
3. Connect: Connect your image to the input_image input
4. Configure: Set your editing instruction and parameters
5. Execute: Run the workflow and get your edited image

Standard Node Parameters

| Parameter | Description | Default | |-----------|-------------|---------| | input_image | Source image to edit | Required | | edit_instruction | Text description of desired changes | "Change the car color to red" | | model | Choose pro or max model | flux-kontext-pro | | aspect_ratio | Output image ratio | 1:1 | | output_format | Image format (png/jpeg) | png | | safety_tolerance | Content filtering level (0-6) | 4 | | seed | Random seed (-1 for random) | -1 | | keep_original_on_fail | Return original if editing fails | True |

🔥 Experimental Fusion Creator

Revolutionary Fusion Workflow

1. Load Multiple Images: Use multiple "Load Image" nodes for your source images
2. Add Experimental Creator: Add the "🔥 Flux Kontext Creator Experimental" node
3. Connect Images: Connect images to image_1, image_2, etc.
4. Set Fusion Parameters: Configure combination mode and fusion settings
5. Write Fusion Prompt: Use fusion-specific language (see guide below)
6. Execute: Get impossible fusions that look completely natural

Experimental Node Parameters

| Parameter | Description | Default | Options | |-----------|-------------|---------|---------| | prompt | Fusion instruction text | "Merge these two people..." | Multiline text | | number_of_images | How many images to process | 2 | 1-10 | | combination_mode | How to layout images | side_by_side | side_by_side, overlay, grid_2x2, all_in_one, no_combine | | force_fusion | Enable advanced fusion mode | True | True/False | | flatten_images | Handle RGBA→RGB conversion | True | True/False | | resize_mode | Image resizing strategy | fit_largest | fit_largest, fit_smallest, no_resize | | gap_pixels | Space between combined images | 10 | 0-100 | | model | Kontext model to use | flux-kontext-pro | pro/max | | aspect_ratio | Output image ratio | 1:1 | Various ratios | | seed | Random seed | -1 | -1 to 2147483647 |

🧠 Fusion Mastery Guide

🎯 FUNDAMENTAL PRINCIPLE

Your prompt determines HOW the AI interprets and fuses your images. The combination_mode creates the reference layout, but your prompt language controls the fusion strategy.

🔥 COMBINATION MODE STRATEGIES

side_by_side (BEST FOR CHARACTER FUSION)

When to use: Merging people, faces, or distinct subjects Prompt approach: Direct fusion language

✅ "merge the two people into one person"
✅ "combine their best features into a single character"
✅ "the woman and child as one unified person"

overlay (BEST FOR STYLE/ATMOSPHERE)

When to use: Style transfer, mood blending, artistic effects Prompt approach: Atmospheric and stylistic language

✅ "apply the vintage mood to the modern portrait"
✅ "blend the lighting and atmosphere from both images"
✅ "combine the artistic style with the main subject"

grid_2x2 (BEST FOR MULTI-ELEMENT SCENES)

When to use: Complex scenes with multiple objects/elements Prompt approach: Spatial and compositional language

✅ "arrange all elements in a cohesive interior scene"
✅ "create a unified composition from all four elements"
✅ "blend the room elements with the people naturally"

all_in_one (BATCH PROCESSING)

When to use: Processing multiple variations simultaneously Prompt approach: Consistent transformation language

✅ "apply the same artistic style to all subjects"
✅ "transform each person with the same lighting effect"
✅ "create consistent character variations"

📝 PROMPT FRAMEWORKS

LEVEL 1: BASIC FUSION PROMPTS

Subject Fusion: "[Person A] combined with [Person B] as [desired outcome]"
Object Integration: "merge [object] with [object] into [result]"
Style Transfer: "[subject] in the style of [reference style]"

Examples:

• ✅ "the blonde woman holding the small dog in a restaurant"
• ✅ "combine the child's innocence with the woman's elegance"
• ✅ "merge the two hairstyles into one unique look"

LEVEL 2: ADVANCED FUSION PROMPTS

Characteristic Fusion: "blend [specific features] from both subjects"
Environmental Integration: "[subject] naturally placed in [environment] with [lighting/mood]"
Temporal Fusion: "[age/time reference] version of [combined subjects]"

Examples:

• ✅ "blend the woman's facial features with the child's eye color and smile"
• ✅ "the combined person sitting naturally in the restaurant with warm lighting"
• ✅ "teenage version combining both their facial structures"

LEVEL 3: EXPERT FUSION PROMPTS

Multi-Attribute Control: "[feature 1] + [feature 2] + [environment] + [mood] + [style]"
Narrative Fusion: "[story context] showing [relationship] between [fuse