Metadata-Version: 2.5
Name: img-cli
Version: 0.1.0
Summary: CLI tool for OpenAI-compatible Image Generation and Editing
License-File: LICENSE
Requires-Python: >=3.10
Requires-Dist: click>=8.1.7
Requires-Dist: httpx>=0.27.0
Requires-Dist: openai>=1.50.0
Requires-Dist: pillow>=10.2.0
Requires-Dist: pydantic>=2.6.0
Requires-Dist: rich>=13.7.0
Description-Content-Type: text/markdown

# img-cli

命令行图片生成与编辑工具，基于 Python + uv 开发，封装 OpenAI 兼容的 Images API（文生图 `generate` 与图生图编辑 `edit`）。

<p align="center">
  <img src="assets/poster.png" alt="img-cli Poster" width="600" />
</p>

---

## 特性

- 🚀 **简单易用**：一行命令完成图片生成和图片编辑。
- 🔑 **灵活认证**：支持 `~/.img_gen/auth.json` 配置文件及环境变量。
- 📝 **审计日志**：自动在 `~/.img_gen/img.log` 记录每次请求详情（JSON Lines 格式）。
- 🖼️ **格式与尺寸自适应**：支持 PNG / JPEG / WEBP，自动进行 RGBA 蒙版和格式转换。
- 🌐 **网络与本地图片支持**：编辑模式下原图和蒙版均支持本地路径（含 `~`）及 HTTP/HTTPS URL。
- 🤖 **Agent 友好**：清晰的标准输出与结构化错误码，便于自动化工作流接入。

---

## 安装与环境准备

### 通过 PyPI 安装

```bash
# 使用 uv 工具安装（推荐）
uv tool install img-cli

# 或通过 pip 安装
pip install img-cli
```

### 本地开发与运行

```bash
# 1. 运行测试 / 调试
uv run img-cli --help

# 2. 从源码安装 CLI
uv tool install .
```

---

## 认证配置

首次使用前，请创建配置文件 `~/.img_gen/auth.json`：

```bash
mkdir -p ~/.img_gen
echo '{"api_key":"sk-xxx","api_base":"https://api.openai.com/v1"}' > ~/.img_gen/auth.json
```

也可通过环境变量传入：
- `OPENAI_API_KEY`（或 `IMG_GEN_API_KEY`）
- `OPENAI_BASE_URL`（或 `OPENAI_API_BASE` / `IMG_GEN_API_BASE`）

---

## 快速使用

### 1. 文生图 (generate)

```bash
# 基础生成（默认模型 gpt-image-2，保存至当前目录）
img-cli generate "一只戴墨镜的猫坐在沙滩上"

# 指定模型、尺寸与输出目录
img-cli generate "a futuristic city at sunset" -m dall-e-3 -s 1792x1024 -q hd -o ~/Desktop

# 指定输出格式为 JPEG
img-cli generate "产品白底宣传图，极简风格" -m gpt-image-1 -q high --format jpeg -o ./output
```

### 2. 图片编辑 (edit)

```bash
# 本地图片全图编辑
img-cli edit "给猫戴上一顶红色圣诞帽" --image ./cat.png -o ./output

# 网络图片直接编辑
img-cli edit "替换背景为星空" --image https://example.com/photo.jpg -o ./output

# 带蒙版的局部编辑（蒙版透明区域为待修改区域）
img-cli edit "用一朵玫瑰替换这里" --image ./photo.png --mask ./mask.png -o ./output
```

---

## 命令参数参考

### `img-cli generate <prompt>`

| 参数 | 默认值 | 说明 |
|---|---|---|
| `prompt` | 必填 | 提示词（支持中文与英文） |
| `-m`, `--model` | `gpt-image-2` | 模型名称（如 `gpt-image-2`, `dall-e-3`, `gpt-image-1`） |
| `-s`, `--size` | `1024x1024` | 尺寸（如 `1024x1024`, `1536x1024`, `1024x1536`, `auto`） |
| `-q`, `--quality` | 无 | 质量（`low` / `medium` / `high` / `auto` / `standard` / `hd`） |
| `-n`, `--n` | `1` | 生成张数 |
| `-o`, `--output` | `.` | 图片输出目录 |
| `--format` | `png` | 输出格式：`png` / `jpeg` / `webp` |

### `img-cli edit <prompt>`

| 参数 | 默认值 | 说明 |
|---|---|---|
| `prompt` | 必填 | 修改描述 |
| `-i`, `--image` | 必填 | 原图：本地路径或 HTTP/HTTPS URL |
| `--mask` | 无 | 蒙版：本地路径或 URL（PNG 透明区域待修改） |
| `-m`, `--model` | `gpt-image-2` | 模型名称 |
| `-s`, `--size` | `auto` | 尺寸 |
| `-q`, `--quality` | `auto` | 质量 |
| `-n`, `--n` | `1` | 生成张数 |
| `-o`, `--output` | `.` | 图片输出目录 |
| `--format` | `png` | 输出格式：`png` / `jpeg` / `webp` |

---

## 运行测试

```bash
uv run pytest -v
```
