🪶 MagicQuill V2: Precise and Interactive Image Editing with Layered Visual Cues

video.mp4

Zichen Liu^*,1,2, Yue Yu^*,1,2, Hao Ouyang², Qiuyu Wang², Shuailei Ma^2,3, Ka Leong Cheng², Wen Wang^2,4, Qingyan Bai^1,2, Yuxuan Zhang⁵, Yanhong Zeng², Yixuan Li^2,5, Xing Zhu², Yujun Shen², Qifeng Chen¹

¹HKUST ²Ant Group ³NEU ⁴ZJU ⁵CUHK
^* Equal Contribution

TLDR: MagicQuill V2 introduces a layered composition paradigm to generative image editing, disentangling creative intent into controllable visual cues (Content, Spatial, Structural, Color) for precise and intuitive control.

• 🪶 MagicQuill V2: Precise and Interactive Image Editing with Layered Visual Cues
  • TODO List
  • Update Log
  • Hardware Requirements
  • Setup
  • System Overview
  • Tutorial
  • Citation
  • Acknowledgement

TODO List

• [✅] Release the paper and project page.
• [✅] Release the system with UI.
• [✅] Release gradio demo on HuggingFace.
• Release the batch inference code.
• Release the training code.

Update Log

• [2025.12.03] 📢 MagicQuill V2 is released!
• [Legacy] For the previous version (MagicQuill V1), which requires much less VRAM and computation resources, please visit MagicQuill V1 Repository.

Hardware Requirements

Our model is based on Flux Kontext, which is large and computationally intensive.

• VRAM: Approximately 40GB of VRAM is required for inference.
• Speed: It takes about 30 seconds to generate a single image.

Important: This is a research project focused on pushing the boundaries of interactive image editing. If you do not have sufficient GPU memory, we recommend checking out our MagicQuill V1 or trying the online demo on Hugging Face Spaces.

Setup

1. Clone the repository

   git clone https://github.com/magic-quill/MagicQuillV2.git
   cd MagicQuillV2

2. Create environment

   conda create -n MagicQuillV2 python=3.10 -y
   conda activate MagicQuillV2

3. Install dependencies

   pip install -r requirements.txt

4. Download models Download the models from Hugging Face and place them in the models/ directory.

   huggingface-cli download LiuZichen/MagicQuillV2-models --local-dir models

5. Run the demo

   python app.py

System Overview

The MagicQuill V2 interactive system is designed to unify our layered composition framework.

Key Upgrades from V1

1. Toolbar (A): Features a new Local Edit Brush for defining the target editing area, along with tools for sketching edges and applying color.
2. Visual Cue Manager (B): Holds all content layer visual cues (foreground props) that users can drag onto the canvas to define what to generate.
3. Image Segmentation Panel (C): Accessed via the segment icon, this panel allows precise object extraction using SAM (Segment Anything Model) with positive/negative dots or bounding boxes.

Tutorial

💡 For a detailed guide on the 5 layer operations, please visit our Project Page.

Citation

If you find MagicQuill V2 useful for your research, please cite our paper:

@article{liu2025magicquillv2,
  title={MagicQuill V2: Precise and Interactive Image Editing with Layered Visual Cues},
  author={Zichen Liu, Yue Yu, Hao Ouyang, Qiuyu Wang, Shuailei Ma, Ka Leong Cheng, Wen Wang, Qingyan Bai, Yuxuan Zhang, Yanhong Zeng, Yixuan Li, Xing Zhu, Yujun Shen, Qifeng Chen},
  journal={arXiv:2512.03046},
  year={2025}
}

Acknowledgement

Our implementation builds upon several great open-source projects:

• EasyControl
• ComfyUI
• comfyui_controlnet_aux
• fabric.js

We thank the authors for their contributions.

License: This repo is governed by the license of CC BY-NC 4.0. We strongly advise users not to knowingly generate or allow others to knowingly generate harmful content.