draw-image: OpenAI gpt-image-2 图像生成

---

两种使用路径

路径	工具	是否需要 API Key	费用
路径 A（本 skill 默认）	Claude Code + draw_image.py	✅ 需要 OPENAI_API_KEY	按 token 计费（见费用表）
路径 B	OpenAI Codex（含 ChatGPT Plus/Pro 订阅）	❌ 不需要额外 API Key	订阅内 usage limit 扣减

本 skill 属于路径 A，设计用于 Claude Code 和 AutoMCM-Pro agent。
若你使用 OpenAI Codex（桌面 app / CLI），见下方"在 Codex 中使用"章节。

---

前置条件（路径 A — Claude Code）

第一步：申请 OpenAI API Key

1. 访问 platform.openai.com/api-keys（需科学上网）
2. 注册/登录 OpenAI 账号（需邮箱 + 手机号验证）
3. 点击 "Create new secret key" → 复制 sk-proj-...
   ⚠️ 关闭弹窗后无法再次查看，务必立即保存
4. 去 Billing 充值（最低 $5，2025 年起无免费额度）

第二步：组织验证（GPT Image 系列必须）

访问 platform.openai.com/settings/organization/general
完成"Organization Verification"，否则调用 GPT Image 模型会返回 403。

第三步：配置到环境

# 临时（当前终端有效）
export OPENAI_API_KEY=sk-proj-xxxxxxxxxxxxxxxx

# 永久（写入 shell 配置）
echo 'export OPENAI_API_KEY=sk-proj-xxxxxxxxxxxxxxxx' >> ~/.bashrc
source ~/.bashrc

# 验证
echo $OPENAI_API_KEY | head -c 15

⚠️ 切勿把 API Key 写入代码文件或 git commit，.env 已在 .gitignore 中排除。

第四步：安装依赖

pip install "openai>=1.0"
python -c "import openai; print(openai.__version__)"

---

在 OpenAI Codex 中使用（路径 B，无需 API Key）

OpenAI Codex（ChatGPT Plus $20/月 及以上订阅已包含）内置 gpt-image-2 支持，
不消耗 API 额度，用自然语言或 $imagegen 关键字直接触发：

# Codex CLI 中自然语言触发
Generate a technical flowchart showing the AutoMCM pipeline steps

# 显式触发（更可靠）
$imagegen Clean flowchart: 建模流程 from 读取题目 to 生成PDF, white background

订阅内 usage limit 耗尽后，设置 OPENAI_API_KEY 可自动切换到 API 计费：

export OPENAI_API_KEY=sk-proj-...   # Codex CLI 检测到此变量后切换为 API 定价

---

Agent 调用前置检查（必须执行）

在生成任何图像前，先运行 --check：

python scripts/draw_image.py --check

输出	含义	Agent 应该做什么
method=api_key available=True	OPENAI_API_KEY 已设置	✅ 直接调用 --prompt 生成
method=codex_oauth available=True	Codex 已登录，但脚本不能直接用 OAuth	⚡ 改用 Codex CLI：$imagegen <prompt>
method=none available=False（退出码 2）	无任何认证	⏭ 跳过图像生成；在 LaTeX 中留 \missingfigure{描述} 占位，继续流水线

退出码 2 = "跳过"信号，不是错误。流水线不应因此中断。

# 示例：优雅跳过
python scripts/draw_image.py --check || {
  if [ $? -eq 2 ]; then
    echo "[draw_image] 跳过 — 无认证，继续流水线"
  fi
}

---

适用范围决策树

需要一张图？
├─ 内容来自代码运行数值（散点图、折线图、热力图、拟合曲线…）
│   └─ ✗ 不用本 skill → 必须用 matplotlib/seaborn 生成
└─ 非数值内容（流程图、架构图、概念示意）
    ├─ 极简几何图（≤3个框） → tikz 即可
    └─ 复杂流程图 / 概念插图
        ├─ --check 返回 api_key → python scripts/draw_image.py --prompt ...
        ├─ --check 返回 codex_oauth → $imagegen ... (Codex CLI)
        └─ --check 退出码 2 → 跳过，\missingfigure{} 占位

---

模型说明

模型	最大分辨率	特点	何时使用
gpt-image-2 (默认)	3840×2160	最新，文字渲染更准，支持灵活分辨率	论文插图、高质量输出
gpt-image-1.5	1536×1024	gpt-image-1 的改进版	中等需求
gpt-image-1	1536×1024	稳定，经过充分测试	兼容性需求
gpt-image-1-mini	1024×1024	轻量快速，价格低	草稿、快速迭代

---

参数说明

参数	默认值	有效值	说明
--prompt	—	任意文字（最多 32,000 字符）	图像描述
--output	—	.png / .jpg / .webp	保存路径
--model	gpt-image-2	见上表	模型选择
--size	1024x1024	任意 WxH（gpt-image-2 规则见下）	分辨率
--quality	medium	low medium high auto	质量
--output-format	从文件扩展名推断	png jpeg webp	格式
--compression	—	0–100	jpeg/webp 压缩率
--background	opaque	opaque auto ⚠️ transparent 不支持于 gpt-image-2	背景
--moderation	auto	auto low	内容审核强度

gpt-image-2 分辨率规则

• 每条边必须是 16px 的倍数
• 最大边 ≤ 3840px
• 长短边比 ≤ 3:1
• 总像素：655,360 – 8,294,400

常用预设：1024x1024、1536x1024、1024x1536、2048x2048、2048x1152、3840x2160

---

调用示例

基础（算法流程图）

python scripts/draw_image.py \
  --prompt "Clean technical flowchart on white background, Chinese labels.
Steps: (1) 读取赛题 → (2) 识别问题类型 → (3) 文献调研 → (4) 建立数学模型
→ (5) 编写求解代码 → (6) 运行验证脚本 → Decision: 全部通过?
→ Yes: 写入LaTeX / No: 修复代码 回到(5).
Style: professional diagram, blue/gray color scheme, sans-serif font,
clear arrows, minimal decoration." \
  --output "CUMCM_Workspace/latex/images/fig00_pipeline.png" \
  --size 1024x1536 \
  --quality high

系统架构图（横版）

python scripts/draw_image.py \
  --prompt "System architecture diagram on white background.
Left: User inputs problem PDF. Center: AutoMCM-Pro Agent with three modules:
[Problem Analysis] [Model & Verify] [LaTeX Writing]. Right: Output PDF paper.
Arrows show data flow. Style: clean tech diagram, English labels, gray boxes." \
  --output "CUMCM_Workspace/latex/images/fig_architecture.png" \
  --size 2048x1152 \
  --quality high

草稿快速预览（低成本）

python scripts/draw_image.py \
  --prompt "Simple flowchart: A → B → C → D" \
  --output "draft_check.png" \
  --model gpt-image-1-mini \
  --quality low

WebP 格式（更小体积）

python scripts/draw_image.py \
  --prompt "..." \
  --output "fig.webp" \
  --output-format webp \
  --compression 20 \
  --quality high

---

Prompt 工程指南

流程图 Prompt 模板

"Clean technical flowchart on white background. [中/英] labels.
Steps: (1) [step1] → (2) [step2] → ...
Decision nodes: [condition] → Yes: [action_yes] / No: [action_no]
Style: professional, minimal, blue/gray color scheme,
sans-serif font, clear directional arrows."

架构图 Prompt 模板

"System architecture diagram, white background.
Components: [component list with roles].
Connections: [arrows describing data/control flow].
Style: clean labeled boxes, professional tech diagram, no decorative elements."

概念插图 Prompt 模板

"Scientific illustration: [scenario].
Show [element1] as [visual], [element2] as [visual].
Style: technical/scientific, clean white background, labeled key elements,
suitable for academic paper, no heavy text."

---

LaTeX 集成

\begin{figure}[htbp]
  \centering
  \includegraphics[width=0.85\textwidth]{images/fig00_pipeline.png}
  \caption{建模流程图}
  \label{fig:pipeline}
\end{figure}

路径说明：images/ 相对于 CUMCM_Workspace/latex/，与 \graphicspath{{images/}} 配合使用。

---

费用参考（gpt-image-2，2026-04-21 定价）

分辨率	low	medium	high
1024×1024	~$0.006	~$0.053	~$0.211
1536×1024	~$0.005	~$0.041	~$0.165
1024×1536	~$0.005	~$0.041	~$0.165

以 token 计费：Image output $30/M tokens，text input $5/M tokens。

---

错误处理

错误信息	原因	解决方案
OPENAI_API_KEY not set	未设置 key	export OPENAI_API_KEY=sk-proj-...
openai package not installed	缺少依赖	pip install "openai>=1.0"
HTTP 403 / organization_verification	未完成组织验证	访问 platform.openai.com/settings/organization/general
content_policy_violation	Prompt 触发审核	简化描述，避免真实人物/商标
invalid_size	gpt-image-2 尺寸不合规	确保每边是 16 倍数，比例 ≤3:1
API returned no image data	响应无数据	检查网络，重试