img-cli

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

特性

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

安装与环境准备

通过 PyPI 安装

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

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

本地开发与运行

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

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

认证配置

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

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)

# 基础生成（默认模型 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)

# 本地图片全图编辑
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>

img-cli edit <prompt>

运行测试

uv run pytest -v