Hugging Face's logo

moonbox-dev
/
Z-Image-Turbo-MLX

Text-to-Image
MLX
Safetensors
Diffusion Single File
moonbox
z-image
Model card Files
xet
 Community
Z-Image-Turbo-MLX
File size: 30,541 Bytes
2b2973f
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
f5c75dc
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
b18450f
 
 
 
 
 
 
 
 
 
 
 
 
 
79f5aaa
 
 
 
 
 
 
 
 
 
 
 
 
2b2973f
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
---
base_model: Tongyi-MAI/Z-Image-Turbo
base_model_relation: quantized
license: apache-2.0
pipeline_tag: text-to-image
library_name: mlx
tags:
- mlx
- moonbox
- z-image
- text-to-image
- diffusion-single-file
---

# Z-Image-Turbo MLX

MLX builds of [Z-Image-Turbo](https://huggingface.co/Tongyi-MAI/Z-Image-Turbo), made by Moonbox for Apple Silicon Macs. Each precision is a folder; keep a folder's
files together. Only the parts listed below are converted: the rest of the pipeline comes from the original
repository unless the section below says otherwise.

## Files

The last column is how far each build is from the original PyTorch model on the same inputs (see the section below
for what was measured).

| Precision | File | Size | sha256 | Checked against the original |
|---|---|---|---|---|
| bf16 | [`bf16/mflux_model.json`](https://huggingface.co/moonbox-ai/Z-Image-Turbo-MLX/blob/main/bf16/mflux_model.json) | 0.4 kB | `82aac4aab78f` | PSNR 22.1 dB mean, LPIPS 0.118 mean / 0.147 worst |
| bf16 | [`bf16/text_encoder/0.safetensors`](https://huggingface.co/moonbox-ai/Z-Image-Turbo-MLX/blob/main/bf16/text_encoder/0.safetensors) | 2.14 GB | `d9da5eee77aa` | PSNR 22.1 dB mean, LPIPS 0.118 mean / 0.147 worst |
| bf16 | [`bf16/text_encoder/1.safetensors`](https://huggingface.co/moonbox-ai/Z-Image-Turbo-MLX/blob/main/bf16/text_encoder/1.safetensors) | 2.12 GB | `21bc20095866` | PSNR 22.1 dB mean, LPIPS 0.118 mean / 0.147 worst |
| bf16 | [`bf16/text_encoder/2.safetensors`](https://huggingface.co/moonbox-ai/Z-Image-Turbo-MLX/blob/main/bf16/text_encoder/2.safetensors) | 2.12 GB | `22617bc5ebe6` | PSNR 22.1 dB mean, LPIPS 0.118 mean / 0.147 worst |
| bf16 | [`bf16/text_encoder/3.safetensors`](https://huggingface.co/moonbox-ai/Z-Image-Turbo-MLX/blob/main/bf16/text_encoder/3.safetensors) | 1.66 GB | `2f5cf62a722c` | PSNR 22.1 dB mean, LPIPS 0.118 mean / 0.147 worst |
| bf16 | [`bf16/text_encoder/model.safetensors.index.json`](https://huggingface.co/moonbox-ai/Z-Image-Turbo-MLX/blob/main/bf16/text_encoder/model.safetensors.index.json) | 22.9 kB | `a37d814cbc0a` | PSNR 22.1 dB mean, LPIPS 0.118 mean / 0.147 worst |
| bf16 | [`bf16/tokenizer/chat_template.jinja`](https://huggingface.co/moonbox-ai/Z-Image-Turbo-MLX/blob/main/bf16/tokenizer/chat_template.jinja) | 4.2 kB | `a55ee1b16601` | PSNR 22.1 dB mean, LPIPS 0.118 mean / 0.147 worst |
| bf16 | [`bf16/tokenizer/tokenizer.json`](https://huggingface.co/moonbox-ai/Z-Image-Turbo-MLX/blob/main/bf16/tokenizer/tokenizer.json) | 11.4 MB | `be75606093db` | PSNR 22.1 dB mean, LPIPS 0.118 mean / 0.147 worst |
| bf16 | [`bf16/tokenizer/tokenizer_config.json`](https://huggingface.co/moonbox-ai/Z-Image-Turbo-MLX/blob/main/bf16/tokenizer/tokenizer_config.json) | 0.7 kB | `1cc816812993` | PSNR 22.1 dB mean, LPIPS 0.118 mean / 0.147 worst |
| bf16 | [`bf16/transformer/0.safetensors`](https://huggingface.co/moonbox-ai/Z-Image-Turbo-MLX/blob/main/bf16/transformer/0.safetensors) | 2.09 GB | `30d27b9e25de` | PSNR 22.1 dB mean, LPIPS 0.118 mean / 0.147 worst |
| bf16 | [`bf16/transformer/1.safetensors`](https://huggingface.co/moonbox-ai/Z-Image-Turbo-MLX/blob/main/bf16/transformer/1.safetensors) | 2.09 GB | `b64e74b43702` | PSNR 22.1 dB mean, LPIPS 0.118 mean / 0.147 worst |
| bf16 | [`bf16/transformer/2.safetensors`](https://huggingface.co/moonbox-ai/Z-Image-Turbo-MLX/blob/main/bf16/transformer/2.safetensors) | 2.09 GB | `4e2ae217bc4a` | PSNR 22.1 dB mean, LPIPS 0.118 mean / 0.147 worst |
| bf16 | [`bf16/transformer/3.safetensors`](https://huggingface.co/moonbox-ai/Z-Image-Turbo-MLX/blob/main/bf16/transformer/3.safetensors) | 2.14 GB | `54a0e97b1a75` | PSNR 22.1 dB mean, LPIPS 0.118 mean / 0.147 worst |
| bf16 | [`bf16/transformer/4.safetensors`](https://huggingface.co/moonbox-ai/Z-Image-Turbo-MLX/blob/main/bf16/transformer/4.safetensors) | 2.14 GB | `bfe37ec4ec90` | PSNR 22.1 dB mean, LPIPS 0.118 mean / 0.147 worst |
| bf16 | [`bf16/transformer/5.safetensors`](https://huggingface.co/moonbox-ai/Z-Image-Turbo-MLX/blob/main/bf16/transformer/5.safetensors) | 1.75 GB | `8545b1fb9bdd` | PSNR 22.1 dB mean, LPIPS 0.118 mean / 0.147 worst |
| bf16 | [`bf16/transformer/model.safetensors.index.json`](https://huggingface.co/moonbox-ai/Z-Image-Turbo-MLX/blob/main/bf16/transformer/model.safetensors.index.json) | 29.7 kB | `7a6841af938d` | PSNR 22.1 dB mean, LPIPS 0.118 mean / 0.147 worst |
| bf16 | [`bf16/vae/0.safetensors`](https://huggingface.co/moonbox-ai/Z-Image-Turbo-MLX/blob/main/bf16/vae/0.safetensors) | 167.7 MB | `ca34451d9193` | PSNR 22.1 dB mean, LPIPS 0.118 mean / 0.147 worst |
| bf16 | [`bf16/vae/model.safetensors.index.json`](https://huggingface.co/moonbox-ai/Z-Image-Turbo-MLX/blob/main/bf16/vae/model.safetensors.index.json) | 16.3 kB | `e3834c6ff50a` | PSNR 22.1 dB mean, LPIPS 0.118 mean / 0.147 worst |
| 8bit | [`8bit/mflux_model.json`](https://huggingface.co/moonbox-ai/Z-Image-Turbo-MLX/blob/main/8bit/mflux_model.json) | 0.4 kB | `68820777b037` | below threshold (experimental): PSNR 21.0 dB, LPIPS 0.141 mean / 0.201 worst |
| 8bit | [`8bit/text_encoder/0.safetensors`](https://huggingface.co/moonbox-ai/Z-Image-Turbo-MLX/blob/main/8bit/text_encoder/0.safetensors) | 2.15 GB | `4756c0deba13` | below threshold (experimental): PSNR 21.0 dB, LPIPS 0.141 mean / 0.201 worst |
| 8bit | [`8bit/text_encoder/1.safetensors`](https://huggingface.co/moonbox-ai/Z-Image-Turbo-MLX/blob/main/8bit/text_encoder/1.safetensors) | 2.13 GB | `d3175a404177` | below threshold (experimental): PSNR 21.0 dB, LPIPS 0.141 mean / 0.201 worst |
| 8bit | [`8bit/text_encoder/model.safetensors.index.json`](https://huggingface.co/moonbox-ai/Z-Image-Turbo-MLX/blob/main/8bit/text_encoder/model.safetensors.index.json) | 51.3 kB | `b92fbec4b1fe` | below threshold (experimental): PSNR 21.0 dB, LPIPS 0.141 mean / 0.201 worst |
| 8bit | [`8bit/tokenizer/chat_template.jinja`](https://huggingface.co/moonbox-ai/Z-Image-Turbo-MLX/blob/main/8bit/tokenizer/chat_template.jinja) | 4.2 kB | `a55ee1b16601` | below threshold (experimental): PSNR 21.0 dB, LPIPS 0.141 mean / 0.201 worst |
| 8bit | [`8bit/tokenizer/tokenizer.json`](https://huggingface.co/moonbox-ai/Z-Image-Turbo-MLX/blob/main/8bit/tokenizer/tokenizer.json) | 11.4 MB | `be75606093db` | below threshold (experimental): PSNR 21.0 dB, LPIPS 0.141 mean / 0.201 worst |
| 8bit | [`8bit/tokenizer/tokenizer_config.json`](https://huggingface.co/moonbox-ai/Z-Image-Turbo-MLX/blob/main/8bit/tokenizer/tokenizer_config.json) | 0.7 kB | `1cc816812993` | below threshold (experimental): PSNR 21.0 dB, LPIPS 0.141 mean / 0.201 worst |
| 8bit | [`8bit/transformer/0.safetensors`](https://huggingface.co/moonbox-ai/Z-Image-Turbo-MLX/blob/main/8bit/transformer/0.safetensors) | 2.13 GB | `0ed0f24a2983` | below threshold (experimental): PSNR 21.0 dB, LPIPS 0.141 mean / 0.201 worst |
| 8bit | [`8bit/transformer/1.safetensors`](https://huggingface.co/moonbox-ai/Z-Image-Turbo-MLX/blob/main/8bit/transformer/1.safetensors) | 2.15 GB | `7f2063711f79` | below threshold (experimental): PSNR 21.0 dB, LPIPS 0.141 mean / 0.201 worst |
| 8bit | [`8bit/transformer/2.safetensors`](https://huggingface.co/moonbox-ai/Z-Image-Turbo-MLX/blob/main/8bit/transformer/2.safetensors) | 2.13 GB | `7aa3cd2e7306` | below threshold (experimental): PSNR 21.0 dB, LPIPS 0.141 mean / 0.201 worst |
| 8bit | [`8bit/transformer/3.safetensors`](https://huggingface.co/moonbox-ai/Z-Image-Turbo-MLX/blob/main/8bit/transformer/3.safetensors) | 129.6 MB | `89daaf83b97b` | below threshold (experimental): PSNR 21.0 dB, LPIPS 0.141 mean / 0.201 worst |
| 8bit | [`8bit/transformer/model.safetensors.index.json`](https://huggingface.co/moonbox-ai/Z-Image-Turbo-MLX/blob/main/8bit/transformer/model.safetensors.index.json) | 61.6 kB | `3deb0349ca67` | below threshold (experimental): PSNR 21.0 dB, LPIPS 0.141 mean / 0.201 worst |
| 8bit | [`8bit/vae/0.safetensors`](https://huggingface.co/moonbox-ai/Z-Image-Turbo-MLX/blob/main/8bit/vae/0.safetensors) | 165.7 MB | `cba8dc410ab2` | below threshold (experimental): PSNR 21.0 dB, LPIPS 0.141 mean / 0.201 worst |
| 8bit | [`8bit/vae/model.safetensors.index.json`](https://huggingface.co/moonbox-ai/Z-Image-Turbo-MLX/blob/main/8bit/vae/model.safetensors.index.json) | 17.4 kB | `a4a46b43b530` | below threshold (experimental): PSNR 21.0 dB, LPIPS 0.141 mean / 0.201 worst |
| 6bit | [`6bit/mflux_model.json`](https://huggingface.co/moonbox-ai/Z-Image-Turbo-MLX/blob/main/6bit/mflux_model.json) | 0.4 kB | `4473625f76d8` | below threshold (experimental): PSNR 20.2 dB, LPIPS 0.164 mean / 0.227 worst |
| 6bit | [`6bit/text_encoder/0.safetensors`](https://huggingface.co/moonbox-ai/Z-Image-Turbo-MLX/blob/main/6bit/text_encoder/0.safetensors) | 2.14 GB | `8f025c99044b` | below threshold (experimental): PSNR 20.2 dB, LPIPS 0.164 mean / 0.227 worst |
| 6bit | [`6bit/text_encoder/1.safetensors`](https://huggingface.co/moonbox-ai/Z-Image-Turbo-MLX/blob/main/6bit/text_encoder/1.safetensors) | 1.13 GB | `3830cc1f9390` | below threshold (experimental): PSNR 20.2 dB, LPIPS 0.164 mean / 0.227 worst |
| 6bit | [`6bit/text_encoder/model.safetensors.index.json`](https://huggingface.co/moonbox-ai/Z-Image-Turbo-MLX/blob/main/6bit/text_encoder/model.safetensors.index.json) | 51.3 kB | `5d9c5b6ad65b` | below threshold (experimental): PSNR 20.2 dB, LPIPS 0.164 mean / 0.227 worst |
| 6bit | [`6bit/tokenizer/chat_template.jinja`](https://huggingface.co/moonbox-ai/Z-Image-Turbo-MLX/blob/main/6bit/tokenizer/chat_template.jinja) | 4.2 kB | `a55ee1b16601` | below threshold (experimental): PSNR 20.2 dB, LPIPS 0.164 mean / 0.227 worst |
| 6bit | [`6bit/tokenizer/tokenizer.json`](https://huggingface.co/moonbox-ai/Z-Image-Turbo-MLX/blob/main/6bit/tokenizer/tokenizer.json) | 11.4 MB | `be75606093db` | below threshold (experimental): PSNR 20.2 dB, LPIPS 0.164 mean / 0.227 worst |
| 6bit | [`6bit/tokenizer/tokenizer_config.json`](https://huggingface.co/moonbox-ai/Z-Image-Turbo-MLX/blob/main/6bit/tokenizer/tokenizer_config.json) | 0.7 kB | `1cc816812993` | below threshold (experimental): PSNR 20.2 dB, LPIPS 0.164 mean / 0.227 worst |
| 6bit | [`6bit/transformer/0.safetensors`](https://huggingface.co/moonbox-ai/Z-Image-Turbo-MLX/blob/main/6bit/transformer/0.safetensors) | 2.14 GB | `973ba309094e` | below threshold (experimental): PSNR 20.2 dB, LPIPS 0.164 mean / 0.227 worst |
| 6bit | [`6bit/transformer/1.safetensors`](https://huggingface.co/moonbox-ai/Z-Image-Turbo-MLX/blob/main/6bit/transformer/1.safetensors) | 2.14 GB | `fdd39290bb7c` | below threshold (experimental): PSNR 20.2 dB, LPIPS 0.164 mean / 0.227 worst |
| 6bit | [`6bit/transformer/2.safetensors`](https://huggingface.co/moonbox-ai/Z-Image-Turbo-MLX/blob/main/6bit/transformer/2.safetensors) | 723.2 MB | `69fa2a1d701b` | below threshold (experimental): PSNR 20.2 dB, LPIPS 0.164 mean / 0.227 worst |
| 6bit | [`6bit/transformer/model.safetensors.index.json`](https://huggingface.co/moonbox-ai/Z-Image-Turbo-MLX/blob/main/6bit/transformer/model.safetensors.index.json) | 61.6 kB | `558852a66f31` | below threshold (experimental): PSNR 20.2 dB, LPIPS 0.164 mean / 0.227 worst |
| 6bit | [`6bit/vae/0.safetensors`](https://huggingface.co/moonbox-ai/Z-Image-Turbo-MLX/blob/main/6bit/vae/0.safetensors) | 165.2 MB | `ae30e4e6c93e` | below threshold (experimental): PSNR 20.2 dB, LPIPS 0.164 mean / 0.227 worst |
| 6bit | [`6bit/vae/model.safetensors.index.json`](https://huggingface.co/moonbox-ai/Z-Image-Turbo-MLX/blob/main/6bit/vae/model.safetensors.index.json) | 17.4 kB | `e287457d19ea` | below threshold (experimental): PSNR 20.2 dB, LPIPS 0.164 mean / 0.227 worst |
| 4bit | [`4bit/mflux_model.json`](https://huggingface.co/moonbox-ai/Z-Image-Turbo-MLX/blob/main/4bit/mflux_model.json) | 0.4 kB | `af71e0c5fca8` | below threshold (experimental): PSNR 17.0 dB, LPIPS 0.246 mean / 0.265 worst |
| 4bit | [`4bit/text_encoder/0.safetensors`](https://huggingface.co/moonbox-ai/Z-Image-Turbo-MLX/blob/main/4bit/text_encoder/0.safetensors) | 2.14 GB | `65b5e0fac735` | below threshold (experimental): PSNR 17.0 dB, LPIPS 0.246 mean / 0.265 worst |
| 4bit | [`4bit/text_encoder/1.safetensors`](https://huggingface.co/moonbox-ai/Z-Image-Turbo-MLX/blob/main/4bit/text_encoder/1.safetensors) | 127.6 MB | `adc84cd2f289` | below threshold (experimental): PSNR 17.0 dB, LPIPS 0.246 mean / 0.265 worst |
| 4bit | [`4bit/text_encoder/model.safetensors.index.json`](https://huggingface.co/moonbox-ai/Z-Image-Turbo-MLX/blob/main/4bit/text_encoder/model.safetensors.index.json) | 51.3 kB | `a5d86c766488` | below threshold (experimental): PSNR 17.0 dB, LPIPS 0.246 mean / 0.265 worst |
| 4bit | [`4bit/tokenizer/chat_template.jinja`](https://huggingface.co/moonbox-ai/Z-Image-Turbo-MLX/blob/main/4bit/tokenizer/chat_template.jinja) | 4.2 kB | `a55ee1b16601` | below threshold (experimental): PSNR 17.0 dB, LPIPS 0.246 mean / 0.265 worst |
| 4bit | [`4bit/tokenizer/tokenizer.json`](https://huggingface.co/moonbox-ai/Z-Image-Turbo-MLX/blob/main/4bit/tokenizer/tokenizer.json) | 11.4 MB | `be75606093db` | below threshold (experimental): PSNR 17.0 dB, LPIPS 0.246 mean / 0.265 worst |
| 4bit | [`4bit/tokenizer/tokenizer_config.json`](https://huggingface.co/moonbox-ai/Z-Image-Turbo-MLX/blob/main/4bit/tokenizer/tokenizer_config.json) | 0.7 kB | `1cc816812993` | below threshold (experimental): PSNR 17.0 dB, LPIPS 0.246 mean / 0.265 worst |
| 4bit | [`4bit/transformer/0.safetensors`](https://huggingface.co/moonbox-ai/Z-Image-Turbo-MLX/blob/main/4bit/transformer/0.safetensors) | 2.14 GB | `a81159ebd7ff` | below threshold (experimental): PSNR 17.0 dB, LPIPS 0.246 mean / 0.265 worst |
| 4bit | [`4bit/transformer/1.safetensors`](https://huggingface.co/moonbox-ai/Z-Image-Turbo-MLX/blob/main/4bit/transformer/1.safetensors) | 1.32 GB | `ef02d88179ed` | below threshold (experimental): PSNR 17.0 dB, LPIPS 0.246 mean / 0.265 worst |
| 4bit | [`4bit/transformer/model.safetensors.index.json`](https://huggingface.co/moonbox-ai/Z-Image-Turbo-MLX/blob/main/4bit/transformer/model.safetensors.index.json) | 61.6 kB | `204a023adee4` | below threshold (experimental): PSNR 17.0 dB, LPIPS 0.246 mean / 0.265 worst |
| 4bit | [`4bit/vae/0.safetensors`](https://huggingface.co/moonbox-ai/Z-Image-Turbo-MLX/blob/main/4bit/vae/0.safetensors) | 164.7 MB | `1c8eaf3d17de` | below threshold (experimental): PSNR 17.0 dB, LPIPS 0.246 mean / 0.265 worst |
| 4bit | [`4bit/vae/model.safetensors.index.json`](https://huggingface.co/moonbox-ai/Z-Image-Turbo-MLX/blob/main/4bit/vae/model.safetensors.index.json) | 17.4 kB | `fb17ac2a8587` | below threshold (experimental): PSNR 17.0 dB, LPIPS 0.246 mean / 0.265 worst |

## How to run

Each folder is the whole pipeline (Qwen3 text encoder, transformer, VAE, tokenizer) saved by
[mflux](https://github.com/filipstrand/mflux) 0.24.0 from the original weights at the revision below. Run it with
mflux:

```bash
pip install mflux==0.24.0
hf download moonbox-ai/Z-Image-Turbo-MLX --include "bf16/*" --local-dir zimage
mflux-generate-z-image-turbo --model zimage/bf16 --base-model z-image-turbo --steps 9 --guidance 0 \
  --prompt "A red fox in fresh snow at sunrise, photo" --width 1024 --height 1024 --seed 7 --output fox.png
```

`8bit/`, `6bit/` and `4bit/` quantize the transformer's and the text encoder's linear layers (MLX affine, group size
64); the VAE stays bf16. There is no fp16 folder: mflux computes in bf16 whatever the weights are.

**How they were checked.** The pipeline in mflux against diffusers' `ZImagePipeline` in PyTorch (bf16), started from
the *same* initial noise, 3 prompts at 512x512, 9 steps. Pass: LPIPS <= 0.15 on every prompt. For scale, two seeds
of the PyTorch pipeline are 12.9 dB / LPIPS 0.46 apart (a turbo model varies little between seeds).

| Precision | Size | PSNR vs PyTorch (mean) | LPIPS (mean / worst) | Status |
|---|---|---|---|---|
| `bf16/` | 20.5 GB | 22.1 dB | 0.118 / 0.147 | passes |
| `8bit/` | 11.0 GB | 21.0 dB | 0.141 / 0.201 | **below threshold, experimental**; the same picture by eye |
| `6bit/` | 8.5 GB | 20.2 dB | 0.164 / 0.227 | **below threshold, experimental**: details change |
| `4bit/` | 5.9 GB | 17.0 dB | 0.246 / 0.265 | **below threshold, experimental**: details change |

A 512x512 picture takes about 2.5 s (9 steps) on an Apple M5 with 24 GB, plus loading.

## How these were made

From [Z-Image-Turbo](https://huggingface.co/Tongyi-MAI/Z-Image-Turbo) at revision `f332072aa7`: the original weights loaded in MLX and stored as bf16 or fp16, or
quantized with MLX's affine quantization (`8bit`, `6bit`, `4bit`, group size 64; layers MLX can't quantize, such as
convolutions and norms, stay bf16). Every build was checked against the original before upload; the `sha256` column
above is what the files must hash to.

## License

Apache-2.0. These files are a derivative of the original model and carry its license: it is copied in this
repository, and it governs your use of these files. The original model card follows unchanged.

---

# Original model card

<h1 align="center">⚡️- Image<br><sub><sup>An Efficient Image Generation Foundation Model with Single-Stream Diffusion Transformer</sup></sub></h1>

<div align="center">

[![Official Site](https://img.shields.io/badge/Official%20Site-333399.svg?logo=homepage)](https://tongyi-mai.github.io/Z-Image-blog/)&#160;
[![GitHub](https://img.shields.io/badge/GitHub-Z--Image-181717?logo=github&logoColor=white)](https://github.com/Tongyi-MAI/Z-Image)&#160;
[![Hugging Face](https://img.shields.io/badge/%F0%9F%A4%97%20Checkpoint-Z--Image--Turbo-yellow)](https://huggingface.co/Tongyi-MAI/Z-Image-Turbo)&#160;
[![Hugging Face](https://img.shields.io/badge/%F0%9F%A4%97%20Online_Demo-Z--Image--Turbo-blue)](https://huggingface.co/spaces/Tongyi-MAI/Z-Image-Turbo)&#160;
[![Hugging Face](https://img.shields.io/badge/%F0%9F%A4%97%20Mobile_Demo-Z--Image--Turbo-red)](https://huggingface.co/spaces/akhaliq/Z-Image-Turbo)&#160;
[![ModelScope Model](https://img.shields.io/badge/🤖%20Checkpoint-Z--Image--Turbo-624aff)](https://www.modelscope.cn/models/Tongyi-MAI/Z-Image-Turbo)&#160;
[![ModelScope Space](https://img.shields.io/badge/🤖%20Online_Demo-Z--Image--Turbo-17c7a7)](https://www.modelscope.cn/aigc/imageGeneration?tab=advanced&versionId=469191&modelType=Checkpoint&sdVersion=Z_IMAGE_TURBO&modelUrl=modelscope%3A%2F%2FTongyi-MAI%2FZ-Image-Turbo%3Frevision%3Dmaster)&#160;
[![Art Gallery PDF](https://img.shields.io/badge/%F0%9F%96%BC%20Art_Gallery-PDF-ff69b4)](assets/Z-Image-Gallery.pdf)&#160;
[![Web Art Gallery](https://img.shields.io/badge/%F0%9F%8C%90%20Web_Art_Gallery-online-00bfff)](https://modelscope.cn/studios/Tongyi-MAI/Z-Image-Gallery/summary)&#160;
<a href="https://arxiv.org/abs/2511.22699" target="_blank"><img src="https://img.shields.io/badge/Report-b5212f.svg?logo=arxiv" height="21px"></a>


Welcome to the official repository for the Z-Image（造相）project!

</div>



## ✨ Z-Image

Z-Image is a powerful and highly efficient image generation model family with **6B** parameters. Currently there are four variants:

- 🚀 **Z-Image-Turbo** – A distilled version of Z-Image that matches or exceeds leading competitors with only **8 NFEs** (Number of Function Evaluations). It offers **⚡️sub-second inference latency⚡️** on enterprise-grade H800 GPUs and fits comfortably within **16G VRAM consumer devices**. It excels in photorealistic image generation, bilingual text rendering (English & Chinese), and robust instruction adherence.

- 🎨 **Z-Image** – The foundation model behind Z-Image-Turbo. Z-Image focuses on **high-quality generation**, **rich aesthetics**, **strong diversity**, and **controllability**, well-suited for creative generation, **fine-tuning**, and downstream development. It supports a wide range of artistic styles, effective negative prompting, and high diversity across identities, poses, compositions, and layouts.

- 🧱 **Z-Image-Omni-Base** – The versatile foundation model capable of both **generation and editing tasks**. By releasing this checkpoint, we aim to unlock the full potential for community-driven fine-tuning and custom development, providing the most "raw" and diverse starting point for the open-source community.

- ✍️ **Z-Image-Edit** – A variant fine-tuned on Z-Image specifically for image editing tasks. It supports creative image-to-image generation with impressive instruction-following capabilities, allowing for precise edits based on natural language prompts.

### 📥 Model Zoo

| Model | Pre-Training | SFT | RL | Step | CFG | Task | Visual Quality | Diversity | Fine-Tunability | Hugging Face | ModelScope |
| :--- | :---: | :---: | :---: | :---: | :---: | :---: | :---: | :---: | :---: | :---: | :---: |
| **Z-Image-Omni-Base** | ✅ | ❌ | ❌ | 50 | ✅ | Gen. / Editing | Medium | High | Easy | *To be released* | *To be released* |
| **Z-Image** | ✅ | ✅ | ❌ | 50 | ✅ | Gen. | High | Medium | Easy | [![Hugging Face](https://img.shields.io/badge/%F0%9F%A4%97%20Checkpoint%20-Z--Image-yellow)](https://huggingface.co/Tongyi-MAI/Z-Image) <br> [![Hugging Face Space](https://img.shields.io/badge/%F0%9F%A4%97%20Demo-Z--Image-blue)](https://huggingface.co/spaces/Tongyi-MAI/Z-Image) | [![ModelScope Model](https://img.shields.io/badge/🤖%20%20Checkpoint-Z--Image-624aff)](https://www.modelscope.cn/models/Tongyi-MAI/Z-Image) <br> [![ModelScope Space](https://img.shields.io/badge/%F0%9F%A4%96%20Demo-Z--Image-17c7a7)](https://www.modelscope.cn/aigc/imageGeneration?tab=advanced&versionId=569345&modelType=Checkpoint&sdVersion=Z_IMAGE&modelUrl=modelscope%3A%2F%2FTongyi-MAI%2FZ-Image%3Frevision%3Dmaster) |
| **Z-Image-Turbo** | ✅ | ✅ | ✅ | 8 | ❌ | Gen. | Very High | Low | N/A | [![Hugging Face](https://img.shields.io/badge/%F0%9F%A4%97%20Checkpoint%20-Z--Image--Turbo-yellow)](https://huggingface.co/Tongyi-MAI/Z-Image-Turbo) <br> [![Hugging Face Space](https://img.shields.io/badge/%F0%9F%A4%97%20Demo-Z--Image--Turbo-blue)](https://huggingface.co/spaces/Tongyi-MAI/Z-Image-Turbo) | [![ModelScope Model](https://img.shields.io/badge/🤖%20%20Checkpoint-Z--Image--Turbo-624aff)](https://www.modelscope.cn/models/Tongyi-MAI/Z-Image-Turbo) <br> [![ModelScope Space](https://img.shields.io/badge/%F0%9F%A4%96%20Demo-Z--Image--Turbo-17c7a7)](https://www.modelscope.cn/aigc/imageGeneration?tab=advanced&versionId=469191&modelType=Checkpoint&sdVersion=Z_IMAGE_TURBO&modelUrl=modelscope%3A%2F%2FTongyi-MAI%2FZ-Image-Turbo%3Frevision%3Dmaster) |
| **Z-Image-Edit** | ✅ | ✅ | ❌ | 50 | ✅ | Editing | High | Medium | Easy | *To be released* | *To be released* |                                                                                                                                                                                                                                                                                           | *To be released*                                                                                                                                                                                                                                                                                                                                                                                                                                                            |

### 🖼️ Showcase

📸 **Photorealistic Quality**: **Z-Image-Turbo** delivers strong photorealistic image generation while maintaining excellent aesthetic quality.

![Showcase of Z-Image on Photo-realistic image Generation](assets/showcase_realistic.png)

📖 **Accurate Bilingual Text Rendering**: **Z-Image-Turbo** excels at accurately rendering complex Chinese and English text.

![Showcase of Z-Image on Bilingual Text Rendering](assets/showcase_rendering.png)

💡  **Prompt Enhancing & Reasoning**: Prompt Enhancer empowers the model with reasoning capabilities, enabling it to transcend surface-level descriptions and tap into underlying world knowledge.

![reasoning.jpg](assets/reasoning.png)

🧠 **Creative Image Editing**: **Z-Image-Edit** shows a strong understanding of bilingual editing instructions, enabling imaginative and flexible image transformations.

![Showcase of Z-Image-Edit on Image Editing](assets/showcase_editing.png)

### 🏗️ Model Architecture
We adopt a **Scalable Single-Stream DiT** (S3-DiT) architecture. In this setup, text, visual semantic tokens, and image VAE tokens are concatenated at the sequence level to serve as a unified input stream, maximizing parameter efficiency compared to dual-stream approaches.

![Architecture of Z-Image and Z-Image-Edit](assets/architecture.webp)

### 📈 Performance
According to the Elo-based Human Preference Evaluation (on [*Alibaba AI Arena*](https://aiarena.alibaba-inc.com/corpora/arena/leaderboard?arenaType=T2I)), Z-Image-Turbo shows highly competitive performance against other leading models, while achieving state-of-the-art results among open-source models.

<p align="center">
  <a href="https://aiarena.alibaba-inc.com/corpora/arena/leaderboard?arenaType=T2I">
    <img src="assets/leaderboard.png" alt="Z-Image Elo Rating on AI Arena"/><br />
    <span style="font-size:1.05em; cursor:pointer; text-decoration:underline;"> Click to view the full leaderboard</span>
  </a>
</p>

### 🚀 Quick Start
Install the latest version of diffusers, use the following command:
<details>
  <summary><sup>Click here for details for why you need to install diffusers from source</sup></summary>

  We have submitted two pull requests ([#12703](https://github.com/huggingface/diffusers/pull/12703) and [#12715](https://github.com/huggingface/diffusers/pull/12715)) to the 🤗 diffusers repository to add support for Z-Image. Both PRs have been merged into the latest official diffusers release.
  Therefore, you need to install diffusers from source for the latest features and Z-Image support.

</details>

```bash
pip install git+https://github.com/huggingface/diffusers
```

```python
import torch
from diffusers import ZImagePipeline

# 1. Load the pipeline
# Use bfloat16 for optimal performance on supported GPUs
pipe = ZImagePipeline.from_pretrained(
    "Tongyi-MAI/Z-Image-Turbo",
    torch_dtype=torch.bfloat16,
    low_cpu_mem_usage=False,
)
pipe.to("cuda")

# [Optional] Attention Backend
# Diffusers uses SDPA by default. Switch to Flash Attention for better efficiency if supported:
# pipe.transformer.set_attention_backend("flash")    # Enable Flash-Attention-2
# pipe.transformer.set_attention_backend("_flash_3") # Enable Flash-Attention-3

# [Optional] Model Compilation
# Compiling the DiT model accelerates inference, but the first run will take longer to compile.
# pipe.transformer.compile()

# [Optional] CPU Offloading
# Enable CPU offloading for memory-constrained devices.
# pipe.enable_model_cpu_offload()

prompt = "Young Chinese woman in red Hanfu, intricate embroidery. Impeccable makeup, red floral forehead pattern. Elaborate high bun, golden phoenix headdress, red flowers, beads. Holds round folding fan with lady, trees, bird. Neon lightning-bolt lamp (⚡️), bright yellow glow, above extended left palm. Soft-lit outdoor night background, silhouetted tiered pagoda (西安大雁塔), blurred colorful distant lights."

# 2. Generate Image
image = pipe(
    prompt=prompt,
    height=1024,
    width=1024,
    num_inference_steps=9,  # This actually results in 8 DiT forwards
    guidance_scale=0.0,     # Guidance should be 0 for the Turbo models
    generator=torch.Generator("cuda").manual_seed(42),
).images[0]

image.save("example.png")
```

## 🔬 Decoupled-DMD: The Acceleration Magic Behind Z-Image

[![arXiv](https://img.shields.io/badge/arXiv-2511.22677-b31b1b.svg)](https://arxiv.org/abs/2511.22677)

Decoupled-DMD is the core few-step distillation algorithm that empowers the 8-step Z-Image model.

Our core insight in Decoupled-DMD  is that the success of existing DMD (Distributaion Matching Distillation) methods is the result of two independent, collaborating mechanisms:

-   **CFG Augmentation (CA)**: The primary **engine** 🚀 driving the distillation process, a factor largely overlooked in previous work.
-   **Distribution Matching (DM)**: Acts more as a **regularizer** ⚖️, ensuring the stability and quality of the generated output.

By recognizing and decoupling these two mechanisms, we were able to study and optimize them in isolation. This ultimately motivated us to develop an improved distillation process that significantly enhances the performance of few-step generation.

![Diagram of Decoupled-DMD](assets/decoupled-dmd.webp)

## 🤖 DMDR: Fusing DMD with Reinforcement Learning

[![arXiv](https://img.shields.io/badge/arXiv-2511.13649-b31b1b.svg)](https://arxiv.org/abs/2511.13649)

Building upon the strong foundation of Decoupled-DMD, our 8-step Z-Image model has already demonstrated exceptional capabilities. To achieve further improvements in terms of semantic alignment, aesthetic quality, and structural coherence—while producing images with richer high-frequency details—we present **DMDR**.

Our core insight behind DMDR is that Reinforcement Learning (RL) and Distribution Matching Distillation (DMD) can be synergistically integrated during the post-training of few-step models. We demonstrate that:

-   **RL Unlocks the Performance of DMD** 🚀
-   **DMD Effectively Regularizes RL** ⚖️

![Diagram of DMDR](assets/DMDR.webp)

## ⏬ Download
```bash
pip install -U huggingface_hub
HF_XET_HIGH_PERFORMANCE=1 hf download Tongyi-MAI/Z-Image-Turbo
```

## 📜 Citation

If you find our work useful in your research, please consider citing:

```bibtex
@article{team2025zimage,
  title={Z-Image: An Efficient Image Generation Foundation Model with Single-Stream Diffusion Transformer},
  author={Z-Image Team},
  journal={arXiv preprint arXiv:2511.22699},
  year={2025}
}

@article{liu2025decoupled,
  title={Decoupled DMD: CFG Augmentation as the Spear, Distribution Matching as the Shield},
  author={Dongyang Liu and Peng Gao and David Liu and Ruoyi Du and Zhen Li and Qilong Wu and Xin Jin and Sihan Cao and Shifeng Zhang and Hongsheng Li and Steven Hoi},
  journal={arXiv preprint arXiv:2511.22677},
  year={2025}
}

@article{jiang2025distribution,
  title={Distribution Matching Distillation Meets Reinforcement Learning},
  author={Jiang, Dengyang and Liu, Dongyang and Wang, Zanyi and Wu, Qilong and Jin, Xin and Liu, David and Li, Zhen and Wang, Mengmeng and Gao, Peng and Yang, Harry},
  journal={arXiv preprint arXiv:2511.13649},
  year={2025}
}
```