Black Forest Labs Nodes for Griptape

This library provides Griptape Nodes for interacting with Black Forest Labs' FLUX APIs, enabling high-quality image generation and editing capabilities directly within your Griptape workflows.

Features

• FLUX Text-to-Image: Generate images using FLUX Pro, Dev, and Ultra models
• FLUX.1 Kontext Text-to-Image: Generate high-quality images from text prompts with Kontext models
• FLUX.1 Kontext Image Editing: Edit existing images with text instructions, including:
  • Object modifications (colors, shapes, elements)
  • Text editing within images
  • Smart, natural-looking changes
  • Iterative editing with character consistency

Installation

1. Clone this repository into your Griptape Nodes workspace directory:

# Navigate to your workspace directory
# On Mac or Linux you can use the command below to print your workspace directory
cd $(gtn config show | grep workspace_directory | cut -d'"' -f4)
# On Windows, the default workspace directory is a directory named GriptapeNodes in your home directory.
# Usually this is C:\Users\<username>\GriptapeNodes

# Clone the repository
git clone https://github.com/griptape-ai/griptape-nodes-library-blackforestlabs.git

2. Install dependencies:

cd griptape-nodes-library-blackforestlabs
uv sync

API Key Setup

You'll need a Black Forest Labs API key to use these nodes.

Get Your API Key

1. Visit Black Forest Labs Documentation
2. Create an account and navigate to your API settings
3. Generate a new API key

Configure Your API Key

Configure your API key through the Griptape Nodes IDE:

1. Open the Settings menu.
2. Navigate to the API Keys & Secrets panel.
3. Add a new secret configuration for the service named BlackForest Labs.
4. Enter your BFL_API_KEY in the respective field.

Add your library to your installed Engine!

If you haven't already installed your Griptape Nodes engine, follow the installation steps HERE. After you've completed those and you have your engine up and running:

1. Copy the path to your griptape_nodes_library.json file within the griptape_nodes_library_blackforestlabs directory. Right click on the file, and Copy Path (Not Copy Relative Path).
2. Start up the engine!
3. Navigate to settings.
4. Open your settings and go to the App Events tab. Add an item in Libraries to Register.
5. Paste your copied griptape_nodes_library.json path from earlier into the new item.
6. Exit out of Settings. It will save automatically!
7. Open up the Libraries dropdown on the left sidebar.
8. Your newly registered library should appear! Drag and drop nodes to use them!

Available Nodes

FLUX Text-to-Image

Generate high-quality images using general FLUX models with advanced control options:

• Model: Choose from:
  • flux-pro-1.1-ultra (highest quality)
  • flux-pro-1.1 (balanced, default)
  • flux-pro (standard)
  • flux-dev (open-source)
• Prompt: Text description of the desired image
• Aspect Ratio: Wide range from 21:9 to 9:21 (ultra-wide to tall formats)
• Seed: For reproducible generation
• Raw Mode: Generate less processed, more natural-looking images
• Safety Tolerance: Content moderation level (1-6)
• Output Format: JPEG or PNG

FLUX.1 Kontext Text-to-Image

Generate images from text descriptions using specialized Kontext models:

• Model: Choose between:
  • flux-kontext-pro (faster generation, default)
  • flux-kontext-max (higher quality)
• Prompt: Text description of the desired image
• Aspect Ratio: Choose from 3:7 to 7:3 ratios (supports portrait, landscape, square)
• Seed: For reproducible generation
• Prompt Upsampling: Enhanced prompt processing
• Safety Tolerance: Content moderation level (0-2)
• Output Format: JPEG or PNG

FLUX.1 Kontext Image Edit

Modify existing images using text instructions with Kontext models:

• Model: Choose between flux-kontext-pro or flux-kontext-max
• Input Image: Accepts both ImageArtifact and ImageUrlArtifact
• Prompt: Edit instructions (use quotes for text replacement: Replace '[old text]' with '[new text]')
• Aspect Ratio: Choose from 3:7 to 7:3 ratios
• Seed: For reproducible edits
• Prompt Upsampling: Enhanced prompt processing
• Safety Tolerance: Content moderation level (0-6, wider range than text-to-image)
• Output Format: JPEG or PNG

Model Comparison

When to Use FLUX vs Kontext

Use FLUX Text-to-Image for:

• Traditional text-to-image generation
• Ultra-high quality with FLUX Pro Ultra
• Open-source workflows with FLUX Dev
• Wide aspect ratios (21:9 to 9:21)
• Raw, natural-looking images

Use FLUX.1 Kontext for:

• Advanced image editing workflows
• Iterative editing with consistency
• Text replacement in images
• Character preservation across edits

Example Workflows

Basic Image Generation

1. Add a FLUX Text-to-Image node
2. Choose your model (flux-pro-1.1 for balanced quality/speed)
3. Set your prompt: "A small furry elephant pet looks out from a cat house"
4. Choose your aspect ratio (default: 1:1)
5. Run the workflow
6. The generated image will be available as an ImageArtifact output

High-Quality Generation

1. Use FLUX Text-to-Image with flux-pro-1.1-ultra model
2. Enable Raw Mode for natural-looking results
3. Use wide aspect ratios for cinematic shots

Image Editing Pipeline

1. Generate Base Image: Use FLUX.1 Kontext Text-to-Image to create your starting image
2. Edit the Image: Connect the output to FLUX.1 Kontext Image Edit node
3. Add Edit Instructions:
   • Object changes: "Change the car color to red"
   • Text replacement: Replace 'Hello' with 'Welcome'
   • Style changes: "Make it look like a painting"

Text Editing in Images

For precise text editing, use the quote syntax with Kontext Image Edit:

Replace 'Choose joy' with 'FLUX Rocks'

This works particularly well for:

• Signs and posters
• Labels and captions
• Brand text replacement

Advanced Features

Iterative Editing

FLUX.1 Kontext excels at maintaining consistency across multiple edits. You can chain multiple Image Edit nodes to make progressive changes while preserving character and scene consistency.

Reproducible Results

Use the seed parameter to generate consistent results:

• Same prompt + same seed = same image
• Useful for A/B testing different prompts
• Essential for collaborative workflows

Safety Controls

All nodes include safety tolerance settings:

• FLUX Text-to-Image: 1-6 (2 = default)
• FLUX.1 Kontext Text-to-Image: 0-2 (2 = least restrictive)
• FLUX.1 Kontext Image Edit: 0-6 (6 = least restrictive)

Higher values allow more creative freedom but may generate content that requires review.

API Documentation

For detailed API information and advanced usage:

• Black Forest Labs API Documentation
• FLUX.1 Kontext Text-to-Image Documentation
• FLUX.1 Kontext Image Editing Documentation
• Black Forest Labs API Reference

Troubleshooting

Common Issues

"API key not found"

• Ensure your BFL_API_KEY is configured in the Griptape Nodes IDE Settings → API Keys & Secrets
• Check the API key is valid and active

"404 Not Found"

• Verify you're using the latest version of the library
• Check your internet connection

"Generation failed with status 'Pending'"

• This should resolve automatically - the node polls until completion
• Large images or complex edits may take longer

Image connection errors

• Image Edit node accepts both ImageArtifact and ImageUrlArtifact
• Ensure the input image is properly connected

Getting Help

If you encounter issues:

1. Check the Black Forest Labs Documentation
2. Verify your API key and account status
3. Review the node's status output for detailed error messages

License

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.