gpt-image-2-skill 0.2.5

Agent-first GPT Image 2 CLI and installable skill runtime.
Documentation

gpt-image-2-skill

GitHub Release CI License Rust npm Homebrew

Language: 中文 | English

面向 AI Agent 的 GPT Image 2 CLI 与 Skill。一个命令面同时支持 OPENAI_API_KEY、OpenAI-compatible --openai-api-base，以及 Codex ~/.codex/auth.json 图片链路。CLI、Tauri App 与 Skill 共用 $CODEX_HOME/gpt-image-2-skill/config.json。

功能特性

  • images generate、images edit、request create
  • OpenAI gpt-image-2 与兼容服务端，支持自定义 --openai-api-base
  • Codex auth.json 图片链路，默认模型 gpt-5.4
  • -m/--model、--ref-image、--mask、--background transparent
  • --format png|jpeg|webp、--quality、--compression、--input-fidelity
  • --json stdout 结果与 --json-events stderr JSONL 进度事件
  • 默认 3 次 retry，Codex 401 自动 refresh 后重试
  • 2K、4K 尺寸别名与自定义 WIDTHxHEIGHT
  • config、secret、history 命令，覆盖共享配置、文件/env/Keychain 密钥来源和本地 SQLite 历史
  • Tauri App scaffold 位于 apps/gpt-image-2-app，前端可直接消费 runtime-contract.ts 与 contracts/mock-data.json

安装

cargo install gpt-image-2-skill --locked
cargo binstall gpt-image-2-skill --no-confirm
brew install wangnov/tap/gpt-image-2-skill
npm install --global gpt-image-2-skill

本地开发安装：

make install-local

快速开始

OpenAI API Key 直连：

OPENAI_API_KEY=sk-... gpt-image-2-skill --json \
  images generate \
  --prompt "A studio product photo of a red apple on transparent background" \
  --out ./apple.png \
  --background transparent \
  --format png \
  --quality high \
  --size 1024x1024

OpenAI-compatible Base URL：

OPENAI_API_KEY=sk-... gpt-image-2-skill --json \
  --provider openai \
  --openai-api-base https://api.duckcoding.ai/v1 \
  images generate \
  --prompt "A polished geometric app logo on transparent background" \
  --out ./logo.png \
  --background transparent \
  --format png \
  --size 2K

共享配置固定 provider：

gpt-image-2-skill --json config add-provider \
  --name my-image-api \
  --type openai-compatible \
  --api-base https://example.com/v1 \
  --api-key sk-... \
  --set-default

gpt-image-2-skill --json config inspect
gpt-image-2-skill --json images generate \
  --prompt "A polished geometric app logo on transparent background" \
  --out ./logo.png

Codex auth.json 生图：

gpt-image-2-skill --json --json-events \
  --provider codex \
  images generate \
  --prompt "A glossy red apple sticker on transparent background" \
  --out ./apple.png

参考图编辑：

gpt-image-2-skill --json --json-events \
  images edit \
  --prompt "Refine this logo, keep transparency, and improve visibility on dark backgrounds" \
  --ref-image ./logo.png \
  --out ./logo-edit.png \
  --background transparent \
  --format png \
  --size 1024x1024

Skill 安装

Codex / Anthropic skills CLI：

npx skills add https://github.com/Wangnov/gpt-image-2-skill --skill gpt-image-2-skill

Claude Code（直接复制到本地 skills 目录）：

git clone https://github.com/Wangnov/gpt-image-2-skill /tmp/gpt-image-2-skill
cp -r /tmp/gpt-image-2-skill/skills/gpt-image-2-skill ~/.claude/skills/

Skill 入口是 node skills/gpt-image-2-skill/scripts/gpt_image_2_skill.cjs。包装器按这个顺序解析运行时：

  1. GPT_IMAGE_2_SKILL_BIN
  2. 已安装的 gpt-image-2-skill
  3. Tauri App bundled CLI
  4. 仓库内 cargo run -p gpt-image-2-skill --
  5. 当前版本 GitHub Release 资产下载到本地缓存

尺寸与输出

  • --size 2K 解析为 2048x2048
  • --size 4K 解析为 3840x2160
  • 竖版 4K 使用 2160x3840
  • 当前方图高分辨率上限是 2880x2880
  • 自定义尺寸遵循当前约束：宽高都是 16 的倍数，最大边长 3840，最大总像素 8294400，最大长宽比 3:1

分发与发布

  • crates.io：cargo install gpt-image-2-skill --locked
  • cargo-binstall：预编译二进制安装
  • GitHub Releases：归档、shell installer、PowerShell installer、Windows MSI
  • Homebrew：wangnov/tap/gpt-image-2-skill
  • npm：根包 + 平台子包矩阵
  • Skill：npx skills add

npm 首发通过 GitHub Actions 中的 NPM_TOKEN 完成，并保留 --provenance。包首次上线后，可运行 scripts/release/configure-npm-trust.sh 绑定 trusted publisher；脚本会先读取现有配置，重复执行也安全。手动验收可通过 npm-publish.yml 的 dry_run 输入完成整条 npm 打包链路校验。

文档

  • Skill 说明：skills/gpt-image-2-skill/SKILL.md
  • Release 流程：scripts/release/prepare.sh、scripts/release/publish.sh、scripts/release/verify.sh
  • Skill 冒烟验证：scripts/smoke_skill_install.cjs

许可证

MIT。详见 LICENSE。

Language: 中文 | English

Agent-first GPT Image 2 CLI and Skill. One command surface supports OPENAI_API_KEY, OpenAI-compatible --openai-api-base, and the Codex image path driven by ~/.codex/auth.json. The CLI, Tauri App, and Skill share $CODEX_HOME/gpt-image-2-skill/config.json.

Features

  • images generate, images edit, and request create
  • OpenAI gpt-image-2 plus OpenAI-compatible backends through --openai-api-base
  • Codex auth.json image flow with default model gpt-5.4
  • -m/--model, --ref-image, --mask, transparent backgrounds, and PNG/JPEG/WebP output
  • machine-readable stdout JSON plus stderr JSONL progress events
  • default three-attempt retry behavior with Codex 401 refresh
  • 2K and 4K size aliases plus custom WIDTHxHEIGHT
  • config, secret, and history commands for shared config, file/env/Keychain credential sources, and local SQLite history
  • Tauri App scaffold under apps/gpt-image-2-app; frontend-ready contracts live in runtime-contract.ts and contracts/mock-data.json

Installation

cargo install gpt-image-2-skill --locked
cargo binstall gpt-image-2-skill --no-confirm
brew install wangnov/tap/gpt-image-2-skill
npm install --global gpt-image-2-skill

Local development install:

make install-local

Quickstart

OpenAI API key:

OPENAI_API_KEY=sk-... gpt-image-2-skill --json \
  images generate \
  --prompt "A studio product photo of a red apple on transparent background" \
  --out ./apple.png \
  --background transparent \
  --format png \
  --quality high \
  --size 1024x1024

OpenAI-compatible base URL:

OPENAI_API_KEY=sk-... gpt-image-2-skill --json \
  --provider openai \
  --openai-api-base https://api.duckcoding.ai/v1 \
  images generate \
  --prompt "A polished geometric app logo on transparent background" \
  --out ./logo.png \
  --background transparent \
  --format png \
  --size 2K

Pinned provider through shared config:

gpt-image-2-skill --json config add-provider \
  --name my-image-api \
  --type openai-compatible \
  --api-base https://example.com/v1 \
  --api-key sk-... \
  --set-default

gpt-image-2-skill --json config inspect
gpt-image-2-skill --json images generate \
  --prompt "A polished geometric app logo on transparent background" \
  --out ./logo.png

Codex auth.json:

gpt-image-2-skill --json --json-events \
  --provider codex \
  images generate \
  --prompt "A glossy red apple sticker on transparent background" \
  --out ./apple.png

Reference image edit:

gpt-image-2-skill --json --json-events \
  images edit \
  --prompt "Refine this logo, keep transparency, and improve visibility on dark backgrounds" \
  --ref-image ./logo.png \
  --out ./logo-edit.png \
  --background transparent \
  --format png \
  --size 1024x1024

Skill Install

Codex / Anthropic skills CLI:

npx skills add https://github.com/Wangnov/gpt-image-2-skill --skill gpt-image-2-skill

Claude Code (drop the skill into your local skills directory):

git clone https://github.com/Wangnov/gpt-image-2-skill /tmp/gpt-image-2-skill
cp -r /tmp/gpt-image-2-skill/skills/gpt-image-2-skill ~/.claude/skills/

The bundled wrapper resolves the runtime in this order:

  1. GPT_IMAGE_2_SKILL_BIN
  2. an installed gpt-image-2-skill
  3. Tauri App bundled CLI
  4. repo-local cargo run -p gpt-image-2-skill --
  5. a cached GitHub Release binary for the current version

Size Rules

  • --size 2K resolves to 2048x2048
  • --size 4K resolves to 3840x2160
  • portrait 4K uses 2160x3840
  • the current square high-resolution ceiling is 2880x2880
  • custom sizes follow the current constraints: both edges must be multiples of 16, max edge 3840, max total pixels 8294400, max aspect ratio 3:1

Distribution

  • crates.io
  • cargo-binstall
  • GitHub Releases with archives and installers
  • Homebrew tap
  • npm root package plus platform subpackages
  • installable Skill bundle through npx skills add

The first npm publish uses NPM_TOKEN in GitHub Actions and keeps --provenance enabled. Once the packages exist on npm, run scripts/release/configure-npm-trust.sh to bind trusted publishers; the script reads the current state first, so reruns are safe. Manual acceptance can use the dry_run input on npm-publish.yml to validate the full npm packaging path.

Docs

  • Skill spec: skills/gpt-image-2-skill/SKILL.md
  • Release flow: scripts/release/prepare.sh, scripts/release/publish.sh, scripts/release/verify.sh
  • Skill smoke test: scripts/smoke_skill_install.cjs

License

MIT. See LICENSE.