# Zimage

> Generate images locally on Apple Silicon — free, offline, zero cloud credits. Z-Image-Turbo (4-bit, via mflux) for text-to-image and image-to-image; SeedVR2 for upscaling ANY image (2x / 4K, batch OK). Image generation defaults to this LOCAL skill; video, or an explicit ask for dreamina/cloud, goes to dreamina instead. Use when the user says "生成图片/出一张图/画一张图/本地生图", "generate/make/draw an image", "图生图/照着这张图改一张", "放大这张图/高清化/超分/upscale this image", "4K 壁纸", or mentions zimage / Z-Image / SeedVR2.

- Skill: `sunfmin/zimage` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add sunfmin/zimage`
- Raw SKILL.md: https://api.skillmd.com/api/skills/sunfmin/zimage/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: DevOps & Infra
- Author: sunfmin (https://skillmd.com/u/sunfmin)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/sunfmin/zimage

---


# zimage — local image generation & upscaling

Everything runs locally via mflux (MLX). No credits, no network once weights are cached.
Canonical terms (see CONTEXT.md): **Generate 文生图**, **Refine 图生图**, **Upscale 放大**.

## Boundary with dreamina

- **Images → zimage (this skill), always the default.** Free and local.
- **Video → dreamina.** zimage does not do video.
- Cloud image generation only when the user explicitly names dreamina/cloud.

## Requirements

- mflux ≥ 0.18 as a uv tool (`mflux-generate-z-image-turbo` and `mflux-upscale-seedvr2` on PATH). Missing → `uv tool install mflux`.
- Weights auto-download to the HF cache on first run: `filipstrand/Z-Image-Turbo-mflux-4bit` (~5.5 GB) + `numz/SeedVR2_comfyUI` (~6.8 GB). No ComfyUI involved — see `docs/adr/0001-mflux-native-not-comfyui.md`.

## Output convention

- Default dir: `~/Pictures/zimage/` (`mkdir -p` first). A user-specified destination always wins.
- Filename: `<YYYYMMDD-HHMMSS>-<short-english-slug>-seed{seed}.png`. Keep the literal `{seed}` in `--output` — mflux substitutes the real seed, and multi-seed runs don't overwrite each other.
- Upscales: next to the source image, suffixed `-2x.png` / `-4k.png`.
- `--metadata` writes `<name>.metadata.json` beside the PNG — always pass it (reproducibility).

## Generate（文生图）

```sh
mkdir -p ~/Pictures/zimage
mflux-generate-z-image-turbo \
  --model filipstrand/Z-Image-Turbo-mflux-4bit \
  --prompt "<prompt — English strongest, Chinese works too>" \
  --steps 8 \
  --width 1024 --height 1024 \
  --metadata \
  --output "$HOME/Pictures/zimage/<ts>-<slug>-seed{seed}.png"
```

- **Always pass `--steps 8`.** mflux's generic default is 25 steps — 3× slower with no visible quality gain on this distilled turbo model (verified same-seed). Never pass `--guidance` (turbo needs none). Only deviate when the user explicitly asks.
- Sizes (multiples of 16): default 1024×1024; 横屏/壁纸/landscape → 1344×768; 竖屏/手机/portrait → 768×1344; explicit dimensions win.
- 多出几张挑一挑 → add `--auto-seeds N` (keep `{seed}` in the output name).
- Exclusions → `--negative-prompt "..."`.

## Refine（图生图）

Generate command + reference image:

```sh
  --image-path <reference.png> --image-strength 0.4
```

`--image-strength` 0.0–1.0: higher = closer to the reference (0.4 default; 0.6–0.8 for "keep the composition, change the style").

## Upscale（放大）— any image, not just zimage output

```sh
mflux-upscale-seedvr2 \
  --image-path <img.png> \
  --resolution 2x \
  --output "<src-stem>-2x.png"
```

- Default `2x`. 「4K/壁纸/wallpaper」→ `--resolution 2160` (shortest edge, px). `--softness` stays 0 unless asked.
- Batch a whole directory: `--image-path <dir>` with `--output "<dir>/{image_name}-2x.png"` (`{image_name}` = each source stem).

## Delivery — after every generation/upscale

1. `open <file>` so the user sees it immediately.
2. Report: file path, seed, and elapsed time.
3. Exact re-run with tweaks: `--config-from-metadata <file>.metadata.json` re-uses saved params; any flag you pass on top overrides it (e.g. same everything, new prompt).

## Expected timings — don't kill the process early

Measured on M4 Pro / 48 GB, 1024×1024 (progress bar streams on stderr):

| Operation | Time |
| --- | --- |
| Generate, 8 steps | ~2 min (~15 s/step + model load) |
| Upscale 2x → 2048px | ~1.5 min (~20 s inference + model load) |
| Peak RAM | ~11 GB either way — no `--low-ram` needed at 48 GB |

Give Bash calls a 10-minute timeout. First-ever run adds weight download time (~12 GB total).