imgcli —— 基于 OpenAI gpt-image-2 的命令行图片生成工具

作者：Mad甘 一条命令把脑子里的画面变成 PNG，专治「想画一张图却懒得开网页」综合症。

📖 第一次用？看完整使用教程：TUTORIAL.md（从零到出图，含提示词写作技巧 + 排错指南）

✨ 特性

• 极简 CLI：gen "你的提示词" 一行搞定（原始命令 python -m imgcli generate 同次可用）
• GUI 配置中心：跑 Mad-Setting 弹出 Tk 窗口填 Key 和 Base URL，点保存自动开 CLI 终端，告别记事本编辑 .env
• 中转友好：默认走 OPENAI_BASE_URL 中转，国内开箱即用；可用 --no-stream 或删 OPENAI_BASE_URL 切回官方
• 流式默认开启：默认 --stream --partial-images 3，自动绕过部分中转 nginx 60s 超时；拿到 partial 即视为成功产出
• 官方 SDK：基于 openai>=1.50，支持 gpt-image-2 / gpt-image-1.5 / gpt-image-1 / gpt-image-1-mini
• 参数齐全：尺寸、质量、输出格式、背景透明度、压缩等级、审核级别全暴露
• 批量生成：-n 4 一次出 4 张（仅非流式），自动按时间戳 + 序号命名永不重名
• 稳定容错：4xx / 网络异常 / 流式中断都给针对性提示，零生亲打栈
• 配置安全：API Key 走 .env，已加入 .gitignore，绝不会被你手滑提交；启动日志自动脱敏
• dry-run 模式：调参前先预览将发送的参数，避免瞎花钱
• 零强依赖：仅 openai + python-dotenv，标准库 argparse 解析命令

� 安装方式

方式一：npm 全局安装（推荐，一行搞定）

前置条件：Node.js >= 14、Python >= 3.10

npm install -g mad-imgcli

安装过程会自动：

1. 在包目录创建 Python 虚拟环境（.venv）
2. 安装 openai、python-dotenv 等 Python 依赖

安装完成后，任意终端、任意目录可用：

# ① 首次使用：一键打开 GUI 配置 API Key / Base URL
imgcli setup

# ② 配置完成后直接出图
imgcli generate "一只穿着宇航服的橘猫"

# ③ 查看帮助
imgcli --help

首次使用流程：imgcli setup → GUI 填写 API Key → 点击「🚀 保存并打开 CLI」→ 自动弹出已配好的终端 → 直接 imgcli generate "提示词" 出图。

方式二：本地开发安装（克隆仓库）

git clone https://github.com/madgan/imgcli.git
cd imgcli
python -m venv .venv
.venv\Scripts\Activate.ps1     # Windows PowerShell
pip install -r requirements.txt

本地安装可额外使用 .ps1 / .cmd 快捷脚本（gen.ps1、first.ps1、probe.ps1 等）。

�� 项目结构

Image_gpt_image2/
├── README.md                # 本文档
├── package.json             # npm 包配置（npm install -g mad-imgcli）
├── requirements.txt         # Python 依赖列表
├── .env.example             # 环境变量模板
├── .gitignore
├── .npmignore               # npm 发布排除清单
├── bin/                     # npm 全局命令入口（Node.js wrapper）
│   ├── imgcli.js            #   imgcli → python -m imgcli
│   └── imgcli-gui.js        #   imgcli-gui → python imgcli/gui.py
├── scripts/
│   └── postinstall.js       # npm postinstall：自动建 venv + 装依赖
├── Mad-Setting.cmd          # GUI 全局命令入口（CMD，本地开发用）
├── Mad-Setting.ps1          # GUI 全局命令入口（PowerShell，本地开发用）
├── gen.cmd                  # 出图快捷（CMD） = python -m imgcli generate
├── gen.ps1                  # 出图快捷（PowerShell）
├── first.cmd / first.ps1    # 首测快捷 = python examples\first_test.py
├── probe.cmd / probe.ps1    # 中转哨兵快捷 = python examples\probe_relay.py
├── imgcli/                  # CLI 主包
│   ├── __init__.py
│   ├── __main__.py          # python -m imgcli 入口
│   ├── banner.py            # ANSI 彩色启动横幅
│   ├── cli.py               # 命令行解析与编排
│   ├── client.py            # OpenAI Images API 封装（含重试）
│   ├── config.py            # 配置加载与参数白名单
│   ├── gui.py               # Mad Setting GUI 配置中心（tkinter）
│   └── io.py                # 文件命名与落盘
├── examples/
│   ├── prompts/
│   │   └── cli_developer_scene.txt   # 首测提示词
│   ├── first_test.py                  # 一键跑首测
│   └── probe_relay.py                 # 中转 upstream_error 恢复哨兵（周期探针 + 响铃）
└── outputs/                 # 生成图片输出目录

⚡ 最快路径：GUI 一键配置（推荐新手）

装好依赖后，直接在项目根目录跑：

.\Mad-Setting.cmd

或在 PowerShell 里：

.\Mad-Setting.ps1

会弹出一个暗色主题 GUI：

• 填 API Key + Base URL（带「显示/隐藏」开关，预设按钮一键填中转/官方）
• 🔍 测试连接 按钮直接调 /v1/models 验证可达性（不耗图像生成额度）
• 💾 仅保存 仅写入 .env
• 🚀 保存并打开 CLI 写完 .env + 自动弹一个新的 PowerShell 窗口（已 cd + 激活 venv），即开即用

配 PATH 后还能在任意目录输入 Mad-Setting 直接调起，详细步骤见 TUTORIAL.md §2.5。

⚡ 出图也有一行命令：gen "提示词"

记不住 python -m imgcli generate "..."？本项目提供同款快捷：

# 项目根目录下直接用
.\gen.ps1 "一只穿着宇航服的橘猫漂浮在木星轨道上"

# 所有原参数都还能用
.\gen.ps1 "..." --size 1536x1024 --quality high
.\gen.ps1 "..." --no-stream -n 4 --prefix candidate
.\gen.ps1 "..." --dry-run -v

等价于 python -m imgcli generate "..."，全部参数透传、退出码透传。配 PATH 后任意目录都能跳：

cd D:\AnyWhere
gen "一只哥特黑猫站在月光下"

PATH 配置方法跳转 TUTORIAL.md §2.5.3（与 Mad-Setting 共用同一个项目 PATH 入口，加一次两个命令都能用）。

🚀 快速开始（CLI 手动配置路线）

1. 准备环境（推荐 Python 3.10+）

# Windows PowerShell
python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -r requirements.txt

# Linux / macOS
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

2. 配置 .env（中转 / 官方二选一）

Copy-Item .env.example .env
# 用记事本 / VSCode 打开 .env

方式 A：使用中转 API（推荐，国内可直连）

在 .env 中填两个值：

OPENAI_API_KEY=中转商发给你的 Key
OPENAI_BASE_URL=https://你的中转域名/v1

要求：

• 中转 API 必须完全兼容 OpenAI Images 接口（即提供 /v1/images/generations 端点）
• BASE_URL 一般以 /v1 结尾，不要带末尾斜杠
• 中转商需支持 gpt-image-1 模型（少数老中转只支持 chat，不支持图像）

启动时控制台会打出（Key 自动脱敏）：

[INFO] imgcli.client: OpenAI 客户端初始化完成 | 类型=中转 | endpoint=https://你的中转域名/v1 | api_key=sk-x******abcd

方式 B：使用 OpenAI 官方

把 .env 里的 OPENAI_BASE_URL 注释掉或删除，仅保留：

OPENAI_API_KEY=sk-从 platform.openai.com 申请的 Key

官方账号还得在「Settings → Organization → Verification」通过组织认证才能用 GPT image 模型。

启动时控制台会打出：

[INFO] imgcli.client: OpenAI 客户端初始化完成 | 类型=OpenAI 官方 | endpoint=https://api.openai.com/v1 | api_key=sk-x******abcd

3. 一键跑首测（用项目自带的「CLI 开发者场景」提示词）

.\first.ps1   # 等价于 python examples\first_test.py，参数与退出码透传

跑完去 outputs/ 文件夹看图，文件名形如： first_test_20260425_181023_01.png

🛠️ CLI 用法

基本调用（默认走 stream + partial_images=3，中转环境最稳）

gen "一只穿着宇航服的橘猫漂浮在木星轨道上，写实风格" --size 1536x1024 --quality high

走官方账号 / 不需超时保护 → 切回一次性返回

gen "..." --no-stream

从文件读取长 prompt

gen --prompt-file examples\prompts\cli_developer_scene.txt --size 1536x1024 -n 2

一次出 4 张并指定输出目录

gen "赛博朋克的雨夜东京街头，霓虹倒映在湿漉漉的地砖上" -n 4 --out outputs\cyberpunk --prefix tokyo

透明背景 PNG（适合做素材）

gen "一颗发光的等离子球，孤立物体" --background transparent --output-format png

Dry-run：先看参数再决定要不要花钱

gen "test" --dry-run -v

查看完整帮助

gen --help

📋 全部 CLI 参数

| 参数 | 默认值 | 说明 | | --- | --- | --- | | prompt (位置参数) | — | 提示词文本（与 --prompt-file 二选一） | | --prompt-file PATH | — | 从 UTF-8 文本文件读 prompt | | --model | gpt-image-2 | 模型名（支持 gpt-image-2 / gpt-image-1.5 / gpt-image-1 / gpt-image-1-mini / dall-e-3 / dall-e-2） | | --size | 1024x1024 | 图像尺寸（1024x1024 / 1536x1024 / 1024x1536 / auto 等） | | --quality | high | 质量等级（low / medium / high / auto） | | --output-format | png | 输出格式（png / jpeg / webp） | | --output-compression | — | 压缩等级 0~100（仅 jpeg/webp 生效） | | --background | auto | 背景（auto / opaque / transparent） | | --moderation | auto | 审核级别（auto / low） | | -n / --num | 1 | 生成数量 1~10（流式模式下仅支持 1） | | --stream / --no-stream | 默认开启 | 流式生成，用于绕过中转 nginx 60s 超时 | | --partial-images | 3 | 流式下推送的中间预览图数量（0~3） | | --out | outputs | 输出目录 | | --prefix | img | 文件名前缀 | | --dry-run | — | 只打印参数不实际调用 API | | -v / --verbose | — | 输出 DEBUG 日志 |

🪦 踩坑记录：sub2.kalin.asia 中转实测

实测证明中转 sub2.kalin.asia 调调不可避免地踩了几个坊，以下全部记录下来供后人参考。

1. 该中转仅上架 gpt-image-2，不支持 gpt-image-1

调 /v1/models 只返回 5 个模型：

gpt-5.3-codex
gpt-5.4
gpt-5.4-mini
gpt-5.5
gpt-image-2

用 gpt-image-1 会报 503 No available compatible accounts。本项目默认 model 已切为 gpt-image-2。

2. 中转 nginx proxy_read_timeout 仅 60s

gpt-image-2 生成一张 1024×1024 高质量图通常 60-120s。一次性请求会被 nginx 报 504 Gateway Time-out：

HTTP/1.1 504 Gateway Time-out
Server: nginx/1.29.8

对策：默认启用 --stream --partial-images 3，OpenAI 在生成过程中推送 partial_image，nginx 持续看到数据流不会超时。

3. partial 之间间隔仍可能 > 60s

实测 gpt-image-2 在 quality=low 和 quality=high 下都只推 1 张 partial（OpenAI 自决定，partial_images=3 是上限不是下限），第 1 张 partial 后约 59s 触发 nginx 间隔超时，报：

httpx.RemoteProtocolError: peer closed connection without sending complete message body

对策：CLI 默认接受 partial 作为成功产出（退出码 0），即流被中途切断也不会被记为失败。partial 是接近完成态的 1024×1024 PNG（实测 1.4MB），多数情况下肉眼看不出与 completed 的差异。

如果你必须 100% 拿到 completed：

• 联系中转商调高 proxy_read_timeout 到 180s+
• 换支持长连接的中转
• 用 OpenAI 官方账号 + --no-stream

🔔 中转挂了怎么办：probe_relay.py 哨兵

如果你撞上中转报了 upstream_error 或 HTTP 502 后，不想手动反复跑 generate 命令守着看，跑个哨兵脚本挂后台就行了：

.\probe.ps1   # 等价于 python examples\probe_relay.py，参数与退出码透传

默认每 90s 打一下最便宜的探针（quality=low + prompt=ping），最多 60 次（约 90 分钟）。中转上游一恢复，脚本会：

• 响 5 声 880Hz 铃（Windows 走 winsound）
• 打印「中转已恢复」起提示 + 建议你重跑的 generate 命令
• 退出码 0

常用参数：

# 探针间隔 60s，最多 30 次（约 30 分钟）
.\probe.ps1 --interval 60 --max-attempts 30

# 看 DEBUG 详细每次请求响应
.\probe.ps1 -v

成本：探针会真实打到 generate 端点，但：

• 中转上游挂时响应一般不计费（未到达 OpenAI）
• 恢复后哨兵补到、响铃、退出，不会多余烧额度
• 最坏情况 60 次 × quality=low × 短 prompt，总量成本极低

退出码：0=恢复 / 1=超过最大次数仍挂 / 130=Ctrl+C 中断。

🐛 常见问题

Q: 报错 未找到 OPENAI_API_KEY？ A: 没复制 .env，或 .env 里 Key 没填、写错了变量名。

Q: 报错 403 / model_not_found / not_authorized_to_use_model？ A: 你账号还没通过组织认证，去 OpenAI 后台 → Settings → Organization → Verify。

Q: 中文 prompt 会不会效果差？ A: gpt-image-2 对中文支持比 1 代明显提升；不放心把关键词翻成英文，或在 prompt 末尾追加风格类英文标签。

Q: 想换成国内代理 / Azure 端点？ A: 在 .env 里设置 OPENAI_BASE_URL=https://你的代理/v1 即可，无需改代码。

Q: 中转 API 报错 404 / model_not_found？ A: 多半是中转商不支持默认的 gpt-image-2。用这段代码列出中转上架了哪些：client.models.list()；没有就试 --model gpt-image-1 或 --model dall-e-3。

Q: 中转 API 报错 Connection error / timeout？ A: 检查 OPENAI_BASE_URL 是否拼错（少 /v1、多斜杠都会出问题），并确认中转域名能在浏览器访问。

Q: 中转返回的图特别小或没数据？ A: 部分廉价中转对 quality=high、size=1536x1024 收费高，会偷偷降级；先用 --dry-run 确认参数，再用低质量小尺寸验通，再加大。

Q: 为什么默认开启 --stream？ A: 实测国内常见中转的 nginx proxy_read_timeout 仅 60s，gpt-image-2 生成时间常超 60s。流式让 OpenAI 边生成边推送，避免 nginx 累计超时。走官方账号不需要这个保护，加 --no-stream 即可。

Q: 怎么强制走非流式？ A: 加 --no-stream。

Q: 报错 peer closed connection without sending complete message body 怎么办？ A: 中转 nginx 在两次 partial 推送之间超过 proxy_read_timeout 主动断流。CLI 已经把已收到的 partial 落盘并视为成功产出。如果必须拿到 completed：联系中转商调高 timeout / 换支持长连接的中转 / 用官方账号。

Q: partial 是不是质量很差的缩略图？ A: 不是。OpenAI 的 partial_image 是生成过程中接近完成态的 1024×1024 PNG（实测 1.4MB），多数情况下肉眼看不出与 completed 的差异。

📝 许可证

MIT License — Copyright © 2026 Mad甘