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.
- 🖼️ 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
- 👥 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
- FLUX.1 Kontext [pro]: Fast, iterative editing for production workflows
- FLUX.1 Kontext [max]: Maximum performance with enhanced typography and prompt precision
- ComfyUI (latest version recommended)
- Python 3.7+
- Black Forest Labs API key
- Required Python packages:
requestsPillow (PIL)torchnumpy
- Open ComfyUI Manager
- Search for "Flux Kontext Creator"
- Click Install
- Restart ComfyUI
- Navigate to your ComfyUI custom nodes directory:
cd ComfyUI/custom_nodes/- Clone the repository:
git clone https://github.com/ShmuelRonen/FluxKontextCreator.git- Install dependencies:
cd FluxKontextCreator
pip install -r requirements.txt- Restart ComfyUI
- Download the latest release from GitHub
- Extract to
ComfyUI/custom_nodes/FluxKontextCreator/ - Restart ComfyUI
- Visit Black Forest Labs API
- Sign up for an account
- Get your API key from the dashboard
- You'll receive 200 free credits to start
Step-by-step instructions:
-
Navigate to the node directory:
ComfyUI/custom_nodes/FluxKontextCreator/ -
Create a new file called
config.ini(use any text editor) -
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
-
Replace
your-actual-api-key-herewith your real API key -
Save the file as
config.ini
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
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- Use
api.bfl.ai(the actual API) notapi.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
- Load Image: Use "Load Image" node to import your source image
- Add Flux Kontext Creator: Add the "🎨 Flux Kontext Creator" node to your workflow
- Connect: Connect your image to the
input_imageinput - Configure: Set your editing instruction and parameters
- Execute: Run the workflow and get your edited image
| 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 |
- Load Multiple Images: Use multiple "Load Image" nodes for your source images
- Add Experimental Creator: Add the "🔥 Flux Kontext Creator Experimental" node
- Connect Images: Connect images to
image_1,image_2, etc. - Set Fusion Parameters: Configure combination mode and fusion settings
- Write Fusion Prompt: Use fusion-specific language (see guide below)
- Execute: Get impossible fusions that look completely natural
| 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 |
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.
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"
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"
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"
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"
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"
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"
Multi-Attribute Control: "[feature 1] + [feature 2] + [environment] + [mood] + [style]"
Narrative Fusion: "[story context] showing [relationship] between [fused elements]"
Technical Specifications: "[specific technical requirements] for [fusion result]"
Examples:
- ✅ "blonde curly hair + bright eyes + cozy restaurant + happy expression + professional portrait style"
- ✅ "mother-daughter bond visualized as one person showing both generations"
- ✅ "photorealistic fusion maintaining facial symmetry and natural lighting"
Wrong: "two people sitting in a restaurant"
✅ Right: "the combined person sitting in the restaurant"
Wrong: "mix them together"
✅ Right: "blend the woman's features with the child's smile and eye color"
Wrong: "keep both people separate but combine them"
✅ Right: "merge both people into one unified character"
Wrong: "create a fusion of the woman and child while maintaining their individual characteristics but also blending them into one person with specific features..."
✅ Right: "blend the woman and child into one person with combined features"
Input: Photo of person wearing blue shirt
Prompt: "Change the shirt color to red"
Result: Same person now wearing red shirt
Input 1: Photo of blonde woman
Input 2: Photo of child with dog
Mode: side_by_side + force_fusion=True
Prompt: "the blonde woman holding the dog in a restaurant"
Result: Single person (fusion of both) holding dog in restaurant setting
Input 1: Modern portrait
Input 2: Vintage photo
Mode: overlay + force_fusion=False
Prompt: "apply the vintage aesthetic to the modern portrait"
Result: Modern person with vintage styling and atmosphere
Input: 4 different room elements
Mode: grid_2x2 + force_fusion=True
Prompt: "create a cohesive living room with all these elements"
Result: Unified interior design combining all elements
✅ Good prompts:
"Change the car color to red"
"Add sunglasses to the person"
"Make the background a beach scene"
"Replace 'Hello' with 'Welcome'"
"Turn the cat into a dog"
❌ Avoid:
Empty instructions
Very long complex descriptions
Conflicting instructions
- 0-2: Very strict content filtering
- 3-4: Balanced filtering (recommended)
- 5-6: More permissive for creative work
- Use for: All character/object fusion tasks
- Effect: Activates advanced fusion prompting system
- Prompt style: Direct fusion language
- Result: True blending and merging of elements
- Use for: Scene enhancement, style application
- Effect: Standard Kontext processing
- Prompt style: Traditional editing language
- Result: Scene modification and enhancement
- 2 images: Perfect for character fusion
- 3-4 images: Good for complex scenes
- 5+ images: Use with grid or all_in_one modes
Chain multiple Flux Kontext Creator nodes to build complex edits:
Image → Kontext1 ("Add hat") → Kontext2 ("Change background") → Final Result
For text within images, use quotation marks:
Replace 'Old Text' with 'New Text'
The model excels at maintaining character identity across edits:
"Put the same person in a different outfit"
"Move the character to a beach setting"
- flux-kontext-pro: Balanced speed and quality, ideal for most fusion tasks
- flux-kontext-max: Maximum quality and prompt adherence for critical fusions
Character Fusion: side_by_side + force_fusion=True + direct prompts
Style Transfer: overlay + force_fusion=False + atmospheric prompts
Complex Scenes: grid_2x2 + force_fusion=True + spatial prompts
Batch Processing: all_in_one + force_fusion=False + consistent prompts
- fit_largest: Best for maintaining detail in high-res images
- fit_smallest: Good for consistent sizing across all images
- no_resize: Use when all images are already properly sized
Node not appearing in ComfyUI:
- Restart ComfyUI completely
- Check console for error messages
- Verify all dependencies are installed
API Key errors:
- Verify your API key in
config.ini - Ensure you have sufficient credits
- Check that BASE_URL is
https://api.bfl.ai
Image generation fails:
- Check your prompt isn't empty
- Verify internet connection
- Try lowering safety_tolerance if content is blocked
- Check BFL service status
Fusion not working properly:
- Ensure
force_fusion=Truefor character merging - Use fusion-specific prompt language (see guide above)
- Try
side_by_sidemode for best character fusion results - Check that you're using singular language ("the person" not "two people")
Connection errors:
- Verify API endpoint is correct
- Check firewall/network settings
- Try again after a few minutes
| Error | Solution |
|---|---|
| "X_KEY not found" | Add API key to config.ini |
| "Invalid API key" | Check your API key is correct |
| "Insufficient credits" | Add credits to your BFL account |
| "Request timeout" | Check internet connection, try again |
| "Content Moderated" | Adjust prompt or lower safety_tolerance |
| "Failed to combine images" | Check image formats and try different resize_mode |
| "No valid images provided" | Ensure images are properly connected to inputs |
Input: Dog photo + Woman with child photo
Settings: side_by_side + force_fusion=True
Prompt: "the blond girl alone hold the dog in restaurant"
Result: ✅ Perfect fusion - single person holding dog in restaurant
Why it worked:
- Singular language ("the blond girl") implies fusion
- Clear action ("hold the dog") provides specific interaction
- Environmental context ("in restaurant") sets the scene
- Simple structure without over-complication
To update the node:
cd ComfyUI/custom_nodes/FluxKontextCreator
git pull origin mainOr use ComfyUI Manager's update feature.
Contributions are welcome! Please feel free to submit a Pull Request.
- Fork the repository
- Create your feature branch (
git checkout -b feature/AmazingFeature) - Commit your changes (
git commit -m 'Add some AmazingFeature') - Push to the branch (
git push origin feature/AmazingFeature) - Open a Pull Request
This project is licensed under the MIT License - see the LICENSE file for details.
- Black Forest Labs for the amazing Flux Kontext API
- ComfyUI community for the excellent framework
- All contributors and users who helped develop the fusion techniques
- Special thanks to the community for breakthrough fusion discoveries
- Issues: GitHub Issues
- Discussions: GitHub Discussions
- BFL API Support: BFL Documentation
- Understand combination_mode effects on reference layout
- Know when to use force_fusion=True vs False
- Can write fusion vs enhancement prompts
- Use specific targeting for precise control
- Apply iterative refinement workflow
- Test parameter combinations systematically
- Build personal prompt template library
- Achieve consistent, high-quality fusion results
If this project helps you create impossible fusions and amazing edits, please consider giving it a star on GitHub!
Made with ❤️ and 🔥 for the ComfyUI community
🚀 Ready to create the impossible? Start with simple character fusion and work your way up to master-level techniques!