diffgentor 0.1.1
A unified visual generation data synthesis factory supporting multiple backends (diffusers, xDiT, OpenAI API)
License: Apache-2.0
Requires Python: >=3.10
Keywords: diffusion, image-editing, image-generation, text-to-image

# Diffgentor

A unified visual generation data synthesis tool for batch image generation and editing, designed for GenArena evaluation and beyond.

## Abstract

Diffgentor is an efficient pipeline for batch image generation using various image generation and editing models. It supports multiple backends including diffusers, OpenAI API, Google GenAI (Gemini), and third-party models like Step1X-Edit, BAGEL, and Emu3.5.

Key features:
- **Multiple Backends**: diffusers, xDiT (multi-GPU), OpenAI, Google GenAI, and third-party models
- **Batch Processing**: Efficient batch inference with multi-process/multi-thread support
- **GenArena Integration**: Generate model outputs for GenArena pairwise evaluation
- **Optimization Suite**: VAE slicing/tiling, torch.compile, attention backends, and more

## Quick Start

### Installation

**Option 1: pip install**

```bash
# Core installation (diffusers, OpenAI, Google GenAI backends)
pip install diffgentor

# Install with all optional backends
pip install "diffgentor[all]"
```

> **GPU users**: PyPI's default torch package is CPU-only. To use CUDA-enabled PyTorch, add the PyTorch index:
> ```bash
> pip install diffgentor --extra-index-url https://download.pytorch.org/whl/cu126
> ```

> **flash-attn**: The `flash-attn` optional dependency requires CUDA compilation. It is recommended to install a pre-built wheel manually:
> ```bash
> pip install flash-attn --no-build-isolation
> ```
> Or download a pre-built wheel from the [flash-attention releases](https://github.com/Dao-AILab/flash-attention/releases).

**Option 2: From source (for development)**

```bash
git clone https://github.com/ruihanglix/diffgentor.git
cd diffgentor
pip install -e ".[all]"
```

### Download GenArena Dataset

```bash
hf download rhli/genarena --repo-type dataset --local-dir ./data
```

### Generate Images for MultiRef Subset

Example using FLUX.2 [klein] 4B model:

```bash
diffgentor edit --backend diffusers \
    --model_name black-forest-labs/FLUX.2-klein-4B \
    --input ./data/multiref/ \
    --output_dir ./output/multiref/FLUX2-klein-4B/
```

## Supported Backends

| Backend | Type | Description |
|---------|------|-------------|
| `diffusers` | T2I / Editing | HuggingFace diffusers with auto pipeline detection |
| `xdit` | T2I | Multi-GPU inference with xDiT parallelism |
| `openai` | T2I / Editing | OpenAI API (GPT-Image, DALL-E) |
| `google_genai` | T2I / Editing | Google GenAI (Gemini native image models) |
| `step1x` | Editing | Step1X-Edit model |
| `bagel` | Editing | ByteDance BAGEL model |
| `emu35` | Editing | BAAI Emu3.5 model |
| `dreamomni2` | Editing | DreamOmni2 (FLUX.1-Kontext + Qwen2.5-VL) |
| `flux_kontext_official` | Editing | BFL official Flux Kontext |
| `hunyuan_image_3` | Editing | Tencent HunyuanImage-3.0-Instruct |

## Documentation

| Document | Description |
|----------|-------------|
| [Image Editing Guide](./docs/editing/README.md) | Comprehensive guide for image editing |
| [Text-to-Image Guide](./docs/t2i/README.md) | Text-to-image generation guide |
| [Optimization Guide](./docs/optimization.md) | Memory and speed optimization |
| [Prompt Enhancement](./docs/prompt_enhance.md) | LLM-based prompt enhancement |
| [Environment Variables](./docs/env_vars.md) | Configuration via environment variables |

### Backend-Specific Guides

- [Diffusers Models](./docs/editing/diffusers.md) - Qwen, FLUX, LongCat
- [Step1X-Edit](./docs/editing/step1x.md) - Step1X-Edit v1.0/v1.1
- [BAGEL](./docs/editing/bagel.md) - ByteDance BAGEL
- [Emu3.5](./docs/editing/emu35.md) - BAAI Emu3.5
- [DreamOmni2](./docs/editing/dreamomni2.md) - DreamOmni2
- [Flux Kontext](./docs/editing/flux_kontext.md) - BFL official
- [HunyuanImage-3.0](./docs/editing/hunyuan_image_3.md) - Tencent HunyuanImage
- [OpenAI](./docs/editing/openai.md) - GPT-Image API
- [Google GenAI](./docs/editing/google_genai.md) - Gemini

## Environment Variables

Model-specific parameters are configured via `DG_*` environment variables:

```bash
# Step1X-Edit
DG_STEP1X_VERSION=v1.1
DG_STEP1X_SIZE_LEVEL=512

# BAGEL
DG_BAGEL_CFG_TEXT_SCALE=3.0
DG_BAGEL_CFG_IMG_SCALE=1.5

# API backends
OPENAI_API_KEY=your_key
GEMINI_API_KEY=your_key
```

See [Environment Variables](./docs/env_vars.md) for the complete list.

## Citation

```bibtex
@misc{li2026genarenaachievehumanalignedevaluation,
      title={GenArena: How Can We Achieve Human-Aligned Evaluation for Visual Generation Tasks?},
      author={Ruihang Li and Leigang Qu and Jingxu Zhang and Dongnan Gui and Mengde Xu and Xiaosong Zhang and Han Hu and Wenjie Wang and Jiaqi Wang},
      year={2026},
      eprint={2602.06013},
      archivePrefix={arXiv},
      primaryClass={cs.CV},
      url={https://arxiv.org/abs/2602.06013},
}
```

## License

Apache-2.0