Metadata-Version: 2.4
Name: zimage-mnn
Version: 0.1.2
Summary: Z-Image-Turbo text-to-image generation on MNN (Apple Silicon Metal / CPU)
Author: ws
License: Apache-2.0
Project-URL: Homepage, https://github.com/alibaba/MNN
Keywords: mnn,diffusion,text-to-image,z-image,apple-silicon
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: MacOS
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: numpy
Requires-Dist: pillow
Requires-Dist: jinja2
Requires-Dist: mnn>=3.6.0
Requires-Dist: transformers>=4.40
Requires-Dist: huggingface_hub

# zimage-mnn

Run [Z-Image-Turbo](https://huggingface.co/Tongyi-MAI/Z-Image-Turbo) text-to-image locally with
[MNN](https://github.com/alibaba/MNN) — optimized for Apple Silicon (Metal) with a CPU fallback.

The 12.3B-parameter DiT is quantized to int8 weights and runs the full pipeline
(text encoder → 8-step denoiser → VAE) entirely on-device. No cloud calls.

## Install & run (one line)

```bash
uvx zimage-mnn "a cute cat sitting on a windowsill"
```

Models (~11 GB) download automatically on first run and are cached in `~/.cache/zimage_mnn`.

## CLI usage

```bash
# basic
uvx zimage-mnn "a red sports car on a coastal highway"

# options
uvx zimage-mnn "a panda eating bamboo" \
    --size 1024 \        # resolution (multiple of 16; model tuned for 1024)
    --steps 8 \          # denoising steps (2-12)
    --seed 42 \          # random seed
    --num-images 2 \     # generate several (seed increments)
    --output out.png \   # output file / prefix
    --backend metal      # auto | metal | cpu
```

## HTTP API

```bash
uvx zimage-mnn --api --port 8000
```

```bash
curl -X POST http://127.0.0.1:8000/generate \
     -H "Content-Type: application/json" \
     -d '{"prompt":"a cute cat","size":1024,"steps":8,"seed":42}' \
     -o cat.png
```

`GET /health` returns `{"status":"ok"}`.

## Python API

```python
from zimage_mnn import ZImageMNNPipeline

pipe = ZImageMNNPipeline.from_pretrained()          # downloads models
image = pipe("a cute cat", size=1024, steps=8, seed=42)
image.save("cat.png")

images = pipe.generate("a dog", num_images=3, seed=7)
```

## Performance (Apple M5 Pro, 1024×1024, 8 steps)

| Backend | per step | end-to-end |
|---------|----------|------------|
| Metal (fp32, int8 weights) | ~13 s | ~2 min |
| CPU (int8, 12 threads) | ~27 s | ~4 min |

Quality matches the original PyTorch pipeline (single-step cosine ≈ 0.9996).

## Requirements

- Python ≥ 3.9
- macOS with Apple Silicon recommended (Metal). CPU works anywhere but is slower.
- ~16 GB RAM recommended; ~11 GB disk for the models.

## License

Apache-2.0. Model weights derive from
[Tongyi-MAI/Z-Image-Turbo](https://huggingface.co/Tongyi-MAI/Z-Image-Turbo) — see its license.
