README.md

---
library_name: mlx
license: apache-2.0
license_link: https://huggingface.co/Tongyi-MAI/Z-Image/blob/main/LICENSE
pipeline_tag: text-to-image
base_model: Tongyi-MAI/Z-Image
language: [en, zh]
tags: [mlx, safetensors, apple-silicon, text-to-image, diffusion, s3-dit, z-image]
---

# mlx-community/Z-Image-bf16

MLX (bf16) conversion of **[Tongyi-MAI/Z-Image](https://huggingface.co/Tongyi-MAI/Z-Image)** (Apache-2.0) for Apple
Silicon — a 6.15B single-stream **S3-DiT** text-to-image model (Qwen3-4B thinking-template
conditioning → single-stream DiT → FLUX.1-dev AE decode). **Base tier**: non-distilled ~28-step with CFG + negative prompts (scheduler shift 6.0) — the quality / LoRA-substrate tier.

Standard diffusers-tree snapshot (`transformer/ text_encoder/ vae/ tokenizer/ scheduler/`) with the
transformer stored at bf16. Loaded by the Swift/MLX port; int8/int4 are produced at load time
(correct resident footprint — a q4 pipeline ≈ 6 GB fits a 16 GB Mac).

## Parity (Swift port vs PyTorch goldens, fp32/CPU stream)
- Full 6.15B S3-DiT: cosine **≥0.9999999** (both aligned + padded token cases)
- FLUX.1-dev AE decode: **118 dB** · Qwen3-4B encoder: token ids **exact**, features cosine **1.0000000**
- Full pipeline e2e: **105–108 dB** (256²/CPU)

## Use (Swift / MLXEngine)

```swift
import MLXZImage
import MLXToolKit
let package = ZImageTurboT2IPackage(configuration: .turbo(quant: .int4, snapshotPath: "<this repo dir>"))
try await package.load()
let r = try await package.run(T2IRequest(prompt: "a lighthouse at dusk, photorealistic",
                                         width: 1024, height: 1024, seed: 42)) as! T2IResponse
```

Code: https://github.com/xocialize/z-image-swift