Skip to content

zquestz/dream-prompter

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, Imagen 4, Nano Banana, Nano Banana Pro, Qwen Image, Qwen Image Edit Plus, Seedream 4.5, 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, Imagen 4, Nano Banana, Nano Banana Pro, Qwen Image, Qwen Image Edit Plus, Seedream 4.5, 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 image formats and file sizes per model
  • 🏗️ Native GIMP Integration: Works seamlessly within your GIMP workflow

Installation

Prerequisites

  • GIMP 3.0+
  • Python 3.8+
  • 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.4.1)

  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.4.1/
unzip dream-prompter-1.4.1.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.4.1 ~/.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
├── settings.py
├── i18n.py
├── models/
│   ├── __init__.py
│   ├── factory.py
│   ├── flux_pro.py
│   ├── gpt_image.py
│   ├── gpt_image_2.py
│   ├── imagen.py
│   ├── nano_banana.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

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 for editing
  • File Size: Maximum 10MB per image
  • 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
  • File Size: Maximum 10MB per image
  • 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
  • File Size: Maximum 10MB per image
  • Formats: PNG, JPEG, WebP
  • Special Features: Quality control, dense text rendering, world-knowledge reasoning

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

  • Capabilities: Generation only
  • Reference Images: Not supported
  • File Size: Maximum 7MB per image
  • 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 for editing
  • File Size: Maximum 7MB per image
  • 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 for editing
  • File Size: Maximum 10MB per image
  • 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 for editing
  • File Size: Maximum 10MB per image
  • Formats: PNG, JPEG, WebP
  • Special Features: 4K resolution, accurate text rendering, multi-image fusion, real-time Google Search integration

Qwen Image (qwen/qwen-image) - Qwen's advanced image generation model:

  • Capabilities: Generation only
  • Reference Images: Up to 1 for img2img
  • File Size: Maximum 10MB per image
  • Formats: PNG, JPEG, WebP
  • Special Features: Guidance control, prompt enhancement, LoRA support

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

  • Capabilities: Editing only
  • Reference Images: Up to 9 for editing
  • File Size: Maximum 10MB per image
  • Formats: PNG, JPEG, WebP, GIF
  • Special Features: Specialized for image editing and transformation

Seedream 4.5 (bytedance/seedream-4.5) - ByteDance's upgraded image model with stronger spatial understanding:

  • Capabilities: Both generation and editing
  • Reference Images: Up to 14 for generation, 13 for editing
  • File Size: Maximum 10MB per image
  • Formats: PNG, JPEG, WebP
  • Special Features: 4K resolution support, enhanced prompt option, improved spatial understanding and world knowledge

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, none for editing
  • File Size: Maximum 10MB per image
  • 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
  • Keep files under 7MB for reference images

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_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
  • 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/imagen.py - Imagen 4 model implementation
  • models/nano_banana.py - Nano Banana model implementation
  • models/nano_banana_pro.py - Nano Banana Pro model implementation
  • models/qwen_image.py - Qwen Image model implementation
  • models/qwen_image_edit_plus.py - Qwen Image Edit Plus model implementation
  • models/seedream.py - Seedream 4.5 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.

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 Plus) 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, Google's Imagen 4, Google's Nano Banana, Google's Nano Banana Pro, Qwen's Image, Qwen's Image Edit Plus, ByteDance's Seedream 4.5, and Stability AI's Stable Diffusion 3.5 Large Turbo.

About

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

Resources

Readme

License

MIT license
Activity

Stars

133 stars

Watchers

0 watching

Forks

7 forks
Report repository

Releases 14

1.4.1 Latest
Apr 22, 2026
+ 13 releases

Packages

 
 
 

Contributors

Languages