🎨 Qwen Image Edit API for Mac Silicon

A high-performance FastAPI-based REST API for running Qwen-Image-Edit locally on Apple Silicon Macs (M1/M2/M3/M4). Features automatic chip detection, optimized settings, and seamless model integration.

✨ Features

• 🚀 Automatic Silicon Detection: Detects M1/M2/M3/M4 and optimizes accordingly
• ⚡ MPS Acceleration: Leverages Metal Performance Shaders for speed
• 🔄 Multiple Fallbacks: CLI, Python module, and UVX support
• 📦 Batch Processing: Process multiple images with chip-specific limits
• 🎯 Auto-optimization: Automatic memory and batch size management
• 📝 Full API Documentation: Interactive Swagger/ReDoc interfaces
• 🧹 Background Cleanup: Automatic temporary file management
• 🌐 CORS Support: Ready for web integration

📊 Performance by Chip

Chip	RAM	Batch Size	Default Steps	Memory Usage
M1	8-16GB	3 images	10	60%
M2	8-24GB	4 images	10	65%
M3	8-36GB	5 images	10	70%
M4	16-64GB	6 images	10	75%

🛠 Installation

Prerequisites

• macOS 14.0+ on Apple Silicon
• Python 3.10+
• 54GB free disk space (for model weights)
• Xcode Command Line Tools

Quick Install

# Clone the repository
git clone https://github.com/hanishkeloth/qwen-image-edit-api.git
cd qwen-image-edit-api

# Create virtual environment
python3 -m venv venv
source venv/bin/activate

# Install dependencies
pip install -r requirements.txt

# Install Qwen model (choose one)
pip install qwen-image-mps           # Recommended
# OR
brew install qwen-image-mps          # Via Homebrew
# OR
uvx install qwen-image-mps           # Via UVX

Install from PyPI (Coming Soon)

pip install qwen-image-edit-api

🚀 Usage

Starting the Server

# Basic start
python main.py

# With hot reload (development)
uvicorn main:app --reload --host 0.0.0.0 --port 8000

# Production with workers
uvicorn main:app --workers 4 --host 0.0.0.0 --port 8000

API Endpoints

Health Check

curl http://localhost:8000/

Returns system info, chip detection, and optimization settings.

Edit Single Image

curl -X POST "http://localhost:8000/edit-image/" \
  -F "file=@input.jpg" \
  -F "prompt=Make it look like a sunset painting" \
  -F "steps=15" \
  --output result.jpg

Batch Processing

curl -X POST "http://localhost:8000/edit-images-batch/" \
  -F "files=@image1.jpg" \
  -F "files=@image2.jpg" \
  -F "prompt=Add dramatic lighting" \
  -F "steps=20"

Python Client Example

import requests

# Single image
with open("photo.jpg", "rb") as f:
    response = requests.post(
        "http://localhost:8000/edit-image/",
        files={"file": f},
        data={
            "prompt": "Transform into anime style",
            "steps": 15
        }
    )
    
with open("edited.jpg", "wb") as f:
    f.write(response.content)

JavaScript/Frontend Integration

const formData = new FormData();
formData.append('file', imageFile);
formData.append('prompt', 'Add snow effect');
formData.append('steps', '20');

const response = await fetch('http://localhost:8000/edit-image/', {
    method: 'POST',
    body: formData
});

const blob = await response.blob();
const imageUrl = URL.createObjectURL(blob);

📖 API Documentation

Interactive documentation available at:

• Swagger UI: http://localhost:8000/docs
• ReDoc: http://localhost:8000/redoc

🔧 Configuration

Environment Variables

# Optional: Set MPS fallback for compatibility
export PYTORCH_ENABLE_MPS_FALLBACK=1

# Optional: Adjust thread workers
export UVICORN_WORKERS=4

Optimization Tips by Model

M1 Mac mini/MacBook Air (8GB)

# Use lower steps for faster processing
steps = 5-10
# Process images one at a time

M2/M3 MacBook Pro (16-32GB)

# Balanced settings
steps = 10-20
# Batch up to 4 images

M4 Mac Studio (64GB+)

# High quality settings
steps = 20-50
# Batch up to 6 images

🧪 Testing

# Run test suite
python test_api.py

# Run with pytest (if installed)
pytest test_api.py -v

🤝 Contributing

We welcome contributions! See CONTRIBUTING.md for guidelines.

Priority Areas

• Performance optimizations for each chip
• Memory management improvements
• Additional model support
• WebUI development
• Unit test coverage

📊 Benchmarks

Operation	M1	M2	M3	M4
Single Image (10 steps)	45s	35s	28s	22s
Batch (3 images)	135s	105s	84s	66s
Memory Peak	6GB	7GB	8GB	9GB

Tested with 512x512 images

🔍 Troubleshooting

Common Issues

"Qwen-image-mps not found"

pip install qwen-image-mps --upgrade
export PATH=$PATH:~/.local/bin

Out of Memory

• Reduce batch size
• Lower steps parameter
• Close other applications
• Restart the server

Slow Performance

• Ensure MPS is enabled
• Check Activity Monitor for resource usage
• Use recommended settings for your chip

📄 License

MIT License - see LICENSE file.

🙏 Acknowledgments

• Qwen team for the amazing model
• FastAPI for the excellent framework
• Apple for Metal Performance Shaders
• Community contributors

👨‍💻 Author

Hanish Keloth
GitHub Profile

🔗 Links

• Report Issues
• Discussions
• Qwen Model Info

📈 Star History

---

Made with ❤️ for the Mac Silicon community by Hanish Keloth

This is an independent community project.