一、项目简介
Image Studio 是一款开源的 AI 图像生成 / 编辑桌面客户端，面向所有 OpenAI 兼容的图像上游接口（官方 API、中转站、自建网关均可接入）。与一般的套壳客户端不同，它把主要精力放在解决一个实际痛点上：长时间图像推理在 Cloudflare / Nginx 等网关后面容易遭遇 524 / 504 断连超时。
项目地址：https://github.com/RoseKhlifa/Image-Studio
许可证：GNU AGPL v3.0
技术栈：Wails（Go + React/TypeScript）桌面端 + Android WebView 壳层
1.1 核心亮点
1.2 与同类工具的差异
许多图像客户端只是简单封装一次性 JSON 请求，一旦上游推理超过 100 秒，Cloudflare 等网关就会直接掐断连接，用户只能看到"生成失败"。Image Studio 的设计思路是：
优先走 SSE 流式传输——事件流持续到达，连接始终保持活跃；
请求策略可选——
OpenAI 标准只发官方字段，兼容中转扩展额外附带 seed / negative_prompt 等中转站常见字段；排错链路透明——每次请求的 raw 响应（SSE dump 或 JSON）都会落盘，历史详情中可直接查看真实 HTTP 状态码与上游报错，而不是只看一个模糊的 toast 提示。
此外，项目还有配套的提示词网站 Image-Prompts，支持把网页上的提示词一键导入桌面端。
1.3 注意事项
项目 不内置任何上游服务，首次启动必须自行填写 BASE_URL、API Key、文本模型 ID 与图像模型 ID，即所谓"BYOK"（Bring Your Own Key）模式。
当前 没有独立部署的在线 Web 版，仓库中的浏览器预览仅用于前端调试，不能当作 SaaS 使用。
项目采用 AGPL v3.0 许可证：基于本项目修改后再分发，或将修改版作为网络服务提供给他人使用，均需以同一许可证公开源码。
二、下载与安装
2.1 下载渠道
下载速度慢可选择下面链接：
⚠️ Windows 用户注意：CI 构建的
exe未经过 Authenticode 签名，在 Windows 11 上可能被 Smart App Control / SmartScreen 拦截，提示"无法确认其编写人"。对外分发或日常使用请优先选择正式 Release。
三、首次配置（关键步骤）
首次启动应用会自动打开「上游配置」窗口（之后也可从设置中重新打开）。需要填写以下 5 项：
填写完成后，务必先点一次「测试连接」，确认当前 profile 能真正走通再保存。应用不会向除你配置的 BASE_URL 以外的任何生成服务发送请求。
3.1 API 形态怎么选
Responses API（推荐，抗超时）
调用
/v1/responses，通过模型内置的image_generation工具触发图像生成，SSE 流式接收事件。适合：图像推理容易超过 100 秒；上游位于 Cloudflare / Nginx 后面经常 524/504；你的 Key 拥有文本模型权限。
特性：SSE 保活、3 次自动重试、15 秒 backoff、部分图像结果兜底保存。
Images API（最大兼容性）
调用标准接口：文生图走
/v1/images/generations，图生图走/v1/images/edits（multipart 上传）。适合：上游不支持 Responses API；Key 只绑定了 image 分组；只需要最大兼容性。
限制：一次性 JSON 响应，没有 SSE 保活，长推理在 Cloudflare 后面仍有 524/504 风险；多参考图、seed、negative prompt 是否生效取决于上游的兼容实现。
3.2 参数策略
在上游 profile 中还可选择请求策略：
四、详细使用教程
4.1 文生图
在模式切换区选择「文生图」。
在输入框中填写 prompt（提示词）。支持 prompt 历史调用、内置模板，以及一键 AI 优化 prompt。
设置参数：
比例：内置常用宽高比；不够用时可打开「自定义比例」弹窗，新增并持久化保存常用比例，新比例会立即出现在参数按钮区，并按当前 1K / 2K / 4K 档位自动换算尺寸；
质量：Auto / high / medium / low；
输出格式：PNG / JPEG / WebP；
风格：通过风格 chip 选择。
注：比例与分辨率是同一个
size字段的拆分视图；比例切到Auto时，尺寸将整体交给上游决定，无法单独锁定。
（可选）设置 seed 或 negative prompt——需确认当前 profile 使用「兼容中转扩展」策略且上游真正支持。
点击「生成」，或使用快捷键
Cmd+Enter（macOS）/Ctrl+Enter（Windows / Linux）。生成成功后，toast 会提供查看详情入口；详情抽屉中可查看图片预览、全部参数、原始 prompt、优化后 prompt、保存路径与 raw 响应路径。
4.2 图生图
添加源图，支持四种方式：
点击「添加图片」打开文件对话框；
直接拖拽本地图片到窗口；
Cmd/Ctrl+V粘贴剪贴板图片；在历史记录中双击某条历史直接设为源图。
切换到「图生图」模式。
输入修改要求（prompt）。
（可选）如需蒙版：在画板中切换到蒙版工具，用画笔涂抹需要修改的区域（支持画笔/橡皮、大小滑块、实时半透明叠加）。
点击「生成」。
提示：标准 OpenAI Images Edits 通常只接受单张
image；多参考图中第二张及之后通过兼容字段发送，是否生效取决于上游实现。
4.3 图生图批处理
桌面端支持按目录批量处理图片，适合"大量源图共用同一组 prompt 与参数"的场景：
切到「图生图」模式。
在「源图片 / 参考图」区域顶部，从
普通图生图切换到批处理。选择输入目录，确认扫描到的图片数量。
选择输出位置：默认保存回原目录，也可单独指定输出目录。
设置并发数。
点击「编辑」开始批量处理。
4.4 画板功能
画板基于 Konva 画布，是图生图与图片编辑的核心工作区：
视图操作：缩放、拖动、双击在 fit 与 100% 之间切换；
F重置视图；按住Space临时切换到拖动。蒙版：画笔、橡皮、笔刷大小滑块（
[/]减/加 5），实时半透明叠加预览。标注：矩形、箭头、自由画笔、文字、颜色选择、选中后
Delete删除。图像变换：旋转、翻转、裁剪为就地编辑，不会创建新的生成历史条目。macOS 端优先走 Core Image / Metal 加速，其他平台走 WebGL / canvas 路径，不可用时回退 CPU。
历史对比：
Shift + 点击历史项进入左右分屏对比，可拖动分割条。撤销 / 重做：覆盖蒙版笔触、标注、清空等画板操作。
4.5 历史记录与数据管理
历史元数据保存在本地 IndexedDB，支持按 prompt 搜索、按模式筛选、按日期筛选。
历史项右键菜单功能丰富：复制 prompt、复制本地路径、查看 raw 响应、设为源图、用作对比、以此参数重新生成、应用参数但不生成。
支持将历史 导出为 JSON 并重新导入，便于跨设备迁移。
生成图片默认落在输出目录的
images/子目录；原始响应与排错日志落在log/子目录，避免图片目录被日志污染。
4.6 多 Workspace
应用支持多 workspace 标签页，每个 workspace 独立保存 prompt、参数、源图、当前图与运行状态，互不干扰：
macOS：
Cmd+N新建 /Cmd+W关闭；Windows / Linux：
Ctrl+N新建 /Ctrl+W关闭。
常用快捷键速查
五、数据存储位置与故障排查
5.1 数据存储位置
桌面端默认输出目录：
5.2 常见问题排查
遇到"生成失败 / 保存失败 / 模型不可用"时，先别急着判定是软件 bug——多数情况是上游配置、Key 权限、网关超时或兼容实现差异导致的。建议按以下顺序自查：
在当前 profile 里点一次「测试连接」，确认 BASE_URL、API Key、文本模型 ID、图像模型 ID 真实可用；
确认选对了 API 形态（Responses API 要求上游真正实现
/v1/responses与 SSE，且 Key 有文本模型权限）；打开历史详情或 raw 响应，查看真实 HTTP 状态码与上游报错，不要只看页面 toast；
用同样的
BASE_URL + Key + 模型 ID在 curl / Postman / 上游自带调试页中验证，如果同样失败，优先联系上游服务商。
典型问题速查：
查看 raw 响应的方法：历史项右键 → 查看 raw 响应。Responses API 通常是 sse-response-*.txt，Images API 通常是 images-response-*.json。排查时优先看 HTTP status、错误 message、是否出现 retryable=true / 524 / 504 / 5xx，以及是否有 partial_image_b64 或 final image 事件。
六、总结
Image Studio 的定位非常明确：它不是一个"开箱即用"的图像生成服务，而是一个 专业、透明、抗造的 OpenAI 兼容图像上游客户端。它的核心价值在于：
用 SSE 流式保活正面解决 524/504 超时这一行业通病，并提供 WebSocket mode 与自动重试兜底；
双 API 形态 + 双参数策略，把兼容性选择权交给用户，适配从官方直连到各种中转站的不同上游；
数据完全本地化，Key 进系统安全存储，raw 响应全量落盘，排错链路透明可查；
功能完整度高：文生图、图生图、蒙版、批处理、画板标注、历史对比、多 workspace、全平台覆盖，日常出图工作流可以完全闭环。
如果你正在使用 OpenAI 兼容的图像生成 API（尤其是通过中转站、且深受长推理断连困扰），Image Studio 值得一试。项目以 AGPL v3.0 开源，欢迎到 GitHub 仓库 点个 Star 或参与贡献。
本文基于 Image Studio 官方 README 及 docs 文档整理撰写，内容以项目仓库最新文档为准。