API Draw

面向个人使用的 gpt-image-2 生图工具。它共用一套核心能力，提供：

• Codex 全局 MCP：让 Codex 在任何项目中调用生图和编辑工具
• 本地网页：提示词、尺寸预设、图片上传编辑、历史记录和下载
• CLI：适合脚本、批处理和诊断

API 默认指向 https://api.999555999.com/v1，模型默认是 gpt-image-2。

安装与升级

在本项目目录执行：

npm.cmd install
npm.cmd install --global .

也可以运行项目自带的 install-global.ps1。如果 PowerShell 的执行策略拦截了 .ps1 文件，使用上面的 npm.cmd 命令。

升级代码后重复执行全局安装即可。当前全局命令名是 api-draw，Windows 下推荐显式使用 api-draw.cmd，避免 PowerShell 误选 api-draw.ps1 shim。

API Key

不要把 Key 写进项目文件、config.toml 或聊天记录。推荐保存为当前 Windows 用户环境变量：

[Environment]::SetEnvironmentVariable("API_DRAW_API_KEY", "你的密钥", "User")

已有 PowerShell 窗口不会自动刷新环境变量。可以在当前窗口立即载入：

$env:API_DRAW_API_KEY = [Environment]::GetEnvironmentVariable("API_DRAW_API_KEY", "User")

API Draw 在 Windows 上还会在进程环境未找到 Key 时读取当前用户的 HKCU\Environment，因此网页服务不依赖父进程是否刚刚刷新。

可选环境变量：

变量	默认值	用途
API_DRAW_BASE_URL	https://api.999555999.com/v1	图片 API 根地址
API_DRAW_MODEL	gpt-image-2	模型名
API_DRAW_DATA_DIR	Windows: %LOCALAPPDATA%\api-draw	图片、历史和服务状态目录
API_DRAW_TIMEOUT_MS	600000	单次 API 请求超时（毫秒）

一键网页

推荐方式：

api-draw.cmd open

它会后台启动本地服务并打开默认浏览器，不会留下常驻 CMD 窗口。也可以双击 open-api-draw.vbs，该方式完全隐藏控制台窗口。

默认地址是 http://127.0.0.1:8765。如果端口被占用，工具会自动选择附近的可用端口并打印实际地址。

服务管理：

api-draw.cmd start       # 后台启动，不打开浏览器
api-draw.cmd status      # 查看 PID、端口、Key 和健康状态
api-draw.cmd stop        # 停止后台服务
api-draw.cmd open        # 启动并打开浏览器

前台调试可以使用 api-draw.cmd web --port 8765。正常使用不需要前台模式。

网页功能

• 生成模式：输入提示词，选择质量和尺寸后生成
• 常见尺寸：1:1、3:2、2:3、16:9、9:16、4:3、3:4、4K 16:9
• 自定义尺寸：宽高都必须是 16 的倍数，最长边不超过 3840，比例不超过 3:1，总像素在 655,360 到 8,294,400 之间
• 编辑模式：直接选择 1 到 16 张 PNG/JPG/WEBP 参考图，可选 PNG 蒙版
• 历史图库：原图预览、下载、复制提示词、套用参数、删除记录
• 图片下载会以附件形式返回，文件名和 MIME 类型保持正确

编辑上传会在本地临时目录处理，调用完成或失败后自动清理临时文件。参考图单张不超过 25MB，蒙版不超过 4MB。

CLI

api-draw.cmd generate -p "一间充满阳光的现代工作室" -s 1024x1024 -q high
api-draw.cmd edit -p "把天空改成夕阳" -i "C:\\images\\input.png" --mask "C:\\images\\mask.png"
api-draw.cmd list -n 20
api-draw.cmd doctor

doctor 检查 Key、API 地址、尺寸规则、数据目录、网页服务和 Codex MCP 配置。doctor --live 会额外调用一次真实 API，使用低质量诊断图，会产生 API 用量。

Codex MCP

全局配置位于 %USERPROFILE%\.codex\config.toml。安装配置：

codex mcp add api-draw --env API_DRAW_BASE_URL=https://api.999555999.com/v1 --env API_DRAW_MODEL=gpt-image-2 -- api-draw mcp

API Key 通过 env_vars = ["API_DRAW_API_KEY"] 从用户环境转发，不会写入配置文件。修改 Key 或 MCP 配置后，完全退出并重新启动 Codex。

MCP 工具：

工具	参数	作用
generate_image	prompt, size, quality	生成一张图片并保存本地
edit_image	prompt, image_paths, mask_path?, size, quality	编辑 1 到 16 张本地图片
list_images	limit?	查询历史记录
get_image	id	返回记录元数据和图片内容

生成和编辑工具会返回 MCP image content、绝对路径、MIME 类型、文件大小和记录 ID。MCP 服务通过 STDIO 运行，不需要常驻 HTTP 端口。

数据位置

默认目录：

%LOCALAPPDATA%\api-draw\
├─ images\       已完成的图片
├─ uploads\      网页编辑临时上传，完成后清理
├─ history.json   最近 500 条记录
└─ service.json   后台网页服务 PID、端口和启动时间

历史文件使用临时文件替换方式写入，避免网页和 MCP 同时写入时产生半截 JSON。每次请求在发出前就会创建任务记录，状态包括 running、succeeded、failed 和 timed_out；即使客户端断开或 API 超时，提示词、参数、任务 ID 和错误信息仍会保留。

这意味着超时后不要立刻重复生成。先运行 api-draw.cmd list 或在网页刷新历史，查看原任务是否后来变成 succeeded；只有明确为 failed 或 timed_out 时才考虑重试。

故障排查

网页提示 API_DRAW_API_KEY is not set

$env:API_DRAW_API_KEY = [Environment]::GetEnvironmentVariable("API_DRAW_API_KEY", "User")
api-draw.cmd stop
api-draw.cmd open
api-draw.cmd doctor

访问网页的 /api/health 也可以检查 apiKeyConfigured 是否为 true。

PowerShell 提示禁止运行 api-draw.ps1

使用 api-draw.cmd，例如 api-draw.cmd open、api-draw.cmd doctor。

端口被占用

open 和 start 会自动选择附近的空闲端口。查看实际端口：

api-draw.cmd status

MCP 工具没有出现

1. 执行 codex mcp get api-draw
2. 确认 command = "api-draw" 和 env_vars = ["API_DRAW_API_KEY"]
3. 完全退出并重新启动 Codex
4. 在终端执行 api-draw.cmd doctor

开发与测试

npm.cmd run check
npm.cmd test

测试使用本地 Mock API，不会产生真实 API 用量。MCP 测试使用 MCP SDK 的内存传输，覆盖工具发现和 generate_image 调用；真实接口测试使用 api-draw.cmd doctor --live，需要你明确执行。

安全说明

• API Key 只从环境变量或当前用户注册表读取
• 网页仅监听 127.0.0.1，默认不能被局域网访问
• 下载接口使用文件名 basename，不能通过路径穿越读取其他文件
• 上传文件只进入本地临时目录，调用结束后清理
• delete 只删除 API Draw 数据目录内的历史记录和图片