edit-batch

Batch image processing with FLUX.2 [klein 9B] Q4_K_M GGUF, HiDream-O1-Image, or Boogu-Image-0.1-Edit.

Run the same prompt across many images with dynamic prompting, static and dynamic reference images, support for multiple generations and step count modification along with multiple text encoders and loras. Optionally use HiDream-O1-Image or Boogu-Image-0.1-Edit as the backend model.

Repos, GGUFs, and other dependencies are cached under ~/.cache/flux-batch/.

• Output directory (-o) is created automatically if it doesn't exist.
• The prompt file is reread at each image, so you can modify it mid-batch.
• The ref file (-rf) is also reread on each iteration — changes are detected by content comparison, and images are only reloaded when the file actually changes.

edit-batch -i "*.jpg" -o new/ -p prompt.txt

• The prompt file can contain multiple lines. Each line generates a separate image per input, cycling through prompts sequentially. Lines starting with # are skipped as comments.
• When multiple prompt lines are present, --count is automatically overridden to match the number of lines.

Inline reference images (ref:<path>):

Prompt lines can embed reference image paths directly using ref:<path> syntax. These are extracted, loaded as reference images, and removed from the prompt text before it reaches the model. This composes with -r and -rf — all sources contribute to the reference pool.

# prompt.txt
Make the character wear the outfit ref:/tmp/hat.png ref:/tmp/jacket.png
Put the ball on the table ref:/tmp/ball.png

# No -r needed — refs are embedded in the prompt
edit-batch -i "*.jpg" -o out/ -p prompt.txt

Inline aspect ratio (ratio:<W>:<H>):

Prompt lines can embed an aspect ratio override using ratio:<W>:<H> syntax. This overrides --ratio from the command line for that prompt line.

# prompt.txt
Wide cinematic shot ratio:16:9
Square format ratio:1:1

Inline steps (steps:<int>):

Prompt lines can embed a step count override using steps:<int> syntax. This overrides --steps from the command line for that prompt line.

# prompt.txt
Quick draft steps:4
High quality render steps:20

Here's an example. This is 960 frames.

Look at how frame-matched it is with the original. I even have a nice little peek-a-boo window to compare

https://github.com/user-attachments/assets/08e5e7ea-d49c-4cbd-9391-237583cf7396

A version posted on YouTube: https://youtu.be/8TdXRJQygyY?si=RCVXLUbkEInJ_Z0r

I did this for over 5,000 frames in the video, automatically with edit-batch. Here's a few up close!

Text Encoders

By default, edit-batch uses the censored FLUX text encoder. Alternative text encoders can be enabled:

• --exact: Loads dx8152/Flux2-Klein-9B-Consistency LoRA for improved consistency
• --nsfw: Uses ponpoke/flux2-klein-9b-uncensored-text-encoder text encoder for unrestricted content

# Use exact encoder (LoRA)
edit-batch --exact -i "*.jpg" -o out/ -p prompt.txt

# Use uncensored encoder
edit-batch --nsfw -i "*.jpg" -o out/ -p prompt.txt

HiDream-O1-Image Mode

Use --model hidream to run HiDream-O1-Image, a natively unified 8B image generation model. This is text-to-image only (no img2img conditioning) — input image globs provide size reference but aren't used for content.

# Basic text-to-image
edit-batch --model hidream -o out/ -p prompt.txt --width 1024 --height 1024

# Use dev model (28-step distilled variant)
edit-batch --model hidream --model-type dev -o out/ -p prompt.txt

You'll need the HiDream repo dependencies installed (pip install -r /path/to/HiDream-O1-Image/requirements.txt) and transformers>=4.57.1.

HiDream-only flags:

Boogu-Image-0.1-Edit-Turbo GGUF Mode

Use --model boogu to run Boogu-Image-0.1-Edit-Turbo, a 10B unified image editing model with DMD few-step inference.

When no --boogu-path is given, the script automatically:

1. Clones the Boogu-Image repo on first run
2. Downloads the GGUF-quantized transformer (Q4_1, ~6.9 GiB) from HuggingFace
3. Loads the Qwen3VL MLLM in 4-bit via bitsandbytes to save VRAM

The pipeline runs in DMD turbo mode (4 steps, no CFG by default). When the default guidance scales (--text-guidance-scale 5.0 --image-guidance-scale 1.0) are unchanged, the script auto-adjusts both to 1.0 for DMD.

# Basic image editing
edit-batch --model boogu -i "*.jpg" -o out/ -p prompt.txt

# Text-to-image only (no input image)
edit-batch --model boogu -o out/ -p prompt.txt --width 1024 --height 1024

Boogu flags:

Requirements: bitsandbytes (installed automatically) for 4-bit MLLM quantization. ~12 GiB VRAM needed for 1024² generation.

Skeleton ControlNet Mode

Use --skeleton to guide generation with detected human poses or custom skeleton images:

# Auto-detect pose from input images and apply skeleton control
edit-batch --skeleton -in "*.jpg" -out pose_out/ -p prompt.txt

# Pure skeleton lines (no Canny edges)
edit-batch --skeleton --skeleton-mode skeleton -in "*.jpg" -out pose_out/ -p prompt.txt

# Use pre-generated skeleton image (reused for all inputs)
edit-batch --skeleton --skeleton-image pose.png -in "*.jpg" -out out/ -p prompt.txt

# Use globbed skeleton images paired with input images
edit-batch --skeleton --skeleton-image "poses/*.png" -in "*.jpg" -out out/ -p prompt.txt

# Adjust control strength (0.0-1.0)
edit-batch --skeleton --skeleton-strength 0.8 -in "*.jpg" -out out/ -p prompt.txt

Skeleton modes:

• auto (default): Renders skeleton lines, then applies Canny edge detection
• skeleton: Pose skeleton lines only
• edges: Skeleton lines + Canny edges on skeleton
• canny: Canny edge detection on original input image

Required Flags

Optional Flags

| --model-type | full | HiDream variant: full (25 steps) or dev (28 steps) | | --guidance-scale | * | HiDream guidance scale (5.0 full, 0.0 dev) | | --text-guidance-scale | 5.0 | Text guidance scale for Boogu | | --image-guidance-scale | 1.0 | Image guidance scale for Boogu | | --seed | 42 | Random seed for generation |