Skip to content

About

A Replicate AI Plugin for GIMP. Supports Nano Banana, Seedream5 and more.

Resources

Readme
MIT license
Activity

Stars

150 stars

Watchers

0 watching

Forks

9 forks
Report repository
BranchesTags

Repository files navigation

Dream Prompter - GIMP Plugin

Dream Prompter brings powerful AI models from Replicate directly into GIMP for intelligent image generation and editing. Choose from multiple advanced models including Flux 2 Pro, GPT Image 1.5, GPT Image 2, GPT Image 2.5 Sunburst, Grok Imagine Image 2, Imagen 4, Nano Banana, Nano Banana 2, Nano Banana Pro, Qwen Image 2 Pro, Qwen Image Edit 2511, Seedream 5 Pro, and Stable Diffusion 3.5 Large Turbo.

Dream Prompter

Features

  • 🎨 AI Image Generation: Create new images from text descriptions
  • ✨ AI Image Editing: Transform existing images with natural language prompts
  • 🤖 Multiple AI Models: Choose from Flux 2 Pro, GPT Image 1.5, GPT Image 2, GPT Image 2.5 Sunburst, Grok Imagine Image 2, Imagen 4, Nano Banana, Nano Banana 2, Nano Banana Pro, Qwen Image 2 Pro, Qwen Image Edit 2511, Seedream 5 Pro, and Stable Diffusion 3.5 Large Turbo
  • 🖼️ Reference Images: Support for multiple reference images (varies by model)
  • 🔄 Smart Layer Management: Automatically creates properly named layers
  • 🎯 Dual Operation Modes: Seamlessly switch between editing and generation
  • 🌍 Multi-Language Support: Full internationalization with 10+ languages
  • 🔒 Safe File Handling: Validates references, edited images, and selections before upload
  • 🏗️ Native GIMP Integration: Works seamlessly within your GIMP workflow

Installation

Prerequisites

  • GIMP 3.0+
  • Python 3.10+ (bundled with GIMP 3)
  • Replicate API key (paid account required)

Install the required Python library:

pip install replicate

Quick Install

  1. Download the latest release from GitHub Releases

  2. Extract the release

    This will create a folder named dream-prompter-{version} (e.g., dream-prompter-1.7.0)

  3. Move to your GIMP plugins folder with the correct name:

    Rename and move the extracted folder to exactly dream-prompter in your GIMP plugins directory:

    Note: In paths below, replace <version> with your installed GIMP's major.minor version — e.g. 3.0 or 3.2. The plugin itself auto-detects the running GIMP version at runtime.

  • Linux: ~/.config/GIMP/<version>/plug-ins/dream-prompter/ (Snap: ~/snap/gimp/current/GIMP/<version>/plug-ins/dream-prompter/)
  • Windows: %APPDATA%\GIMP\<version>\plug-ins\dream-prompter\
  • macOS: ~/Library/Application Support/GIMP/<version>/plug-ins/dream-prompter/

Example for Linux:

# Extract creates dream-prompter-1.7.0/
unzip dream-prompter-1.7.0.zip
# Move to correct location with correct name
# Replace ~/.config/GIMP with ~/snap/gimp/current/GIMP if you installed GIMP via Snap
mv dream-prompter-1.7.0 ~/.config/GIMP/<version>/plug-ins/dream-prompter

  1. Make executable (Linux/macOS only):

    # Replace ~/.config/GIMP with ~/snap/gimp/current/GIMP if you installed GIMP via Snap
chmod +x ~/.config/GIMP/<version>/plug-ins/dream-prompter/dream-prompter.py

  2. Restart GIMP

Building translations (optional): If you need languages other than English, run python3 scripts/build-translations.py in the plugin directory after installation.

Arch Linux Installation

To install Dream Prompter on Arch Linux, you can install it from the AUR.

yay -S dream-prompter

Advanced Installation

Manual Installation from Source

  1. Find your GIMP plugins directory (paths listed above) If you installed GIMP via Snap, use ~/snap/gimp/current/GIMP as the base directory instead of ~/.config/GIMP.

  2. Create plugin directory:

    # Replace ~/.config/GIMP with ~/snap/gimp/current/GIMP if you installed GIMP via Snap
mkdir -p ~/.config/GIMP/<version>/plug-ins/dream-prompter/

  3. Copy all Python files and the models directory:

    # Replace ~/.config/GIMP with ~/snap/gimp/current/GIMP if you installed GIMP via Snap
cp *.py ~/.config/GIMP/<version>/plug-ins/dream-prompter/
cp -r models ~/.config/GIMP/<version>/plug-ins/dream-prompter/

  4. Build and install translations (Optional):

    python3 scripts/build-translations.py
# Replace ~/.config/GIMP with ~/snap/gimp/current/GIMP if you installed GIMP via Snap
cp -r locale ~/.config/GIMP/<version>/plug-ins/dream-prompter/

  5. Make executable:

    # Replace ~/.config/GIMP with ~/snap/gimp/current/GIMP if you installed GIMP via Snap
chmod +x ~/.config/GIMP/<version>/plug-ins/dream-prompter/dream-prompter.py

Note: Your final directory structure should look like:

~/.config/GIMP/<version>/plug-ins/dream-prompter/
├── dream-prompter.py
├── api.py
├── dialog*.py
├── integrator.py
├── image_validation.py
├── model_settings.py
├── settings.py
├── i18n.py
├── models/
│   ├── __init__.py
│   ├── factory.py
│   ├── flux_pro.py
│   ├── gpt_image.py
│   ├── gpt_image_2.py
│   ├── gpt_image_2_5_sunburst.py
│   ├── grok_imagine_image_2.py
│   ├── imagen.py
│   ├── nano_banana.py
│   ├── nano_banana_2.py
│   ├── nano_banana_pro.py
│   ├── qwen_image.py
│   ├── qwen_image_edit_plus.py
│   ├── seedream.py
│   └── stable_diffusion_large_turbo.py
└── locale/ (optional)
    └── ...

Development Setup

git clone https://github.com/zquestz/dream-prompter.git
cd dream-prompter
pip install replicate
python3 scripts/build-translations.py # optional, defaults to English
# Replace ~/.config/GIMP with ~/snap/gimp/current/GIMP if you installed GIMP via Snap
ln -s $(pwd) ~/.config/GIMP/<version>/plug-ins/dream-prompter

Python Dependencies Note

Important: Use the same Python that GIMP uses. If pip install replicate doesn't work:

# System-wide installation
sudo pip install replicate

# User installation (recommended)
pip install --user replicate

# Ensure Python 3
pip3 install replicate

macOS Instructions

If you get the "replicate not installed" error on macOS:

  1. Locate GIMP's Python by opening the Python Console: Filters → Development → Python-Fu

  2. Run this command in the console:

    import sys; print(sys.executable)

    You should see something like:

    /Applications/GIMP.app/Contents/MacOS/python3

  3. Install replicate using GIMP's Python from Terminal:

    # Change to GIMP's Python directory
cd /Applications/GIMP.app/Contents/MacOS

# Ensure pip is installed
./python3 -m ensurepip

# Install replicate
./python3 -m pip install replicate

Windows Instructions

If you get the "replicate not installed" error on Windows:

  1. Locate GIMP's Python by opening the Python Console: Filters → Development → Python-Fu

  2. Run this command in the console:

    import sys; print(sys.executable)

    You should see something like:

    C:\Users\quest\AppData\Local\Programs\GIMP 3\bin\pythonw.exe

  3. Install replicate using GIMP's Python from Command Prompt or PowerShell:

    # First make sure we can adjust the python installation
cd C:\Users\quest\AppData\Local\Programs\"GIMP 3"\lib\python3.12\
mv EXTERNALLY-MANAGED EXTERNALLY-MANAGED.bak

# Change to GIMP's bin directory
cd C:\Users\quest\AppData\Local\Programs\"GIMP 3"\bin

# Ensure pip is installed
python.exe -m ensurepip

# Install replicate
python.exe -m pip install replicate --only-binary=:all:

Note: You may need to run Command Prompt or PowerShell as Administrator if you encounter permission errors.

Getting Your API Key

  1. Visit Replicate
  2. Generate an API key
  3. Keep your key secure and monitor usage/costs

Available AI Models

The limits below describe plugin support. File-size caps are plugin limits per reference file in MiB (1 MiB = 1,048,576 bytes); they do not apply to GIMP's exported edit image or selection. Editing reference counts exclude the main image, which occupies one input slot. Provider-side limits still apply.

Flux 2 Pro (black-forest-labs/flux-2-pro) - High-quality image generation and editing model:

  • Capabilities: Both generation and editing
  • Reference Images: Up to 8 for generation, 7 additional references for editing
  • File Size: Maximum 10 MiB per reference file
  • Formats: PNG, JPEG, WebP, GIF
  • Special Features: Excellent text rendering, photorealism, character consistency, up to 4MP resolution
  • More Info: Replicate Model Page

GPT Image 1.5 (openai/gpt-image-1.5) - OpenAI's advanced image generation model:

  • Capabilities: Generation only
  • Reference Images: Up to 10 for generation (plugin limit)
  • File Size: Maximum 10 MiB per reference file
  • Formats: PNG, JPEG, WebP
  • Special Features: Transparent backgrounds, quality control, input fidelity options

GPT Image 2 (openai/gpt-image-2) - OpenAI's next generation image generation model:

  • Capabilities: Generation only
  • Reference Images: Up to 10 for generation (plugin limit)
  • File Size: Maximum 10 MiB per reference file
  • Formats: PNG, JPEG, WebP
  • Special Features: Quality control, dense text rendering, world-knowledge reasoning

GPT Image 2.5 Sunburst (openai/gpt-image-2.5-sunburst) - OpenAI's image generation and editing model with precise editing control:

  • Capabilities: Both generation and editing
  • Reference Images: Up to 10 for generation, 9 additional references for editing (plugin limits)
  • File Size: Maximum 10 MiB per reference file
  • Formats: PNG, JPEG, WebP
  • Special Features: Precise editing, automatic high-fidelity references, six quality levels, transparent backgrounds, flexible output sizes
  • More Info: Replicate Model README and API Schema

Grok Imagine Image 2 (xai/grok-imagine-image-2) - xAI's general-purpose image generation and editing model:

  • Capabilities: Both generation and editing
  • Reference Images: Up to 1 for img2img, no additional references for editing
  • File Size: Maximum 10 MiB per reference file
  • Formats: PNG, JPEG, WebP
  • Special Features: 1K/2K resolution, quality control, wide aspect ratio range including phone ratios, handles real-world entities and brands

Imagen 4 (google/imagen-4) - Google's advanced image generation model:

  • Capabilities: Generation only
  • Reference Images: Not supported
  • Output Formats: PNG, JPEG
  • Special Features: Advanced safety filtering, high-quality generation

Nano Banana (google/nano-banana) - Google's Gemini 2.5 Flash Image model for fast, conversational workflows:

  • Capabilities: Both generation and editing
  • Reference Images: Up to 10 for generation, 9 additional references for editing (plugin limits)
  • File Size: Maximum 7 MiB per reference file
  • Formats: PNG, JPEG, WebP
  • Special Features: Character consistency, multi-image fusion, conversational editing, native image understanding

Nano Banana 2 (google/nano-banana-2) - Google's Gemini 3.1 Flash Image model:

  • Capabilities: Both generation and editing
  • Reference Images: Up to 14 for generation, 13 additional references for editing
  • File Size: Maximum 10 MiB per reference file
  • Formats: PNG, JPEG, WebP
  • Special Features: Multiple resolutions (1K/2K/4K), extended aspect ratios (including 1:4, 4:1, 1:8, 8:1), Google Search and Image Search grounding, improved text rendering

Nano Banana Pro (google/nano-banana-pro) - Google's Gemini 3 Pro state of the art model:

  • Capabilities: Both generation and editing
  • Reference Images: Up to 14 for generation, 13 additional references for editing
  • File Size: Maximum 10 MiB per reference file
  • Formats: PNG, JPEG, WebP
  • Special Features: 4K resolution, accurate text rendering, multi-image fusion, real-time Google Search integration

Qwen Image 2 Pro (qwen/qwen-image-2-pro) - Qwen's next-generation image generation and editing model:

  • Capabilities: Both generation and editing
  • Reference Images: Up to 1 for img2img, no additional references for editing
  • File Size: Maximum 10 MiB per reference file
  • Formats: PNG, JPEG, WebP
  • Special Features: Enhanced text rendering, prompt expansion, negative prompts

Qwen Image Edit 2511 (qwen/qwen-image-edit-2511) - Qwen's advanced image editing model:

  • Capabilities: Editing only
  • Reference Images: Up to 9 additional references for editing (plugin limit)
  • File Size: Maximum 10 MiB per reference file
  • Formats: PNG, JPEG, WebP, GIF
  • Special Features: Specialized for image editing and transformation

Seedream 5 Pro (bytedance/seedream-5-pro) - ByteDance's flagship image generation and editing model:

  • Capabilities: Both generation and editing
  • Reference Images: Up to 10 for generation, 9 additional references for editing
  • File Size: Maximum 10 MiB per reference file
  • Formats: PNG, JPEG, WebP
  • Special Features: 1K and 2K resolution, multi-reference composition, character consistency

Stable Diffusion 3.5 Large Turbo (stability-ai/stable-diffusion-3.5-large-turbo) - Stability AI's high-resolution image generation model:

  • Capabilities: Both generation and editing
  • Reference Images: Up to 1 for generation, no additional references for editing
  • File Size: Maximum 10 MiB per reference file
  • Formats: PNG, JPEG, WebP
  • Special Features: High-resolution generation, fast inference, fewer steps required

Cost Considerations

  • Each image generation/edit counts toward your API usage
  • Monitor your usage at Replicate to avoid unexpected charges

Usage

Basic Workflow

  1. Open an image in GIMP (for editing) or create a new document (for generation)
  2. Launch Dream Prompter: Filters → AI → Dream Prompter...
  3. Enter your API key (saved automatically for future use)
  4. Choose your AI model: Select from available models in the dropdown
    • Note: Available models will vary based on whether an image is open (edit-capable models) or not (generation-capable models)
  5. Select mode:
    • Edit Mode: Transform the current layer (requires edit-capable model and open image)
    • Generate Mode: Create a new image (requires generation-capable model)
  6. Write your prompt: Be descriptive and specific
  7. Add reference images (optional): Click "Select Images..." to add references
  8. Generate: Click the generate button and watch the progress
  9. Result: New layer appears with a descriptive name

Example Prompts

For Generation:

  • "A majestic dragon flying over snow-capped mountains at sunset"
  • "Portrait of a woman in Victorian dress, oil painting style"
  • "Cyberpunk cityscape with neon reflections on wet streets"

For Editing:

  • "Change the background to a peaceful forest clearing"
  • "Make this person wear a red Victorian dress"
  • "Transform this into a watercolor painting style"
  • "Add falling snow to this winter scene"

Tips for Best Results

  • Be specific: "Red sports car" vs "bright red Ferrari 488 GTB"
  • Include style: "photorealistic", "oil painting", "digital art"
  • Describe lighting: "golden hour", "dramatic shadows", "soft natural light"
  • Use reference images to guide style and composition
  • Observe the selected model's reference-file cap: 7 MiB for Nano Banana, 10 MiB for other models that accept images

Input Validation

Before uploading, the plugin checks the operation, reference count, file readability, nonempty content, reference-file size, and supported MIME type. PNG, JPEG, WebP, and GIF are identified by file signatures, not filenames. Files with missing or misleading extensions are accepted when their detected format is supported; use the file chooser's All Files filter when needed.

Requests that fail these checks stop before uploading; references are never silently skipped or truncated. Switching models or modes preserves selected files until you remove them. A batch that exceeds the reference limit is rejected in full, with the remaining capacity shown.

Selection edits check the exported PNG of the selection's bounding rectangle, not the full canvas. Main-image exports are checked for nonempty content and supported MIME type, without applying reference-file size caps.

The plugin does not decode input images, inspect their dimensions, or resize, recompress, or convert uploads. Signature detection identifies a format, not whether an image is complete or uncorrupted; image integrity and provider-specific constraints are handled by Replicate. Upload bytes and local files are unchanged. Only the in-memory upload filename's extension is normalized, with explicit MIME mappings so upload metadata does not depend on system defaults. Decoding returned images for import into GIMP is unchanged.

Language Support

Available Languages

Dream Prompter is fully translated and available in:

  • 🇺🇸 English (default)
  • 🇪🇸 Spanish (complete)
  • 🇫🇷 French (complete)
  • 🇵🇹 Portuguese (complete)
  • 🇷🇺 Russian (complete)
  • 🇯🇵 Japanese (complete)
  • 🇮🇳 Hindi (complete)
  • 🇧🇩 Bengali (complete)
  • 🇨🇳 Chinese (Simplified) (complete)
  • 🇹🇼 Chinese (Traditional) (complete)
  • 🇰🇷 Korean (complete)

The plugin automatically detects your system language and uses the appropriate translation. If your language isn't available, it defaults to English.

For Developers

# Extract new translatable strings
python3 scripts/update-pot.py

# Update existing translations
python3 scripts/update-translations.py

# Build compiled translations
python3 scripts/build-translations.py

Architecture

The plugin is organized into focused modules with a clean model-driven architecture:

Core Plugin Files

  • dream-prompter.py - Main GIMP plugin entry point
  • dialog.py - Main dialog coordinator
  • dialog_gtk.py - GTK user interface components
  • dialog_events.py - Event handling and user interactions
  • dialog_threads.py - Background processing and threading
  • api.py - Replicate API integration
  • integrator.py - GIMP-specific operations
  • image_validation.py - Shared request and image-upload validation
  • model_settings.py - Model parameter management utilities
  • settings.py - Configuration persistence
  • i18n.py - Internationalization support

Model System

  • models/__init__.py - Base model classes and registry system
  • models/factory.py - Model factory for centralized model management
  • models/flux_pro.py - Flux 2 Pro model implementation
  • models/gpt_image.py - GPT Image 1.5 model implementation
  • models/gpt_image_2.py - GPT Image 2 model implementation
  • models/gpt_image_2_5_sunburst.py - GPT Image 2.5 Sunburst generation and editing implementation
  • models/grok_imagine_image_2.py - Grok Imagine Image 2 model implementation
  • models/imagen.py - Imagen 4 model implementation
  • models/nano_banana.py - Nano Banana model implementation
  • models/nano_banana_2.py - Nano Banana 2 model implementation
  • models/nano_banana_pro.py - Nano Banana Pro model implementation
  • models/qwen_image.py - Qwen Image 2 Pro model implementation
  • models/qwen_image_edit_plus.py - Qwen Image Edit 2511 model implementation
  • models/seedream.py - Seedream 5 Pro model implementation
  • models/stable_diffusion_large_turbo.py - Stable Diffusion 3.5 Large Turbo model implementation

The model system provides a clean abstraction for AI models, making it easy to:

  • Add new models by implementing the BaseModel interface
  • Validate inputs using model-specific limits and constraints
  • Build API requests with model-specific parameter formats
  • Maintain consistency across the entire plugin

Extending with New Models

To add support for a new Replicate model:

  1. Create a new model file in the models/ directory (e.g., models/my_model.py)
  2. Implement the BaseModel interface:
from . import BaseModel, OutputFormat, register_model

class MyModel(BaseModel):
    @property
    def name(self) -> str:
        return "my-account/my-model"

    @property
    def display_name(self) -> str:
        return "My Custom Model"

    # Implement other required properties...

    def build_generation_input(self, prompt, reference_images=None, **kwargs):
        # Implementation for generating...
        pass

    def build_edit_input(self, prompt, main_image, reference_images=None, **kwargs):
        # Implementation for editing...
        pass

# Register the model
my_model = MyModel()
register_model(my_model)
  1. Import the model in models/factory.py to ensure it's loaded
  2. The model is now available throughout the plugin with automatic validation and UI updates

The nano_banana.py file serves as a complete reference implementation.

Declare max_file_size_mb as a per-reference-file limit in MiB and max_reference_images_edit as additional references, excluding the main edit image. Declare accepted input MIME types in supported_mime_types; a new format also needs signature detection and an upload extension in image_validation.py. ReplicateAPI checks inputs before calling a model's request builder; it does not decode them or enforce pixel dimensions.

Offline Tests

Run from the repository root using the same Python environment as GIMP, with the plugin's dependencies installed. Replace python3 or python.exe below with GIMP's Python executable path when needed. Input validation tests do not require image codecs.

On Linux/macOS (POSIX shell):

LANGUAGE=en python3 -m unittest discover -s tests -v

On Windows (PowerShell):

$env:LANGUAGE = "en"
python.exe -m unittest discover -s tests -v

These tests cover every registered model, content-based MIME detection, arbitrary filenames, reference-file size and count boundaries, exported edit data, stream cleanup, and reference-selection behavior. Replicate SDK upload metadata and data-URI encoding are exercised with the network boundary mocked. GIMP exports are mocked; no paid predictions run. In-GIMP creation, whole-image editing, and selection editing remain manual smoke tests.

Troubleshooting

Common Issues

"replicate not installed" warning

  • Install with: pip install replicate
  • Ensure you're using GIMP's Python environment

Plugin doesn't appear in menu

  • Check file permissions: chmod +x dream-prompter.py
  • Restart GIMP after installation
  • Verify files are in correct plugins directory

API errors

  • Verify your API key is correct
  • Check your quota at Replicate
  • Monitor costs to avoid unexpected charges

Interface problems

  • Check GIMP's Error Console: Windows → Dockable Dialogs → Error Console
  • Ensure translations are built: python3 scripts/build-translations.py
  • Report UI issues with screenshots

Model or mode not available

  • Edit mode disabled: Some models (like Imagen 4) only support generation - select a different model or use Generate mode
  • Model missing from dropdown: Models are filtered based on context - edit-only models won't appear when no image is open
  • Generate mode disabled: Some models (like Qwen Image Edit 2511) only support editing - open an image first or select a different model

Getting Help

  1. Check the Error Console in GIMP for specific error messages
  2. Verify all requirements are installed correctly
  3. Test with simple prompts first
  4. Check file permissions on the plugin directory
  5. Review API quotas if getting timeout errors

Contributing

For Translators

We welcome translations! Here's how to contribute:

  1. Copy the template: cp locale/dream-prompter.pot locale/[YOUR_LANG].po
  2. Translate the strings using Poedit, Lokalize, or any text editor
  3. Test your translation: Build with python3 scripts/build-translations.py
  4. Submit a pull request with your .po file

Translation Guidelines:

  • Keep UI text concise but clear
  • Use GIMP's existing terminology for your language
  • Preserve HTML tags and placeholders like {count}, {url}
  • Test that text fits in the interface

For Developers

  1. Fork the repository
  2. Create a feature branch
  3. Follow the existing code style
  4. Update translations if adding new strings
  5. Submit a pull request

License

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

Credits

Built with Replicate's API providing access to multiple advanced AI models including Black Forest Labs' Flux 2 Pro, OpenAI's GPT Image 1.5, OpenAI's GPT Image 2, OpenAI's GPT Image 2.5 Sunburst, xAI's Grok Imagine Image 2, Google's Imagen 4, Google's Nano Banana, Google's Nano Banana 2, Google's Nano Banana Pro, Qwen's Image 2 Pro, Qwen's Image Edit 2511, ByteDance's Seedream 5 Pro, and Stability AI's Stable Diffusion 3.5 Large Turbo.

About

A Replicate AI Plugin for GIMP. Supports Nano Banana, Seedream5 and more.

Resources

Readme
MIT license
Activity

Stars

150 stars

Watchers

0 watching

Forks

9 forks
Report repository

Releases

Packages

Contributors

Languages