# imgen-cli

**Repository Path**: cc123hh/imgen-cli

## Basic Information

- **Project Name**: imgen-cli
- **Description**: 命令行 AI 生图工具：零依赖 Python 脚本，macOS/Linux/Windows 全平台通用，支持任何 OpenAI 兼容的 /images/generations 接口
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-10-30
- **Last Updated**: 2026-11-04

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

<h1 align="center">imgen</h1>

<p align="center">
  <img src="docs/banner.jpg" alt="imgen banner" width="720">
</p>

<p align="center">
  <img src="docs/badges/python.svg" alt="python 3.8+">
  <img src="docs/badges/platform.svg" alt="platform">
  <img src="docs/badges/deps.svg" alt="dependencies">
  <img src="docs/badges/license.svg" alt="license">
</p>

<p align="center">
  <b>一条命令，把脑子里的画面变成图片。</b><br>
  零依赖 · 跨平台 · 支持任何 OpenAI 兼容的 <code>/images/generations</code> 接口
</p>

---

## 📑 目录

- [功能演示](#-功能演示)
- [特性](#-特性)
- [安装](#-安装)
- [配置](#-配置)
- [用法](#-用法)
- [参数一览](#-参数一览)
- [示例作品](#-示例作品)
- [常见问题](#-常见问题)
- [贡献](#-贡献)
- [License](#license)

## 🎬 功能演示

```console
$ imgen -p "一只趴在窗台上的橘猫，阳光午后，插画风格" -o cat.png

[1/1] 生成中… model=gpt-image-1 size=1024x1024
  ✅ 已保存 cat.png（2113 KB，20.0s，tokens=1650）
```

一行命令，20 秒，出图。没有配置地狱，没有依赖安装 —— 只要有 Python 就能跑。

## ✨ 特性

- 🪶 **零依赖**：只用 Python 标准库，不需要 `pip install` 任何东西
- 🖥️ **跨平台**：macOS / Linux / Windows 通吃，脚本、安装器、文档都适配
- 🌐 **接口通用**：默认走 OpenAI 官方接口，用 `--base` / `IMGEN_BASE` 可指向任何兼容服务
- 🔑 **秘钥走环境变量**：不写死在代码里，不怕误传仓库
- 🔄 **两种返回格式都支持**：`b64_json` 与 `url` 自动识别
- 📦 **批量生成**：`-n 4` 一次四张，自动编号
- 🇨🇳 **中文 prompt 友好**：Windows 控制台自动切 UTF-8，不乱码
- 🖼️ **支持参考图**：`--image` 传一张或多张参考图，走 `/images/edits`，可配 `--mask` 局部重绘
- 🔌 **代理友好**：`--proxy` 或 `IMGEN_PROXY`，国内网络轻松用

## 🚀 安装

> **前提**：已安装 Python 3.8 或更高版本。
> 检查：`python3 --version`（Windows 上是 `python --version`）

### macOS / Linux

```bash
git clone https://gitee.com/cc123hh/imgen-cli.git
cd imgen-cli
./install.sh
```

安装器会把命令放到 `~/.local/bin`，并检查该目录是否在 `PATH` 中。

### Windows

**方式一：PowerShell 一键安装**

```powershell
git clone https://gitee.com/cc123hh/imgen-cli.git
cd imgen-cli
powershell -ExecutionPolicy Bypass -File .\install.ps1
```

脚本会安装到 `%USERPROFILE%\.local\bin`，并自动把该目录加入用户 `PATH`（重开终端生效）。

**方式二：免安装直接用**

```bat
cd imgen-cli
imgen.cmd -p "一只戴围巾的小企鹅"
```

**方式三：手动**

把 `imgen.py` 放到任意目录，然后：

```bat
python C:\path\to\imgen.py -p "你的描述"
```

### 所有平台：pipx 安装（推荐给 Python 用户）

```bash
pipx install git+https://gitee.com/cc123hh/imgen-cli.git
```

之后在任意位置直接使用 `imgen` 命令，升级也很方便。

### 其他安装方式

```bash
# 临时运行，不安装
python3 imgen.py -p "一只柴犬"

# Git Bash / WSL 里也可以用 ./install.sh
```

## ⚙️ 配置

只需要一个环境变量：**API Key**。

### macOS / Linux（写进 `~/.zshrc` 或 `~/.bashrc`）

```bash
export IMGEN_API_KEY="sk-你的key"
```

### Windows（PowerShell，永久生效）

```powershell
setx IMGEN_API_KEY "sk-你的key"
```

### Windows（cmd，仅当前窗口）

```bat
set IMGEN_API_KEY=sk-你的key
```

### 可选配置

| 变量 | 用途 | 示例 |
|---|---|---|
| `IMGEN_BASE` | 接口地址 | `https://api.openai.com/v1` |
| `IMGEN_PROXY` | 代理地址 | `http://127.0.0.1:7890` |
| `IMGEN_MODEL` | 默认模型名 | `gpt-image-1` |

## 📖 用法

```bash
imgen -p "一只柴犬在海边奔跑，吉卜力风格"                 # 直接出图
imgen -p "星空下的鲸鱼" -o whale.png                     # 指定输出文件名
imgen -m gpt-image-1 -p "赛博朋克城市"                   # 换模型
imgen -p "白米饭拟人" -n 4                              # 一次出 4 张
imgen -p "极简 logo 设计" -s 1024x1024 --timeout 120    # 尺寸与超时
imgen -p "深夜食堂" --proxy http://127.0.0.1:7890       # 临时走代理
imgen --help                                            # 查看全部参数
```

Windows 用户把 `imgen` 换成 `imgen.cmd`（或已加入 PATH 则直接用 `imgen`）。

### 带参考图生成（图生图）

传了 `--image` 就会自动改走 `/images/edits`（multipart 上传），不再走纯文本接口。

```bash
# 单张参考图：改风格、改画法、保持构图
imgen -p "把这只猫改成水墨画风格，保留姿势" --image docs/demo-cat.png -o out.png

# 多张参考图：融合主体（人物 + 服装、猫 + 企鹅 等）
imgen -p "让这只橘猫和这只企鹅一起坐在雪地长椅上" \
      --image docs/demo-cat.png --image docs/demo-penguin.png -o out.png

# 局部重绘：用蒙版圈出要改的区域
imgen -p "把天空换成晚霞" --image photo.png --mask sky_mask.png -o out.png
```

单张参考图效果（原图 → 水墨风，姿势与构图均保留）：

| 原图 | 生成结果 |
|---|---|
| <img src="docs/demo-cat.png" width="300" alt="原图"> | <img src="docs/demo-edit.png" width="300" alt="水墨风结果"> |

注意事项：

- 支持 png / jpg / webp / gif，单张上限 50 MB
- `--mask` 必须配合 `--image` 使用
- 参考图接口由服务端提供，**不是所有 OpenAI 兼容服务都实现了 `/images/edits`**；不支持时会返回 404


未指定 `-o` 时，文件自动命名为 `imgen-时间戳-序号.png`，例如 `imgen-20261030-130500-01.png`。

## 📋 参数一览

| 参数 | 说明 | 默认值 |
|---|---|---|
| `-p, --prompt` | 图片描述（必填，支持中文） | — |
| `-m, --model` | 模型名 | `gpt-image-1` |
| `-o, --output` | 输出文件名 | 自动生成 |
| `-s, --size` | 图片尺寸 | `1024x1024` |
| `-n, --count` | 生成张数 | `1` |
| `--base` | 接口地址 | `https://api.openai.com/v1` |
| `--proxy` | 代理地址 | 读 `IMGEN_PROXY` |
| `--image` | 参考图路径（可重复） | 无需，出现即走编辑接口 |
| `--mask` | 局部重绘蒙版（需配合 `--image`） | 无需 |
| `--timeout` | 超时秒数 | `300` |

## 🖼️ 示例作品

全部由 `imgen` 生成：

| | |
|---|---|
| <img src="docs/demo-cat.png" width="340" alt="窗台橘猫"><br><sub>`imgen -p "一只趴在窗台上的橘猫，阳光午后，插画风格"`</sub> | <img src="docs/demo-maid.png" width="340" alt="鲸鱼娘"><br><sub>`imgen -p "鲸鱼少女，蓝色渐变长发，端着白米饭，动漫风"`</sub> |
| <img src="docs/demo-penguin.png" width="340" alt="小企鹅"><br><sub>`imgen -p "一只戴着围巾的小企鹅在看雪"`</sub> | <img src="docs/example.png" width="340" alt="logo"><br><sub>`imgen -p "极简 logo，鲸鱼尾巴托起一碗白米饭"`</sub> |

## ❓ 常见问题

<details>
<summary><b>提示「未设置 API Key」怎么办？</b></summary>

环境变量没生效。macOS/Linux 下确认已在当前 shell 执行过 `export`（或重开终端）；Windows 下用 `setx` 后需要**新开**一个终端窗口。
</details>

<details>
<summary><b>Windows 控制台中文乱码 / 报 UnicodeEncodeError？</b></summary>

脚本已自动把输出切换到 UTF-8，一般不会出现。若仍有问题，可先执行 `chcp 65001` 切换控制台编码，或改用 Windows Terminal。
</details>

<details>
<summary><b>网络超时 / 连接失败？</b></summary>

国内访问部分接口需要代理，加 `--proxy http://127.0.0.1:7890`（Clash 默认端口），或设置环境变量 `IMGEN_PROXY`。企业网络下也可能需要配置 HTTPS 代理。
</details>

<details>
<summary><b>返回的图片尺寸和我指定的不一样？</b></summary>

部分服务端会忽略 `size` 参数，固定返回自身支持的尺寸（例如 1254×1254）。这是接口行为，不是脚本问题。
</details>

<details>
<summary><b>可以使用其他厂商的生图接口吗？</b></summary>

可以，只要它兼容 OpenAI 的 `/images/generations` 格式：

```bash
imgen --base https://api.openai.com/v1 -m dall-e-3 -p "a cute whale"
```

注意：不同服务的参数支持度可能不同，报错信息里会带上服务端返回的原始错误，方便排查。
</details>

<details>
<summary><b>怎么升级？</b></summary>

```bash
cd imgen-cli && git pull && ./install.sh        # macOS / Linux
# 或
pipx upgrade imgen-cli                           # pipx 安装的用户
```
</details>

## 🤝 贡献

欢迎提 Issue 和 PR！如果你在某个平台遇到兼容问题，请附上：

- 操作系统与版本
- `python --version` 输出
- 完整报错信息

## License

[MIT](LICENSE)