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（文生图）

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:

  --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

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):

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