Mage-Flow

Mirror notice — SceneWorks weights-preservation snapshot

This repository is a verbatim, byte-identical mirror of microsoft/Mage-Flow, pinned at upstream revision faca09c18c1c19458e7fbc3f7bce6f7a7d4d01a9 (mirrored 2026-07-24). Nothing has been converted, quantized, re-packed or re-trained: transformer/, text_encoder/, vae/, scheduler/ and model_index.json are the upstream bytes. Only this notice, the front-matter license_link, and an added copy of the upstream LICENSE differ from the upstream card.

Why: durable org-owned archival copy. Microsoft removed microsoft/Lens from the Hub after release; this snapshot ensures SceneWorks builds stay reproducible if microsoft/Mage-Flow is withdrawn or force-pushed. It is not a fork and carries no changes of our own.

Verification: every LFS object was sha256-hashed locally and compared against upstream LFS metadata before upload — 24/24 LFS objects and 43/43 files matched, zero mismatches. Compare any file yourself against microsoft/Mage-Flow at revision faca09c18c1c19458e7fbc3f7bce6f7a7d4d01a9.

License: MIT, unchanged, © Microsoft. See LICENSE.

Model role in the family: text-to-image aligned / post-trained.

Shared components: text_encoder/ (Qwen3-VL, 8.875 GB) and vae/ (Mage-VAE, 0.345 GB) are bit-identical across all six Mage-Flow repos, as are all four config files. The six models differ only in transformer/diffusion_pytorch_model.safetensors (8.232 GB). Each mirror below is nonetheless self-contained and independently restorable.

Upstream	SceneWorks mirror	Mirrored revision
microsoft/Mage-Flow-Base	SceneWorks/Mage-Flow-Base	59a9cfd58cf6ecef28245852c6bdace3f12428a2
microsoft/Mage-Flow	SceneWorks/Mage-Flow	faca09c18c1c19458e7fbc3f7bce6f7a7d4d01a9
microsoft/Mage-Flow-Turbo	SceneWorks/Mage-Flow-Turbo	34f3a2d25248500a5352646b335775c07e1bd8aa
microsoft/Mage-Flow-Edit-Base	SceneWorks/Mage-Flow-Edit-Base	8654a7bc0283ab2946385230b5b2eb944e0b76ea
microsoft/Mage-Flow-Edit	SceneWorks/Mage-Flow-Edit	b01d524f86498b7dabcc4b3572c6d264d786a16e
microsoft/Mage-Flow-Edit-Turbo	SceneWorks/Mage-Flow-Edit-Turbo	14427bd7627d3a25436497a5939e1096f6a0d523

Links in the upstream card body below still point at microsoft/*; use the table above for the archival copies.

---

<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> <p align="center"> <a href="https://arxiv.org/abs/2607.19064"><img alt="arXiv" src="https://img.shields.io/badge/arXiv-Mage--Flow-b31b1b" height="22" /></a> <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> <a href="https://github.com/microsoft/Mage"><img src="https://img.shields.io/badge/Code-GitHub-181717?logo=github" alt="GitHub"></a> <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> <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> <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> <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> <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> <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> <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/License-MIT-green" alt="License: MIT"></a> </p> <!-- <p align="center"> <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> <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> <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> <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> <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> <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> </p> --> <div align="center"> <img src="assets/mage-flow-cover.png" width="100%" alt="gallery"> </div>

---

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.

The stack is built from two shared, co-designed components:

• Mage-VAE — a lightweight, high-fidelity latent tokenizer (one-step diffusion encode/decode with anchor-latent KL regularization).
• NR-MMDiT — a shared 4B Native-Resolution Multimodal Diffusion Transformer, trained with rectified flow matching in the Mage-VAE latent space.

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.

✨ Highlights

• 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).
• 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.
• Native resolution. One checkpoint generates from 512 to 2048 on any aspect ratio, including extreme 4:1 (e.g. 512×2048, 2048×512).
• System-level speed. Native-resolution packing (FlashAttention var-len + per-sample 2D RoPE) + fused CUDA kernels cut per-step training time from ~1.93 s → ~0.78 s (~2.5× faster training); CFG's conditional/unconditional branches run in one packed forward.
• Full family. Base, RL-aligned, and 4-step Turbo variants for both generation and editing.
• 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.
• 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).

<div align="center"> <img src="assets/one_to_many_editing_diversity.jpg" width="100%" alt="One-to-many editing diversity"><br> <em>One-to-many editing diversity — Mage-Flow-Edit can generate diverse outputs from a single reference image.</em> </div>

📥 Model Zoo

Each checkpoint is a self-contained diffusers-style repo (transformer/ + shared vae/, text_encoder/, scheduler/).

🖼️ Showcase

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.)

<details open> <summary><b>Showcase</b></summary> <div align="center"><img src="assets/t2i_teaser.jpg" width="100%" alt="t2i teaser"></div> </details> <details> <summary><b>General scenes</b></summary> <div align="center"><img src="assets/general.jpg" width="100%" alt="general scenes"></div> </details> <details> <summary><b>Portraits</b></summary> <div align="center"><img src="assets/portrait.jpg" width="100%" alt="portraits"></div> </details> <details> <summary><b>Cuisine & still life</b></summary> <div align="center"><img src="assets/cuisine.jpg" width="100%" alt="cuisine"></div> </details> <details> <summary><b>English text rendering</b></summary> <div align="center"><img src="assets/text_en.jpg" width="100%" alt="english text"></div> </details> <details> <summary><b>Chinese text rendering</b></summary> <div align="center"><img src="assets/text_zh.jpg" width="100%" alt="chinese text"></div> </details>

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.)

<details open> <summary><b>Various Editing I</b></summary> <div align="center"><img src="assets/edit_gallery_showcase_1.jpg" width="100%" alt="editing showcase 1"></div> </details> <details> <summary><b>Various Editing II</b></summary> <div align="center"><img src="assets/edit_gallery_showcase_2.jpg" width="100%" alt="editing showcase 2"></div> </details> <details> <summary><b>Localized content & object editing</b></summary> <div align="center"><img src="assets/edit_gallery_content.jpg" width="100%" alt="content editing"></div> </details> <details> <summary><b>Scene, subject & camera transformations</b></summary> <div align="center"><img src="assets/edit_gallery_scene_subject.jpg" width="100%" alt="scene and subject"></div> </details> <details> <summary><b>Appearance & artistic rendering</b></summary> <div align="center"><img src="assets/edit_gallery_appearance.jpg" width="100%" alt="appearance"></div> </details> <details> <summary><b>Human-centered & creative editing</b></summary> <div align="center"><img src="assets/edit_gallery_human_creative.jpg" width="100%" alt="human-centered and creative"></div> </details> <details> <summary><b>Low-level vision & conditional reconstruction</b></summary> <div align="center"><img src="assets/edit_gallery_lowlevel.jpg" width="100%" alt="low-level vision"></div> </details> <details> <summary><b>Bidirectional degradation & restoration</b></summary> <div align="center"><img src="assets/edit_gallery_restoration.jpg" width="100%" alt="restoration"></div> </details>

📊 Performance

<details> <summary><b>Full benchmark tables (text-to-image & image editing) — click to expand</b></summary>

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.

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.

</details>

🏗️ Architecture

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.

<div align="center"> <img src="assets/mage_vae.jpg" width="100%" alt="Mage-VAE architecture and training"><br> <em>Mage-VAE — anchor VAE (FLUX.2-VAE), the symmetric one-step encoder/decoder architecture, and the three-stage training pipeline.</em> </div>

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.

<div align="center"> <img src="assets/nr_mmdit.jpg" width="100%" alt="Mage-Flow / Native-Resolution MMDiT architecture"><br> <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> </div>

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.

🚀 Quick Start

Installation

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.

cd Mage/mage_flow
uv venv && source .venv/bin/activate

# 1) Pinned, tested dependency set (torch 2.13, transformers 5.5, diffusers 0.38, pillow 12.3, …).
#    Recommended for reproducibility. `uv pip install -e .` also works, but its loose
#    bounds may resolve to a newer torch/transformers than the code was tested against.
uv pip install -r requirements.txt
uv pip install -e . --no-deps           # the mage-flow package itself

# 2) flash-attn — needs build tools present and a CUDA toolkit whose MAJOR version
#    matches your torch build (e.g. torch cu12x ↔ nvcc 12.x). A cu13/nvcc-12 mix fails.
uv pip install setuptools wheel ninja
uv pip install --no-build-isolation flash-attn==2.8.3

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.

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.13.0 torchvision==0.28.0 --index-url https://download.pytorch.org/whl/cu126, otherwise the flash-attn build will fail with a CUDA-version mismatch. (torch 2.13.0 ships cu126/cu129/cu130 wheels — pick the one matching your nvcc.)

Python API

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).

Text-to-image:

from mage_flow import MageFlowPipeline

pipe = MageFlowPipeline.from_pretrained("microsoft/Mage-Flow", device="cuda")

# 1) single image
img = pipe.generate(["A close-up portrait of an elderly African man with deep wrinkles, wearing a traditional hat, soft natural lighting, ultra realistic."],
                    steps=20, cfg=5.0, heights=[1024], widths=[1024])[0]
img.save("t2i.png")

# 2) batch: several prompts / resolutions / seeds in ONE packed forward per step
imgs = pipe.generate(
    ["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.", 
     "A close-up portrait of an elderly African man with deep wrinkles, wearing a traditional hat, soft natural lighting, ultra realistic.", 
     "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."],
    heights=[512, 1024, 1792], widths=[2048, 1024, 1024],   # per-sample; 4:1 is fine
    seeds=[1, 2, 3], steps=20, cfg=5.0,
)

Image editing:

from mage_flow import MageFlowPipeline

pipe = MageFlowPipeline.from_pretrained("microsoft/Mage-Flow-Edit", device="cuda")

# single reference (path or PIL image)
img = pipe.edit(["Replace the background with a field of sunflowers"], ["assets/dog.jpg"],
                steps=30, cfg=5.0, max_size=1024)[0]
img.save("single_edit.png")

# multi-image edit — ref_images[i] is a LIST of source images
img = pipe.edit(["blend the object from image 2 into image 1"],
                [["scene.png", "object.png"]], steps=30, cfg=5.0)[0]
img.save("multi_edit.png")

# explicit output size (overrides max_size); Turbo edit = 4 steps / cfg 1
img = pipe.edit(["Replace the background with a field of sunflowers"], ["assets/dog.jpg"],
                heights=[1024], widths=[1024], steps=4, cfg=1.0)[0]
img.save("single_edit_1024x1024.png")

Parameters (shared by generate / edit):

CLI

# text-to-image (two prompts in one batch)
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." \
          --model_path microsoft/Mage-Flow --steps 20 --cfg 5.0 \
          --height 1024 512 --width 1024 2048 --seed 42 --out ./outputs


# editing (one --ref per prompt; comma-separate sources for multi-image edit)
mage-flow-edit --prompt "Replace the background with a field of sunflowers" "blend these two images" \
               --ref assets/dog.jpg "scene.png,object.png" \
               --model_path microsoft/Mage-Flow-Edit --max_size 1024 --out ./outputs

Gradio app

mage-flow-app                     # serve on http://0.0.0.0:7860  (or: python -m mage_flow.app)

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.

Launch options:

📝 Citation

@article{zhang2026mageflow,
  title={Mage-Flow: An Efficient Native-Resolution Foundation Model for Image Generation and Editing},
  author={Zhang, Xinjie and Zhang, Peng and Zheng, Shicheng and Guo, Jinghao and Jia, Zhaoyang and Shen, Yifei and Guo, Xun and Luo, Yuxuan and Li, Jiahao and Xie, Wenxuan and Pu, Fanyi and Zhang, Xiaoyi and Zhang, Kaichen and Guo, Zongyu and Bi, Tianci and Gui, Dongnan and Liu, Zhening and Wen, Zimo and Zheng, Zihan and Yang, Senqiao and Li, Xiao and Wang, Jinglu and Li, Bin and Lu, Yan},
  journal={arXiv preprint arXiv:2607.19064},
  year={2026}
}