中文 / English bilingual README
- 知乎文章 / Zhihu: https://zhuanlan.zhihu.com/p/2027097934508880925
这是一个把 Zimage 封装成网页应用的本地项目。
目标很直接：让用户下载项目后，就能在本地浏览器里直接运行 Zimage，不需要先学习复杂的 ComfyUI 节点工作流，也不需要自己拼装一整套推理界面。
这个项目适合：
- 想在 Mac 上本地跑 Zimage
- 想直接输入提示词并出图
- 想调尺寸、比例、分辨率、步数、种子等参数
- 想保留任务队列、历史记录、预览和下载能力
- 想在本地做边界更宽、偏成熟内容的私有探索, 没有审查，可以在本地生成色色内容。具体可以去 output 目录看看
- 不想折腾 ComfyUI 的用户
This project turns Zimage into a local WebUI for macOS.
The goal is simple: download the repository, install dependencies, start the local server, and generate images in your browser without building complex ComfyUI workflows.
This project is for users who want:
- a local Zimage experience on Mac
- direct prompt-to-image generation in a browser
- adjustable size, aspect ratio, resolution, steps, seed, and guidance
- task queue, history, preview, and download support
- more permissive private experimentation for mature visual concepts
- a lighter workflow than ComfyUI
git clone https://github.com/leigegehaha/zimage-webui.git
cd zimage-webui
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
chmod +x start-webapp.sh
./start-webapp.sh浏览器打开：
http://127.0.0.1:8765
git clone https://github.com/leigegehaha/zimage-webui.git
cd zimage-webui
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
chmod +x start-webapp.sh
./start-webapp.shOpen:
http://127.0.0.1:8765
- 本地优先 / Local first 下载代码后即可本地运行，不依赖远程网页平台。
- 不需要 ComfyUI / No ComfyUI required 直接网页交互，不需要节点编排。
- 模型不进仓库 / Model files are not committed
首次运行自动下载，或通过
download-model.sh一键预下载。 - 产品化交互 / Productized UX 任务队列、进度条、历史记录、图片预览、下载、高级参数抽屉。
- 更自由的本地探索 / More permissive local exploration
更适合私有、成熟内容方向的本地创作与实验，生成样例可查看
output/。 - 可扩展 / Extensible
自带
skill/目录，可继续接入更大的自动化流程。
Zimage 是一个先进的图像生成模型，适合本地文生图场景。当前项目基于 mflux 生态下的 z-image-turbo 变体进行封装，可以在 Apple Silicon 的本地环境中直接运行。
它的几个关键特征：
- 本地运行
- 出图速度较友好
- 适合配合 Prompt 和风格模板快速创作
- 内容限制相对更少，探索空间更大
- 更适合做私有环境下的成熟内容实验
需要说明的是，这个项目是本地工具，不内置线上平台那类强审核链路，因此在成熟内容方向上的边界通常会更宽。你可以直接查看本地 output/ 目录里的生成样例。这里不展开描述具体内容，但请确保你的使用符合所在地法律法规与平台要求。
Zimage is an advanced image generation model suited for local text-to-image workflows. This project currently wraps the z-image-turbo variant from the mflux ecosystem and runs locally on Apple Silicon.
Key characteristics:
- local execution
- relatively fast iteration
- prompt and style-template friendly
- fewer built-in restrictions compared to many hosted services
- better suited for private mature-content experimentation
This repository is a local tool, not a hosted platform with a heavy moderation pipeline. As a result, the boundary for mature content exploration is typically wider in private local use. You can review example outputs in the local output/ directory. Make sure your usage complies with local laws and platform requirements.
- 提示词输入 / Prompt input
- 风格模板输入与复用 / Style templates and reuse
- 自定义宽高 / Custom width and height
- 比例选择 / Aspect ratio selection
- 分辨率选择：
1080p/2K/4K - 批量生成 / Multi-image generation
- 非阻塞任务队列 / Non-blocking task queue
- 进度条与耗时统计 / Progress bar and elapsed time
- 历史记录 / History with generation parameters
- 图片预览和下载 / Preview and download
- 取消任务 / Cancel task
stepsseedguidancegaussian
- 单页应用 / Single-page app
- 像素风、高饱和界面 / Pixel-style, saturated UI
- 瀑布流结果布局 / Waterfall-style result stream
- 中英切换 / Chinese-English toggle
- 状态颜色区分 / Status-based color tags
项目内置 skill/ 目录，可作为独立 skill 使用：
- 按提示词生成图片
- 如果用户未指定比例，要求先问比例
- 默认
1080p - 高级参数在
skill/skim/config.json - 输出到
skill/output/
zimage/
├── app/
│ └── server.py
├── web/
│ ├── index.html
│ ├── styles.css
│ └── app.js
├── skill/
│ ├── SKILL.md
│ ├── skim/
│ │ └── config.json
│ ├── scripts/
│ │ └── generate.py
│ └── output/
├── assets/
│ └── screenshots/
├── output/
├── download-model.sh
├── run-zimage.sh
├── start-webapp.sh
├── requirements.txt
└── README.md
- macOS
- Apple Silicon
- Python 3.11+
mfluxcarsenk/z-image-turbo-mflux-8bit
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txtchmod +x start-webapp.sh
./start-webapp.shchmod +x run-zimage.sh
./run-zimage.sh --prompt "一只橘猫坐在木桌上，窗边自然光，写实风格"仓库不上传模型文件本体，只上传代码。
The repository does not contain model weights. It only contains code.
首次生成时，底层会自动把模型下载到：
hf-cache/
chmod +x download-model.sh
./download-model.sh脚本验证通过后，会把模型缓存到本地 hf-cache/。
编辑配置：
skill/skim/config.json
调用脚本：
python3 skill/scripts/generate.py \
--prompt "测试图片，像素风格小机器人，霓虹背景，高饱和度" \
--aspect-ratio 1:1如果你要给客户发“可下载版本”，建议使用 GitHub Releases，而不是直接把模型缓存和本地输出一起提交进仓库。
建议规则：
- 不要把
.venv/、hf-cache/、output/、skill/output/打进 release - release 只包含源码、启动脚本、README、skill、前端和后端代码
- 模型通过首次运行自动下载，或客户手动执行
download-model.sh
推荐流程：
git tag v0.1.0
git push origin v0.1.0然后在 GitHub Releases 页面发布一个新版本，并在 Release Notes 中说明：
- 支持的系统
- 首次运行会自动下载模型
- 如需提前下载可运行
download-model.sh - 模型文件不包含在 release 包内
For customer-facing downloadable builds, use GitHub Releases instead of committing model caches or local outputs.
Recommended rules:
- do not ship
.venv/,hf-cache/,output/, orskill/output/ - releases should include source code, scripts, README, skill files, frontend, and backend
- model weights should be downloaded on first run or pre-downloaded with
download-model.sh
Recommended flow:
git tag v0.1.0
git push origin v0.1.0Then publish a GitHub Release and mention:
- supported system requirements
- first run downloads the model automatically
download-model.shis available for prefetching- model weights are not included in the release bundle
1080p是目标分辨率档位，不一定严格等于最终像素- 底层模型可能把宽高自动调整为
16的倍数 - 例如
1080x1080可能最终落盘为1072x1072 - 首次出图会较慢，因为需要下载模型
hf-cache/体积会比较大，不建议提交到 Git
MIT. See LICENSE.
