---
name: openai_image_gen
description: 當使用者要求「畫圖」、「生圖」、「生成圖片」、「AI 繪圖」、「做一張插圖」、「修改這張圖」、「用 OpenAI 生圖」、「用 Codex 生圖」或需要寫實/插畫風格圖片時觸發。優先透過 Codex CLI（ChatGPT 訂閱額度，不另計費）生圖，必要時改用 OpenAI Images API（GPT Image 2.5），輸出到目前專案的 output/images/。
---

# AI 圖片生成（全域）

> 安裝：放到 `~/.claude/skills/openai_image_gen/SKILL.md`，並把下方所有 `<腳本資料夾>` 換成 codex_image.py 與 generate_image.py 的實際資料夾路徑。
> 教學：https://ijun-ai.com/media/ai-image-gen/

## 選擇方式

1. **預設：Codex CLI**（用 ChatGPT 訂閱額度，不另計費）。
2. **改用 API**（每張計費）的情況，用 API 前先告知使用者：
   - Codex 失敗（額度用完、未登入、逾時、沒產生圖片）；
   - 需要精確參數：透明背景、指定像素尺寸、指定畫質、遮罩局部修改、指定 sunburst 模型；
   - 使用者明確要求用 API。

## 方式一：Codex CLI（優先）

```
python "<腳本資料夾>\codex_image.py" "<prompt>" [選項]
```

- `--aspect landscape|portrait|square`：橫／直／方（只是提示，非精確像素）
- `--edit a.png [b.png ...]`：附圖作為修改底圖或參考圖
- `--prompt-file prompt.txt`：長描述或含引號時，從 UTF-8 文字檔讀取（PowerShell 5.1 傳含雙引號的參數會被拆開）
- `-n 2`：張數；`--name hero`：檔名前綴；`--out-dir`：輸出資料夾（預設目前工作目錄的 `output/images/`）
- 一張約 40–60 秒，指令 timeout 設 600000 毫秒。
- 腳本會自動找 Codex（CODEX_EXE → PATH → Codex 桌面版安裝路徑）。
- 印出輸出檔路徑即成功；結束碼非 0 或「沒有產生圖片」即失敗，改用方式二。

## 方式二：OpenAI API（備援 / 精確參數）

```
python "<腳本資料夾>\generate_image.py" "<prompt>" [選項]
```

- API Key：環境變數 OPENAI_API_KEY，或腳本旁邊的 `.env`（`OPENAI_API_KEY=sk-...`）。
- `--size 1536x1024`（橫）/ `1024x1536`（直）/ `1024x1024`（方）/ `auto`
- `--quality low|medium|high`：草稿用 low 省錢，定稿用 high
- `--background transparent`：透明背景（貼紙、Logo、去背角色）
- `--edit a.png [b.png ...]`：以既有圖片為底修改；`--mask m.png` 指定修改區域
- `-n 2`：張數；`--name hero`：檔名前綴
- `--model`：預設讀 OPENAI_IMAGE_MODEL，否則 gpt-image-2.5-flare
- 模型選擇：日常用 `gpt-image-2.5-flare`（快、便宜）；精緻定稿、精準局部編輯、圖內文字多時用 `gpt-image-2.5-sunburst`

兩種方式都會印出輸出檔路徑，產生後要打開圖片檢查，再交給使用者。

## Prompt 撰寫

- 寫清楚：主體、動作、場景、風格（扁平插畫／水彩／寫實照片）、構圖、色調、用途。
- 圖中需要中文字時，把文字用引號標明並要求「字體清楚、無錯字」；生成後檢查文字（小字較易出錯），錯字多時改用 high 畫質或 sunburst，或圖內不放字、之後再排版。

## 注意

- 絕不把 API Key 寫進指令、程式或回覆中，也不要讀出 .env 內容。
- API 方式每張都會計費；Codex 方式也會消耗訂閱額度。大量生成（>4 張）前先跟使用者確認。
- output/images/ 為產出檔，不要當作原始素材覆寫。