| 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
- 访问 platform.openai.com/api-keys（需科学上网）
- 注册/登录 OpenAI 账号（需邮箱 + 手机号验证）
- 点击 "Create new secret key" → 复制
sk-proj-...
⚠️ 关闭弹窗后无法再次查看，务必立即保存
- 去 Billing 充值（最低 $5，2025 年起无免费额度）
第二步：组织验证（GPT Image 系列必须）
访问 platform.openai.com/settings/organization/general
完成"Organization Verification"，否则调用 GPT Image 模型会返回 403。
第三步：配置到环境
export OPENAI_API_KEY=sk-proj-xxxxxxxxxxxxxxxx
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-...
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 | 响应无数据 | 检查网络，重试 |
