draw-image

name

draw-image

description

Generate diagrams, flowcharts, and conceptual illustrations using OpenAI gpt-image-2 (default) or gpt-image-1. Use for: algorithm/code flow diagrams, system architecture sketches, conceptual illustrations, and any figure that does NOT represent actual code execution output (data plots, model results, etc. must still be generated by running Python code). Requires OPENAI_API_KEY and OpenAI organization verification when used from Claude Code / API path. OpenAI Codex subscribers can use built-in $imagegen without an API key.

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	响应无数据	检查网络，重试