GPT Image-2 × SuperToken 连通性排查与修复(500错误根因)
## 问题现象 配置 `api.supertoken.cc` 的 `gpt-image-2` 渠道后,WorkBuddy 调用图片生成接口返回 **HTTP 500**,但同一 API Key 在 SuperToken 官网(https://creator.supertoken.cc)可以正常生图。 --- ## 根因:两个参数错误(不是服务端问题) SuperToken 的 `/v1/images/generations` 端点对参数有严格校验,**无效参数会返回 500 而非 400**,导致误判为服务端故障。 ### ❌ 错误 1:`quality` 参数 | 错误写法 | 正确写法 | |---------|----------| | `"standard"` | `"low"` | | `"hd"` | `"medium"` | | | `"high"` | > OpenAI 官方 API 支持 `standard`/`hd`,但 **SuperToken 的实现不支持**,必须改用 `low`/`medium`/`high`。 ### ❌ 错误 2:`size` 参数 | 错误写法 | 正确写法 | |---------|----------| | `"512x512"` | `"1024x1024"` | | `"768x768"` | `"1024x1536"` | | | `"1536x1024"` | | | `"2048x2048"` | | | `"3840x2160"` | | | `"auto"` | > SuperToken 不支持小尺寸,`size` 最低为 `1024x1024`。 --- ## 修复步骤 ### Step 1:修改 `models.json` 文件路径:`~/.workbuddy/models.json` ```json { "id": "gpt-image-2", "name": "GPT Image 2", "vendor": "Custom", "url": "https://api.supertoken.cc/v1/images/generations", "apiKey": "sk-你的Key", "supportsToolCall": false, "supportsImages": true, "supportsReasoning": false, "useCustomProtocol": true } ``` **两个关键点:** 1. `useCustomProtocol: true` — 防止 WorkBuddy 错误拼接 `/chat/completions` 2. `apiKey` — 确保在 https://creator.supertoken.cc 能正常生图 ### Step 2:检查 Skill 参数默认值 如果安装了 `auto-image-optimizer` 或 `gpt-image-2-edits` skill,确认其中的参数表: | 参数 | 有效值 | ❌ 无效值 | |--------|----------|-----------| | size | 1024x1024 / 1024x1536 / ... | ~~512x512~~ ~~768x768~~ | | quality | low / medium / high | ~~standard~~ ~~hd~~ | ### Step 3:验证 在 WorkBuddy 中执行:`用 gpt-image-2 生成一张图:a red apple on white background`,成功返回即修复完成。 --- ## 已知限制 | 问题 | 说明 | |------|------| | 最小文件大小 | SuperToken image-2 最小输出约 **760KB**(1024x1024 + low),无法压缩到 400KB 以下 | | 不支持透明背景 | SuperToken 端点不支持 `background: "transparent"`,会返回 500 | | n > 1 | 部分 Key 不支持 `n > 1`,建议每次生成 1 张 | --- ## 快速排查清单 遇到 500 错误,按顺序检查: - [ ] `models.json` 中 `useCustomProtocol` 是否为 `true` - [ ] `quality` 是否为 `low`/`medium`/`high`(不是 `standard`/`hd`) - [ ] `size` 是否为有效值(最低 `1024x1024`,不是 `512x512`) - [ ] API Key 是否在官网能正常生图 - [ ] Skill 文件中的参数表是否已更新 --- *整理:混沌 🔥 | 2026-05-24*

