105 lines
7.4 KiB
Markdown
105 lines
7.4 KiB
Markdown
---
|
||
name: le-gpt-image
|
||
description: >
|
||
用 GPT Image 生成或编辑图片：海报、封面、插画、UI mockup、信息图配图、文章插图、表情包、风格迁移改图。
|
||
复用本机 Codex CLI 的 ChatGPT 登录凭证（~/.codex/auth.json），不需要 OpenAI API Key，
|
||
走 Codex 内部图像通道，消耗的是 ChatGPT 订阅额度。
|
||
当用户说「画一张图」「生成一张…的图」「做张海报/封面/头图」「帮文章配图」「把这张图的背景换成…」
|
||
「按这张图的风格重画」「GPT Image 生图」时使用；拿到图像需求但没指明工具、而本机已登录 Codex 时也触发。
|
||
不要用于：视频生成、需要 API 计费与发票的正式生产管线、要求 gpt-image-2.5-flare/sunburst 专属能力的任务
|
||
（那是 API 通道专属模型，无 Key 走不了）、未登录 Codex 的机器。
|
||
---
|
||
|
||
# le-gpt-image
|
||
|
||
用 GPT Image 生图与改图，凭证复用本机 Codex 登录，全程无 API Key。额度来自 ChatGPT 订阅——把每次生成当作在花用户的订阅用量，高成本操作先确认。
|
||
|
||
## 核心原则
|
||
|
||
- **无 Key 通道。** 凭证只读 `~/.codex/auth.json`（ChatGPT 登录态），token 临过期由脚本自动刷新并原子写回；任何情况下不打印、不外发 token。
|
||
- **执行只走脚本。** 生图一律调 `scripts/gpt_image.py`，不现场写 HTTP/SDK 代码；判断放参考（提示词手艺读 [references/prompt-craft.md](references/prompt-craft.md)），调用走 CLI。
|
||
- **尺寸是建议值。** 实测 Codex 通道不严格遵循请求尺寸（请求 1024x1024 可能返回 1374x1145）；要精确画布时在交付说明里报告实际尺寸，必要时用改图/裁剪兜底。
|
||
- **失败即停。** 401 刷新失败、配额不足、内容策略拒绝：如实报告并停，不换参数偷跑重试。
|
||
|
||
## 能力边界
|
||
|
||
| 能力 | 说明 |
|
||
|---|---|
|
||
| 文生图 | `generate`，prompt + 尺寸 + 质量 |
|
||
| 改图 | `edit`，1–5 张参考图 + 指令；多图可做融合/参考绘制 |
|
||
| 风格迁移 | `edit --style-image`：内容取 `--image`，画风取 `--style-image` |
|
||
| 通道 | native（默认，GPT Image 直连，即 Codex 内部同款）；responses（备用，走推理模型强制图像工具） |
|
||
| 质量 | `auto / low / medium / high`（无 xhigh/max——那是 API 通道档位） |
|
||
| 背景 | `auto / opaque`；**不支持透明背景**（当前通道限制） |
|
||
| 张数 | `--n` 逐张请求，输出文件名加 `-1..-n` 后缀 |
|
||
|
||
单张耗时实测 40–60 秒；脚本默认超时 300 秒，429 限流自动退避重试（最多 4 次）。
|
||
|
||
## 工作流
|
||
|
||
1. **接单**：明确用途（海报/封面/插画/配图…）、主体、需出现的文字（逐字）、比例倾向。据 [references/prompt-craft.md](references/prompt-craft.md) 对应分节起草英文 prompt（图像模型对英文 prompt 更稳；图内文字保持用户原文）。
|
||
2. **停点确认**（回合终止契约）：出现以下任一情况，展示「最终 prompt + 尺寸/质量/张数 + 输出路径」后**立即结束回合**，不得再发起任何工具调用；用户确认或给修改意见后再继续——
|
||
- 实质改写或补写了用户给的描述（用户只说「画只猫」而你扩写了一整段场景）；
|
||
- `--n > 1` 或 4k 尺寸（成倍消耗额度）；
|
||
- 要编辑不可再生的原图（用户仅有的一份照片/扫描件）——先确认输出另存、不覆盖。
|
||
用户明确说「直接生成」、或需求已完整（明确描述 + 默认参数 + 单张）时跳过停点，直接生成。
|
||
3. **生成与交付**：调 CLI，stdout 末行即输出路径。交付时报告：路径 + 实际尺寸 + 关键参数，另附一条可选的改进建议（换质量档/调 prompt），不自动追加生成变体。
|
||
|
||
## CLI 速查
|
||
|
||
```bash
|
||
SKILL/scripts/gpt_image.py check # 看凭证：模式/套餐/token 余量
|
||
SKILL/scripts/gpt_image.py generate \
|
||
--prompt "A minimalist poster for a tea shop, warm beige palette, the text \"好茶慢慢喝\" centered" \
|
||
--size portrait --quality high --out poster.png
|
||
SKILL/scripts/gpt_image.py edit \
|
||
--image photo.png --prompt "Change the background to snowy mountains, keep the person unchanged" \
|
||
--out photo-new.png
|
||
SKILL/scripts/gpt_image.py edit \
|
||
--image content.png --style-image ink.png --out styled.png # 风格迁移
|
||
```
|
||
|
||
| 参数 | 取值 | 说明 |
|
||
|---|---|---|
|
||
| `--prompt` / `--prompt-file` | 文本 / 路径 | 生图或改图指令（edit 配 `--style-image` 时可选） |
|
||
| `--out` | 路径 | 缺省 `fig/YYYYMMDD-HHMMSS-<slug>.png`；存在须加 `--force` 才覆盖 |
|
||
| `--size` | 见下表 | 缺省 `auto` |
|
||
| `--quality` | `auto/low/medium/high` | 草稿 low，成品 high |
|
||
| `--n` | 整数 | 逐张请求，文件名加后缀 |
|
||
| `--backend` | `native/responses` | native 默认；responses 为备用通道 |
|
||
| `--image` | 路径，可重复 | edit 输入图，1–5 张（Pillow 在位时自动压至最长边 1536 的 WebP） |
|
||
| `--style-image` | 路径 | edit 的风格参考图 |
|
||
| `--dry-run` | 开关 | 只打印请求（凭证打码）不联网，排障首选 |
|
||
|
||
### 尺寸速查
|
||
|
||
| 别名 | 像素 | 适用 |
|
||
|---|---|---|
|
||
| `1k` / `square` | 1024x1024 | 默认方图、社交媒体 |
|
||
| `portrait` | 1024x1536 | 海报、封面、手机壁纸 |
|
||
| `landscape` | 1536x1024 | 文章头图、横幅 |
|
||
| `wide` | 1536x640 | 超宽 banner |
|
||
| `tall` | 1024x2048 | 长图、竖版故事 |
|
||
| `2k` / `4k` | 2048x2048 / 3840x2160 | 印刷、大屏（高额度，先停点确认） |
|
||
|
||
也接受 `WIDTHxHEIGHT`（须 16 倍数、最长边 ≤3840、宽高比 1:3–3:1）。**记住服务端可能自行调整尺寸**，交付时以实际输出为准。
|
||
|
||
## 故障排查
|
||
|
||
| 现象 | 处置 |
|
||
|---|---|
|
||
| 未找到凭证文件 / auth_mode 不是 chatgpt | 指引用户在本机跑 `codex login` 选 ChatGPT 登录；Codex 需文件凭证存储（config.toml `cli_auth_credentials_store = "file"`） |
|
||
| 刷新令牌失败（HTTP 4xx） | refresh_token 已失效，指引用户重新 `codex login`；不要反复重试 |
|
||
| HTTP 429 | 脚本自动退避重试；重试仍失败则告知用户订阅图像额度已到限，建议稍后再试或降 quality/尺寸 |
|
||
| 尺寸不符警告 | 属正常（服务端建议值行为），按实际尺寸交付 |
|
||
| 网络请求失败 | 先定位出口：`curl --noproxy '*' https://api.ipify.org` 与 `curl -x http://127.0.0.1:7890 ...` 对比出口 IP。macOS 上 Python urllib 会自动读系统代理设置（即使只开 TUN 模式也会被显式代理入口接管）；TUN 与 7890 通常同核同出口 |
|
||
| `Remote end closed connection` / 403 含 `cf-mitigated: challenge` | 出口 IP 被 chatgpt.com 的 Cloudflare 风控盯上（浏览器能过 JS 质询所以「看着正常」，CLI 过不了；`check` 仍正常、api.openai.com 可能仍可达——风控按域名单独加）。请用户在代理 App **切换节点换出口 IP**，切完重试即可；勿反复硬撞 |
|
||
| native 通道 404/失效 | 内部接口无稳定性契约；切 `--backend responses` 试试，并在交付时说明 |
|
||
|
||
## 安全边界
|
||
|
||
- 凭证只读 `auth.json`，刷新写回仅限该文件；绝不打印 token、不把凭证带进生成参数。
|
||
- 输出只落在用户指定目录或当前目录 `fig/`；覆盖已存在文件必须显式 `--force`。
|
||
- 生成内容遵守平台内容政策；收到拒绝时如实转达，不换措辞绕过。
|
||
- 每张图都消耗 ChatGPT 订阅额度：不擅自生成变体对比、不批量跑图，多张先停点确认。
|