Hugging Face's logo

microsoft
/
Mage-Flow

Text-to-Image
Diffusers
Safetensors
MageFlowPipeline
image-generation
image-editing
diffusion
rectified-flow
mage-flow
Model card Files
xet
 Community
3
Xinjie-Q commited on
Commit
2a94cad
·
verified ·
1 Parent(s): 4a05281

add README

Browse files
Files changed (1) hide show
  1. README.md +379 -0
README.md CHANGED
@@ -1,3 +1,382 @@
1
  ---
2
  license: mit
 
 
 
 
 
 
 
 
 
3
  ---
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
  ---
2
  license: mit
3
+ library_name: diffusers
4
+ pipeline_tag: text-to-image
5
+ tags:
6
+ - text-to-image
7
+ - image-generation
8
+ - image-editing
9
+ - diffusion
10
+ - rectified-flow
11
+ - mage-flow
12
  ---
13
+
14
+ <h1 align="center">Mage-Flow<br><span style="font-size: 0.55em; font-weight: normal;">An Efficient Native-Resolution Foundation Model for Image Generation and Editing</span></h1>
15
+
16
+ <p align="center">
17
+ <a href="https://arxiv.org/abs/2601.XXXXX"><img alt="arXiv" src="https://img.shields.io/badge/arXiv-Mage--Flow-b31b1b" height="22" /></a>
18
+ <a href="https://microsoft.github.io/Mage"><img alt="Project Page" src="https://img.shields.io/badge/%F0%9F%8C%90-Project%20Page-blue" height="22" /></a>
19
+ <a href="https://github.com/microsoft/Mage"><img src="https://img.shields.io/badge/Code-GitHub-181717?logo=github" alt="GitHub"></a>
20
+ <a href="https://huggingface.co/microsoft/Mage-Flow-Base"><img alt="Hugging Face" src="https://img.shields.io/badge/%F0%9F%A4%97-Mage--Flow--Base-yellow" height="22" /></a>
21
+ <a href="https://huggingface.co/microsoft/Mage-Flow"><img alt="Hugging Face" src="https://img.shields.io/badge/%F0%9F%A4%97-Mage--Flow-yellow" height="22" /></a>
22
+ <a href="https://huggingface.co/microsoft/Mage-Flow-Turbo"><img alt="Hugging Face" src="https://img.shields.io/badge/%F0%9F%A4%97-Mage--Flow--Turbo-yellow" height="22" /></a>
23
+ <a href="https://huggingface.co/microsoft/Mage-Flow-Edit-Base"><img alt="Hugging Face" src="https://img.shields.io/badge/%F0%9F%A4%97-Mage--Flow--Edit--Base-yellow" height="22" /></a>
24
+ <a href="https://huggingface.co/microsoft/Mage-Flow-Edit"><img alt="Hugging Face" src="https://img.shields.io/badge/%F0%9F%A4%97-Mage--Flow--Edit-yellow" height="22" /></a>
25
+ <a href="https://huggingface.co/microsoft/Mage-Flow-Edit-Turbo"><img alt="Hugging Face" src="https://img.shields.io/badge/%F0%9F%A4%97-Mage--Flow--Edit--Turbo-yellow" height="22" /></a>
26
+ <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/License-MIT-green" alt="License: MIT"></a>
27
+ </p>
28
+
29
+ <!-- <p align="center">
30
+ <a href="https://huggingface.co/microsoft/Mage-Flow-Base"><img alt="Hugging Face" src="https://img.shields.io/badge/%F0%9F%A4%97-Mage--Flow--Base-yellow" height="22" /></a>
31
+ <a href="https://huggingface.co/microsoft/Mage-Flow"><img alt="Hugging Face" src="https://img.shields.io/badge/%F0%9F%A4%97-Mage--Flow-yellow" height="22" /></a>
32
+ <a href="https://huggingface.co/microsoft/Mage-Flow-Turbo"><img alt="Hugging Face" src="https://img.shields.io/badge/%F0%9F%A4%97-Mage--Flow--Turbo-yellow" height="22" /></a>
33
+ <a href="https://huggingface.co/microsoft/Mage-Flow-Edit-Base"><img alt="Hugging Face" src="https://img.shields.io/badge/%F0%9F%A4%97-Mage--Flow--Edit--Base-yellow" height="22" /></a>
34
+ <a href="https://huggingface.co/microsoft/Mage-Flow-Edit"><img alt="Hugging Face" src="https://img.shields.io/badge/%F0%9F%A4%97-Mage--Flow--Edit-yellow" height="22" /></a>
35
+ <a href="https://huggingface.co/microsoft/Mage-Flow-Edit-Turbo"><img alt="Hugging Face" src="https://img.shields.io/badge/%F0%9F%A4%97-Mage--Flow--Edit--Turbo-yellow" height="22" /></a>
36
+ </p> -->
37
+
38
+ <div align="center">
39
+ <img src="assets/mage-flow-cover.png" width="100%" alt="gallery">
40
+ </div>
41
+
42
+ ---
43
+
44
+ **Mage-Flow** is a compact **4B-scale generative stack** for efficient **text-to-image generation** and **instruction-based image editing**. Instead of scaling to tens of billions of parameters, Mage-Flow reaches state-of-the-art-competitive quality through careful **tokenizer–backbone–system co-design**, so it stays fast, memory-light, and easy to fine-tune under realistic compute budgets.
45
+
46
+ The stack is built from **two shared, co-designed components**:
47
+
48
+ - **Mage-VAE** — a lightweight, high-fidelity latent tokenizer (one-step diffusion encode/decode with anchor-latent KL regularization).
49
+ - **NR-MMDiT** — a shared 4B **Native-Resolution Multimodal Diffusion Transformer**, trained with rectified flow matching in the Mage-VAE latent space.
50
+
51
+ Together with native-resolution packing and a fused-kernel training infrastructure, this shared stack powers **two model instantiations**: **Mage-Flow** for text-to-image generation and **Mage-Flow-Edit** for instruction-based image editing. Each ships in **Base**, **RL-aligned**, and **4-step Turbo** variants.
52
+
53
+ ## ✨ Highlights
54
+
55
+ - **Compact & competitive.** A single 4B family for generation *and* editing that matches or beats much larger open systems (Qwen-Image 20B, Z-Image 6B, FLUX.2 32B, FireRed-Image-Edit 20B).
56
+ - **Efficient tokenizer.** Mage-VAE matches FLUX.2-VAE reconstruction fidelity while using **~12× / ~22× fewer encode / decode MACs per pixel**, removing the VAE as the high-resolution bottleneck.
57
+ - **Native resolution.** One checkpoint generates from **512 to 2048** on any aspect ratio, including extreme **4:1** (e.g. `512×2048`, `2048×512`).
58
+ - **System-level speed.** Native-resolution packing (FlashAttention var-len + per-sample 2D RoPE) + fused CUDA kernels raise MFU from **~33% → ~77%** (**~2.5× faster training**); CFG's conditional/unconditional branches run in **one** packed forward.
59
+ - **Full family.** **Base**, **RL-aligned**, and **4-step Turbo** variants for both generation and editing.
60
+ - **Versatile editing.** Mage-Flow-Edit supports semantic content editing, appearance transformation, image restoration, and structure-aware outputs within a unified image-and-text-conditioned model. See the report's editing galleries.
61
+ - **Interactive latency.** At `1024²` on a single A100: **Mage-Flow-Turbo 0.59 s/image**, **Mage-Flow-Edit-Turbo 1.02 s/edit**, peak memory **~18–20 GB** (lowest among compared systems).
62
+
63
+ <div align="center">
64
+ <img src="assets/one_to_many_editing_diversity.jpg" width="100%" alt="One-to-many editing diversity"><br>
65
+ <em>One-to-many editing diversity — Mage-Flow-Edit can generate diverse outputs from a single reference image.</em>
66
+ </div>
67
+
68
+ ## 📥 Model Zoo
69
+
70
+ Each checkpoint is a self-contained diffusers-style repo (`transformer/` + shared `vae/`, `text_encoder/`, `scheduler/`).
71
+
72
+ | Model | Task | Variant | Steps | Hugging Face |
73
+ | :-------------------------- | :---------- | :----------------- | :---: | :---------------------------------------------------------------------------------------- |
74
+ | `Mage-Flow-4B-Base` | text→image | Base | 30 | [🤗 microsoft/Mage-Flow-Base](https://huggingface.co/microsoft/Mage-Flow-Base) |
75
+ | `Mage-Flow-4B` | text→image | RL-aligned | 20 | [🤗 microsoft/Mage-Flow](https://huggingface.co/microsoft/Mage-Flow) |
76
+ | `Mage-Flow-4B-Turbo` | text→image | Few-step distilled | 4 | [🤗 microsoft/Mage-Flow-Turbo](https://huggingface.co/microsoft/Mage-Flow-Turbo) |
77
+ | `Mage-Flow-Edit-4B-Base` | editing | Base | 30 | [🤗 microsoft/Mage-Flow-Edit-Base](https://huggingface.co/microsoft/Mage-Flow-Edit-Base) |
78
+ | `Mage-Flow-Edit-4B` | editing | RL-aligned | 30 | [🤗 microsoft/Mage-Flow-Edit](https://huggingface.co/microsoft/Mage-Flow-Edit) |
79
+ | `Mage-Flow-Edit-4B-Turbo` | editing | Few-step distilled | 4 | [🤗 microsoft/Mage-Flow-Edit-Turbo](https://huggingface.co/microsoft/Mage-Flow-Edit-Turbo) |
80
+
81
+ ## 🖼️ Showcase
82
+
83
+ **Text-to-image** — prompt following, fine detail, and legible English/Chinese text rendering. *(The first panel is open; click a title to expand the others.)*
84
+
85
+ <details open>
86
+ <summary><b>Showcase</b></summary>
87
+ <div align="center"><img src="assets/t2i_teaser.jpg" width="100%" alt="t2i teaser"></div>
88
+ </details>
89
+
90
+ <details>
91
+ <summary><b>General scenes</b></summary>
92
+ <div align="center"><img src="assets/general.jpg" width="100%" alt="general scenes"></div>
93
+ </details>
94
+
95
+ <details>
96
+ <summary><b>Portraits</b></summary>
97
+ <div align="center"><img src="assets/portrait.jpg" width="100%" alt="portraits"></div>
98
+ </details>
99
+
100
+ <details>
101
+ <summary><b>Cuisine & still life</b></summary>
102
+ <div align="center"><img src="assets/cuisine.jpg" width="100%" alt="cuisine"></div>
103
+ </details>
104
+
105
+ <details>
106
+ <summary><b>English text rendering</b></summary>
107
+ <div align="center"><img src="assets/text_en.jpg" width="100%" alt="english text"></div>
108
+ </details>
109
+
110
+ <details>
111
+ <summary><b>Chinese text rendering</b></summary>
112
+ <div align="center"><img src="assets/text_zh.jpg" width="100%" alt="chinese text"></div>
113
+ </details>
114
+
115
+ **Instruction-based editing** — appearance, content, scene/subject, human-centered & creative, low-level, and restoration edits (source → result). *(The first panel is open; click a title to expand the others.)*
116
+
117
+ <details open>
118
+ <summary><b>Various Editing I</b></summary>
119
+ <div align="center"><img src="assets/edit_gallery_showcase_1.jpg" width="100%" alt="editing showcase 1"></div>
120
+ </details>
121
+
122
+ <details>
123
+ <summary><b>Various Editing II</b></summary>
124
+ <div align="center"><img src="assets/edit_gallery_showcase_2.jpg" width="100%" alt="editing showcase 2"></div>
125
+ </details>
126
+
127
+ <details>
128
+ <summary><b>Localized content & object editing</b></summary>
129
+ <div align="center"><img src="assets/edit_gallery_content.jpg" width="100%" alt="content editing"></div>
130
+ </details>
131
+
132
+ <details>
133
+ <summary><b>Scene, subject & camera transformations</b></summary>
134
+ <div align="center"><img src="assets/edit_gallery_scene_subject.jpg" width="100%" alt="scene and subject"></div>
135
+ </details>
136
+
137
+ <details>
138
+ <summary><b>Appearance & artistic rendering</b></summary>
139
+ <div align="center"><img src="assets/edit_gallery_appearance.jpg" width="100%" alt="appearance"></div>
140
+ </details>
141
+
142
+ <details>
143
+ <summary><b>Human-centered & creative editing</b></summary>
144
+ <div align="center"><img src="assets/edit_gallery_human_creative.jpg" width="100%" alt="human-centered and creative"></div>
145
+ </details>
146
+
147
+ <details>
148
+ <summary><b>Low-level vision & conditional reconstruction</b></summary>
149
+ <div align="center"><img src="assets/edit_gallery_lowlevel.jpg" width="100%" alt="low-level vision"></div>
150
+ </details>
151
+
152
+ <details>
153
+ <summary><b>Bidirectional degradation & restoration</b></summary>
154
+ <div align="center"><img src="assets/edit_gallery_restoration.jpg" width="100%" alt="restoration"></div>
155
+ </details>
156
+
157
+ ## 📊 Performance
158
+
159
+ <details>
160
+ <summary><b>Full benchmark tables (text-to-image & image editing) — click to expand</b></summary>
161
+
162
+ **Text-to-image** — full benchmark suite: GenEval, DPG-Bench, TIIF-Bench (short/long splits), CVTG-2K, OneIG (EN/CN), LongText (EN/CN). Higher is better; GenEval / CVTG-2K / OneIG / LongText on a 0–1 scale, DPG / TIIF on 0–100. The **Type** column marks closed- vs open-source; **bold** / <ins>underline</ins> = best / second-best among **open-source** models (closed-source shown for reference, not ranked); `–` = not reported; ★ = ours.
163
+
164
+ | Model | Type | #Params | Steps | GenEval | DPG | TIIF-Short | TIIF-Long | CVTG-2K | OneIG-EN | OneIG-CN | LongText-EN | LongText-CN |
165
+ | :--------------------------- | :----: | :-----: | :---: | :-------------: | :--------------: | :--------------: | :--------------: | :--------------: | :--------------: | :--------------: | :--------------: | :--------------: |
166
+ | Seedream 3.0 | Closed | – | – | 0.84 | 88.27 | 86.02 | 84.31 | 0.592 | 0.530 | 0.528 | 0.896 | 0.878 |
167
+ | Seedream 4.0 | Closed | – | – | 0.84 | 88.63 | – | – | 0.892 | 0.573 | 0.554 | 0.936 | 0.946 |
168
+ | GPT-Image-1 | Closed | – | – | 0.84 | 85.15 | 89.15 | 88.29 | 0.857 | 0.533 | 0.474 | 0.956 | 0.619 |
169
+ | Nano-Banana-Pro | Closed | – | – | 0.83 | 87.16 | – | – | 0.779 | 0.580 | 0.570 | 0.981 | 0.949 |
170
+ | FLUX.1-dev | Open | 12B | 50 | 0.66 | 83.84 | 71.09 | 71.78 | 0.496 | 0.434 | 0.245 | 0.607 | 0.005 |
171
+ | FLUX.1-Krea-dev | Open | 12B | 50 | 0.72 | 86.59 | 80.36 | 81.67 | 0.444 | 0.443 | 0.271 | 0.693 | 0.002 |
172
+ | FLUX.2-dev | Open | 32B | 50 | 0.87 | 87.57 | **88.82** | **88.10** | **0.893** | **0.551** | 0.516 | **0.963** | 0.757 |
173
+ | FLUX.2-Klein-Base-4B | Open | 4B | 50 | 0.78 | 83.02 | 79.94 | 80.01 | 0.656 | 0.485 | 0.366 | 0.554 | 0.071 |
174
+ | FLUX.2-Klein-Base-9B | Open | 9B | 50 | 0.83 | 85.29 | 81.47 | 84.52 | 0.655 | 0.544 | 0.400 | 0.872 | 0.227 |
175
+ | FLUX.2-Klein-4B | Open | 4B | 4 | 0.83 | 85.53 | 78.91 | 79.04 | 0.628 | 0.500 | 0.364 | 0.649 | 0.068 |
176
+ | FLUX.2-Klein-9B | Open | 9B | 4 | 0.86 | 86.20 | 85.22 | 84.13 | 0.424 | 0.538 | 0.406 | 0.872 | 0.226 |
177
+ | Qwen-Image | Open | 20B | 50 | 0.87 | **88.32** | <ins>86.14</ins> | <ins>86.83</ins> | 0.829 | 0.539 | **0.548** | 0.943 | 0.946 |
178
+ | JoyAI-Image | Open | 16B | 50 | – | 88.05 | – | – | 0.874 | 0.542 | 0.521 | **0.963** | **0.963** |
179
+ | HunyuanImage-3.0 | Open | 80B | 50 | 0.72 | 86.10 | – | – | 0.765 | – | – | – | – |
180
+ | LongCat-Image | Open | 6B | 50 | 0.87 | 86.80 | 80.93 | 81.30 | 0.866 | 0.516 | 0.518 | 0.885 | <ins>0.956</ins> |
181
+ | Z-Image-Base | Open | 6B | 50 | 0.84 | <ins>88.14</ins> | 80.20 | 83.04 | 0.867 | <ins>0.546</ins> | <ins>0.535</ins> | 0.935 | 0.936 |
182
+ | Z-Image-Turbo | Open | 6B | 8 | 0.82 | 84.86 | 77.73 | 80.05 | 0.859 | 0.528 | 0.507 | 0.917 | 0.926 |
183
+ | **Mage-Flow-Base** ★ | Open | 4B | 30 | 0.79 | 86.26 | 82.50 | 83.19 | 0.851 | 0.542 | 0.509 | 0.904 | 0.792 |
184
+ | **Mage-Flow** ★ | Open | 4B | 20 | **0.90** | 86.49 | 82.19 | 84.70 | <ins>0.887</ins> | 0.536 | 0.505 | <ins>0.944</ins> | 0.823 |
185
+ | **Mage-Flow-Turbo** ★ | Open | 4B | 4 | <ins>0.88</ins> | 85.48 | 83.58 | 84.16 | 0.873 | 0.523 | 0.491 | 0.911 | 0.801 |
186
+
187
+ **Image editing** — ImgEdit-Bench (0–5), GEdit-Bench EN/CN (0–10), TextEdit-Bench synthetic/real (0–25). Higher is better; the **Type** column marks closed- vs open-source; **bold** / <ins>underline</ins> = best / second-best among **open-source** models; `–` = not reported; ★ = ours.
188
+
189
+ | Model | Type | #Params | Steps | ImgEdit | GEdit-EN | GEdit-CN | TextEdit-Syn | TextEdit-Real |
190
+ | :-------------------------------- | :----: | :-----: | :---: | :-------------: | :--------------: | :--------------: | :--------------: | :--------------: |
191
+ | Nano-Banana | Closed | – | – | 4.29 | 7.291 | 7.399 | 16.54 | 18.22 |
192
+ | Seedream 4.0 | Closed | – | – | 4.30 | 7.701 | 7.692 | 14.90 | 18.54 |
193
+ | Seedream 4.5 | Closed | – | – | 4.32 | 7.820 | 7.800 | – | – |
194
+ | Nano-Banana-Pro | Closed | – | – | 4.37 | 7.738 | 7.799 | – | – |
195
+ | Step1X-Edit-v1.2 | Open | 19B | 50 | 3.95 | 7.480 | 7.467 | 9.26 | 12.02 |
196
+ | FLUX.1-Kontext-dev | Open | 12B | 28 | 3.71 | 6.462 | 1.857 | 12.14 | 14.31 |
197
+ | FLUX.2-dev | Open | 32B | 50 | 4.35 | 7.413 | 7.278 | 11.86 | 14.71 |
198
+ | FLUX.2-Klein-Base-4B | Open | 4B | 50 | 3.80 | 7.081 | 7.102 | 11.01 | 13.79 |
199
+ | FLUX.2-Klein-4B | Open | 4B | 4 | 4.01 | 7.717 | 7.750 | 11.84 | 14.46 |
200
+ | FLUX.2-Klein-Base-9B | Open | 9B | 50 | 4.05 | 7.740 | 7.745 | 12.76 | 15.65 |
201
+ | FLUX.2-Klein-9B | Open | 9B | 4 | 4.18 | 8.040 | 8.055 | 12.73 | 15.75 |
202
+ | Z-Image-Edit | Open | 6B | 50 | 4.30 | 7.570 | 7.540 | – | – |
203
+ | Qwen-Image-Edit-2509 | Open | 20B | 50 | 4.31 | 7.480 | 7.467 | 13.40 | 15.81 |
204
+ | Qwen-Image-Edit-2511 | Open | 20B | 50 | <ins>4.51</ins> | 7.877 | 7.819 | 13.53 | <ins>16.81</ins> |
205
+ | LongCat-Image-Edit | Open | 6B | 50 | 4.45 | 7.748 | 7.731 | 12.46 | 14.89 |
206
+ | FireRed-Image-Edit-1.0 | Open | 20B | 50 | **4.56** | 7.943 | 7.887 | **15.19** | **17.23** |
207
+ | JoyAI-Image-Edit | Open | 16B | 50 | 4.46 | **8.276** | <ins>8.125</ins> | <ins>14.80</ins> | **17.23** |
208
+ | **Mage-Flow-Edit-Base** ★ | Open | 4B | 30 | 4.28 | 7.860 | 7.970 | 13.63 | 15.57 |
209
+ | **Mage-Flow-Edit** ★ | Open | 4B | 30 | 4.34 | 8.127 | 8.123 | 14.14 | 16.26 |
210
+ | **Mage-Flow-Edit-Turbo** ★ | Open | 4B | 4 | 4.38 | <ins>8.271</ins> | **8.264** | 12.77 | 15.41 |
211
+
212
+ </details>
213
+
214
+ ## 🏗️ Architecture
215
+
216
+ **Mage-VAE** — a latent tokenizer built as a *symmetric* one-step diffusion codec: the decoder is a fully-convolutional one-step pixel-diffusion model (no global-attention blocks), and the encoder is its architectural dual (a one-step latent generator conditioned on pixels). A standard Gaussian-prior KL is replaced with an **anchor-latent KL** that regularizes the posterior toward FLUX.2-VAE latents, giving a generation-ready `128`-channel, `16×`-downsampled latent space.
217
+
218
+ <div align="center">
219
+ <img src="assets/mage_vae.jpg" width="100%" alt="Mage-VAE architecture and training"><br>
220
+ <em>Mage-VAE — anchor VAE (FLUX.2-VAE), the symmetric one-step encoder/decoder architecture, and the three-stage training pipeline.</em>
221
+ </div>
222
+
223
+ **Mage-Flow** — a 4B Multimodal DiT that encodes prompts with **Qwen3-VL** and images with Mage-VAE, then processes **packed** variable-length image+text sequences with per-sample 2D rotary embeddings and joint self-attention. **Native-resolution packing** removes bucket quantization and padding, lets one checkpoint generalize to any output size, and fuses the CFG cond/uncond branches into a single forward.
224
+
225
+ <div align="center">
226
+ <img src="assets/nr_mmdit.jpg" width="100%" alt="Mage-Flow / Native-Resolution MMDiT architecture"><br>
227
+ <em>Mage-Flow — native-resolution packing of variable-length image+text tokens through the Native-Resolution MMDiT (left), and the dual-stream MMDiT block (right).</em>
228
+ </div>
229
+
230
+ **Post-training** — from `Base`, generation is aligned with **Diffusion-NFT** (prompt following, aesthetics, text rendering, preference) to produce the RL model, and distilled with **decoupled-DMD + adversarial perceptual guidance** into the 4-step `Turbo`. Editing models reuse the recipe, trained on a mixture of generation and editing data to keep the generative prior.
231
+
232
+ ## 🚀 Quick Start
233
+
234
+ ### Installation
235
+
236
+ Install everything **except** `flash-attn` first, then install `flash-attn` separately with build isolation **off** — it compiles a CUDA extension against your installed torch, so torch and a matching CUDA toolkit must already be present.
237
+
238
+ ```bash
239
+ cd Mage/mage_flow
240
+ uv venv && source .venv/bin/activate
241
+
242
+ # 1) Pinned, tested dependency set (torch 2.10, transformers 5.5, diffusers 0.38, pillow 12.3, …).
243
+ # Recommended for reproducibility. `uv pip install -e .` also works, but its loose
244
+ # bounds may resolve to a newer torch/transformers than the code was tested against.
245
+ uv pip install -r requirements.txt
246
+ uv pip install -e . --no-deps # the mage-flow package itself
247
+
248
+ # 2) flash-attn — needs build tools present and a CUDA toolkit whose MAJOR version
249
+ # matches your torch build (e.g. torch cu12x ↔ nvcc 12.x). A cu13/nvcc-12 mix fails.
250
+ uv pip install setuptools wheel ninja
251
+ uv pip install --no-build-isolation flash-attn==2.8.3
252
+ ```
253
+
254
+ Plain `pip` is equivalent (`pip install -r requirements.txt`, `pip install -e . --no-deps`, then the two flash-attn lines). This registers three commands: `mage-flow`, `mage-flow-edit`, `mage-flow-app`.
255
+
256
+ > **torch / CUDA:** the default PyPI torch wheel targets the newest CUDA (currently cu13x). If your machine's CUDA toolkit is 12.x, install torch from the matching index first, e.g. `uv pip install torch==2.10.0 torchvision==0.25.0 --index-url https://download.pytorch.org/whl/cu128`, otherwise the flash-attn build will fail with a CUDA-version mismatch.
257
+
258
+ ### Python API
259
+
260
+ `pipe.generate(prompts, **kw)` and `pipe.edit(prompts, ref_images, **kw)` return a `list[PIL.Image]` aligned with `prompts`. A `prompts` **list** is batched into one packed forward per denoise step (each sample can have its own resolution/seed).
261
+
262
+ **Text-to-image:**
263
+
264
+ ```python
265
+ from mage_flow import MageFlowPipeline
266
+
267
+ pipe = MageFlowPipeline.from_pretrained("microsoft/Mage-Flow", device="cuda")
268
+
269
+ # 1) single image
270
+ img = pipe.generate(["A close-up portrait of an elderly African man with deep wrinkles, wearing a traditional hat, soft natural lighting, ultra realistic."],
271
+ steps=20, cfg=5.0, heights=[1024], widths=[1024])[0]
272
+ img.save("t2i.png")
273
+
274
+ # 2) batch: several prompts / resolutions / seeds in ONE packed forward per step
275
+ imgs = pipe.generate(
276
+ ["the Salar de Uyuni mirror surface captured at high noon, with intimate stillness permeating the air. dew beads on every blade of grass. National Geographic editorial, cinematic depth, fine-grained natural texture.",
277
+ "A close-up portrait of an elderly African man with deep wrinkles, wearing a traditional hat, soft natural lighting, ultra realistic.",
278
+ "An immersive close-up of a steaming bowl of Sichuan mapo tofu over jasmine rice served on a hand-thrown ceramic plate, finished with a wedge of citrus. Surface oils catch a tiny specular highlight. Shot with a Hasselblad H6D-100c, ambient window light, the kind of image that makes the viewer hungry."],
279
+ heights=[512, 1024, 1792], widths=[2048, 1024, 1024], # per-sample; 4:1 is fine
280
+ seeds=[1, 2, 3], steps=20, cfg=5.0,
281
+ )
282
+ ```
283
+
284
+ **Image editing:**
285
+
286
+ ```python
287
+ pipe = MageFlowPipeline.from_pretrained("microsoft/Mage-Flow-Edit", device="cuda")
288
+
289
+ # single reference (path or PIL image)
290
+ img = pipe.edit(["Replace the background with a field of sunflowers"], ["assets/dog.jpg"],
291
+ steps=30, cfg=5.0, max_size=1024)[0]
292
+ img.save("single_edit.png")
293
+
294
+ # multi-image edit — ref_images[i] is a LIST of source images
295
+ img = pipe.edit(["blend the object from image 2 into image 1"],
296
+ [["scene.png", "object.png"]], steps=30, cfg=5.0)[0]
297
+ img.save("multi_edit.png")
298
+
299
+ # explicit output size (overrides max_size); Turbo edit = 4 steps / cfg 1
300
+ img = pipe.edit(["Replace the background with a field of sunflowers"], ["assets/dog.jpg"],
301
+ heights=[1024], widths=[1024], steps=4, cfg=1.0)[0]
302
+ img.save("single_edit_1024x1024.png")
303
+ ```
304
+
305
+ **Parameters** (shared by `generate` / `edit`):
306
+
307
+ | Parameter | Default | Description |
308
+ | :------------------------------- | :--------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
309
+ | `prompts` | — | string or list of strings; a list is batched into one forward per step |
310
+ | `ref_images` *(edit)* | — | per prompt: one image/path, or a**list** of images for multi-image edit |
311
+ | `steps` | `30` | denoising steps — Base`30`, RL `20`, Turbo `4` |
312
+ | `cfg` | `5.0` | classifier-free guidance scale (Turbo:`1.0`) |
313
+ | `heights`, `widths` | `[1024]` | per-sample output size, multiple of 16; native resolution`512`–`2048` |
314
+ | `max_size` *(edit)* | source size | longest output side; short side follows the reference's aspect ratio |
315
+ | `vl_cond_long_edge` *(edit)* | `384` | cap the long edge of the reference image fed to the**VL text encoder** (matches training preprocessing; the VAE/generation path keeps the full output resolution). `0`/`None` disables |
316
+ | `neg_prompts` | `" "` | per-sample negative prompt (applied when`cfg > 1`) |
317
+ | `seeds` | `42` | per-sample seed;`-1` = random |
318
+ | `batch_cfg` | `True` | fuse the CFG conditional + unconditional passes into one packed forward |
319
+ | `renormalization` | `False` | rescale guided velocity per token (reduces over-saturation at high cfg) |
320
+ | `static_shift` | `6.0` | override the flow-matching sigma shift |
321
+ | `prompt_template` | `mage-flow` / `mage-flow-edit` | text-encoder prompt template |
322
+
323
+ ### CLI
324
+
325
+ ```bash
326
+ # text-to-image (two prompts in one batch)
327
+ mage-flow --prompt "A close-up portrait of an elderly African man with deep wrinkles, wearing a traditional hat, soft natural lighting, ultra realistic." "An immersive landscape of a Greenlandic icefjord at midnight sun, painted by early dawn light, crystal-clear skies adding drama. fine grains of sand carving sharp shadows. Peter Lik gallery print, moody atmosphere, museum-grade composition." \
328
+ --model_path microsoft/Mage-Flow --steps 20 --cfg 5.0 \
329
+ --height 1024 512 --width 1024 2048 --seed 42 --out ./outputs
330
+
331
+
332
+ # editing (one --ref per prompt; comma-separate sources for multi-image edit)
333
+ mage-flow-edit --prompt "Replace the background with a field of sunflowers" "blend these two images" \
334
+ --ref assets/dog.jpg "scene.png,object.png" \
335
+ --model_path microsoft/Mage-Flow-Edit --max_size 1024 --out ./outputs
336
+ ```
337
+
338
+ | Flag | Scope | Meaning |
339
+ | :-------------------- | :---: | :---------------------------------------------------------------------------- |
340
+ | `--prompt` | both | one or more prompts, run as a batch (sample `i` uses `--seed + i`) |
341
+ | `--model_path` | both | local repo dir or HF Hub repo id (auto-downloaded + cached) |
342
+ | `--steps` | both | number of denoising steps |
343
+ | `--cfg` | both | classifier-free guidance scale |
344
+ | `--height` | both | output height — one value, or one per prompt for mixed resolutions |
345
+ | `--width` | both | output width — one value, or one per prompt for mixed resolutions |
346
+ | `--seed` | both | base seed (sample `i` uses `--seed + i`) |
347
+ | `--neg_prompt` | both | negative prompt |
348
+ | `--static_shift` | both | override the flow-matching sigma shift |
349
+ | `--out` | both | output directory |
350
+ | `--ref` | edit | reference image per prompt (comma-separate paths for a multi-image edit) |
351
+ | `--max_size` | edit | max size of the reference image |
352
+ | `--vl_cond_long_edge` | edit | VL-condition long edge (default `384`) |
353
+
354
+ ### Gradio app
355
+
356
+ ```bash
357
+ mage-flow-app # serve on http://0.0.0.0:7860 (or: python -m mage_flow.app)
358
+ ```
359
+
360
+ A web UI with **Text → Image** and **Image Edit** tabs; models load lazily on first use and are cached. Presets default to the `microsoft/Mage-Flow*` **Hugging Face repos** (downloaded + cached on first use); set `MAGEFLOW_HF_DIR` to load local checkpoint dirs instead.
361
+
362
+ **Launch options:**
363
+
364
+ | Flag | Default | Meaning |
365
+ | :------------ | :---------- | :-------------------------------------------------------------------------- |
366
+ | `--host` | `0.0.0.0` | bind address |
367
+ | `--port` | `7860` | port |
368
+ | `--device` | `cuda` | inference device |
369
+ | `--share` | off | create a public Gradio share link |
370
+ | `--preload` | *(lazy)* | comma-separated repo ids / paths to load at startup instead of on first use |
371
+
372
+ ## 📝 Citation
373
+
374
+ ```bibtex
375
+ @techreport{mageflow2026,
376
+ title = {Mage-Flow: An Efficient Native-Resolution Foundation Model for Image Generation and Editing},
377
+ author = {Microsoft Mage Team},
378
+ year = {2026},
379
+ institution = {Microsoft},
380
+ url = {https://github.com/microsoft/Mage}
381
+ }
382
+ ```