# API Draw

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

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

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

## 安装与升级

在本项目目录执行：

```powershell
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 用户环境变量：

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

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

```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 请求超时（毫秒） |

## 一键网页

推荐方式：

```powershell
api-draw.cmd open
```

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

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

服务管理：

```powershell
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

```powershell
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`。安装配置：

```powershell
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 端口。

## 数据位置

默认目录：

```text
%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`

```powershell
$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` 会自动选择附近的空闲端口。查看实际端口：

```powershell
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`

## 开发与测试

```powershell
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 数据目录内的历史记录和图片