Image-2 API 参数别写死：用 /capabilities 动态生成画质和比例选项

先把四种接法摆上计分板：参数全写死，开发最快、后续最脆；启动时拉一次，能跟上当天状态，却怕进程常驻；每次打开页面都拉，最鲜活，但会把一次普通操作变成额外网络依赖；服务端按账号缓存并在关键错误后刷新，代码略多，却把准确性、延迟和降级空间放在了同一条链路里。

这不是“实时一定比静态高级”的争论。真正的问题是：Image-2 的可用画质既有产品规则，也有账号状态；比例既有固定字典，也有高清跟随原图的条件。如果客户端只记住某次文档里的 1k / 2k / 4k，很容易把用户当前不能用的选项照样亮出来。按钮很漂亮，提交才报错，这种体验最伤信任。

根据图叮仓库内开放平台官方文档，本文在 2026 年 7 月 18 日核对了 /capabilities 的当前字段。接口会返回 qualities、各画质对应的 aspectRatios、defaultQuality、defaultAspectRatio、promptMaxLength、maxReferenceImages、hdEnabled、hdFollowSourceByAuto、creditUnit 和 taskStatuses。这些是下面四种方案的统一对比依据，不是根据旧文章或界面截图猜出来的。

四种接法放在一起，差别不只是一趟请求

图注：四种参数接法在准确性、延迟和稳定性上取舍不同。

接法	首屏延迟	能否反映账号高清权限	服务异常时能否继续	主要风险
本地硬编码	最低	不能可靠反映	能	展示无效选项，规则变更后整体漂移
进程启动时拉一次	低	能，直到缓存过期	视启动结果而定	长驻进程拿着旧能力不放
每次页面或任务前拉取	较高	能	较弱	能力接口抖动会阻断本来可提交的任务
服务端短缓存 + 错误触发刷新	低	能	能	需要设计缓存键、失效和保守降级

方案一，全部硬编码。 它适合一次性脚本，前提是脚本由同一个人运行、失败后能立刻改代码，并且不把选项暴露给普通用户。生产控制台不适合这么做。官方文档列出了 1K 推荐比例，也列出了 2K/4K 的 15 个具体比例；可用户能否提交高清，仍要看 qualities 和 hdEnabled。把字典抄全，不等于拿到了当前账号的能力。

方案二，进程启动时拉一次。 这比硬编码好一大截。短命令行任务、一次性批处理或每次发布都会重启的服务，可以接受这种做法。问题出在常驻进程：它早上启动时读到 hdEnabled=false，下午账号开通高清，页面仍只展示 1K；反过来也一样，权限或服务状态变化后，旧缓存可能继续放出无效选项。

方案三，每次都拉。 数据最新，却把能力查询变成了提交链路的硬依赖。页面每次展开画质下拉框都请求一次，用户会感到选项忽快忽慢；批量任务如果每张图都查询，更是在重复做同一件事。官方文档说明图叮侧当前不主动限流，但这不等于客户端应该制造无意义流量，更不等于能力接口短暂失败时整条业务必须停下。

方案四，服务端短缓存并允许强制刷新。 这是更适合正式产品的落点。缓存键至少要区分环境与 API Key 身份；不要用完整密钥当日志或浏览器缓存键，可以使用服务端内部的 Key ID、不可逆摘要或受控别名。正常请求命中短缓存，账号切换、Key 更换或收到能力相关错误时强制刷新。它不是最省代码的方案，却最少把用户推到“先点、再报错”的死胡同。

真正要动态的，是可选集合与条件，不是把整个文档搬进接口

最容易写错的一点，是看到 aspectRatios 里有 2k、4k 两组，就直接把高清选项显示出来。根据同一份官方文档，当 hdEnabled=false 时，qualities 只包含 1k；2K/4K 的比例列表仍可能返回，作用是提前告知字典，不代表当前 Key 已经能用高清。因此，画质下拉框应以 qualities 为准，比例下拉框再读取所选画质对应的数组。

hdFollowSourceByAuto 也不能只看名字猜。当前合同里，高清开启且该字段为 true 时，2K/4K 可以用 aspectRatio:"auto" 配合参考图，让服务端按首张参考图映射到最近的高清比例。没有参考图会兜底成 1:1；参考图不可访问、被安全策略拒绝或不是图片，会在扣费前返回 100049。如果字段为 false，界面就不该承诺“高清跟随原图”。

另外两组数字值得直接从响应读取：promptMaxLength 当前为 16000，maxReferenceImages 当前为 5。根据官方文档核对，这两项都属于能力返回值。前端可以据此限制输入并给出计数提示，服务端仍要再次校验；只做前端校验，会让脚本调用和旧客户端绕过限制。

如果你还不熟悉模型本身适合做什么，可以先看截至 2026-04 的 GPT Image 2 能力边界。那篇讲生成结果的边界，本文讲 API 参数的协商边界，两者不要混成同一张“能力表”。涉及高清档选择时，2K 与 4K 的任务选择建议更适合作为业务判断；/capabilities 只回答当前能选什么，不替你判断该不该多花积分。

推荐链路：先协商，再校验，提交失败后只刷新一次

图注：先协商并缓存能力，提交遇到能力错误只刷新一次。

一条稳妥链路可以分成五个动作。

1. 服务端拿当前 API Key 调用 GET /open/api/v1/gptImage2/capabilities，浏览器不接触完整 Key。
2. 用环境、Key 身份和产品版本组成缓存键，保存响应与获取时间。缓存时间不必追求绝对统一，重点是短、可失效、能观察。
3. 前端只展示 qualities 中存在的画质；用户选定画质后，再展示 aspectRatios[quality] 的比例。
4. 提交前同时做客户端提示与服务端硬校验。客户端负责少走弯路，服务端负责不信任输入。
5. 若提交返回 10073、10074 或 10075，服务端清掉该 Key 的能力缓存、重新拉取一次，再决定提示用户改参数还是稍后重试；不要无限刷新，也不要把所有 9999 都当能力变化。

伪代码可以保持很短：

const caps = await capabilityCache.get(keyIdentity, { ttl: 'short' });
assert(caps.qualities.includes(input.quality));
assert(caps.aspectRatios[input.quality]?.includes(input.aspectRatio));

const result = await submit(input);
if ([10073, 10074, 10075].includes(result.code)) {
  capabilityCache.invalidate(keyIdentity);
  return explainWith(await fetchCapabilities());
}
return result;

这里故意没有写死缓存分钟数。能力变化的频率、控制台访问量和可接受延迟不同，固定数字容易装成普适答案。真正不能省的是三个边界：缓存必须按 Key 隔离，失效必须可控，失败后最多做一次针对性刷新。

降级不是把所有选项都打开，而是保留最后一次可信集合

能力接口暂时不可用时，有两种常见错误动作。第一种是把 1K、2K、4K 全放出来，理由是“先让用户试”。这会把服务端已知的不确定性转嫁给用户。第二种是把生成入口全部锁死，即使系统刚刚还有一份未过期或刚过期的可信缓存。前者太冒进，后者太僵。

更稳的顺序是：有最近一次成功响应，就显示该集合并标记“能力信息可能延迟”，提交仍按服务端结果为准；完全没有缓存，就只给官方默认的保守路径，或明确提示能力读取失败，不承诺高清。若你的业务必须在断网状态组装请求，可以把文档字典作为只读兜底，但要把它标成“语法可选值”，不能冒充“当前账号可用值”。

参考图也要保留同样的诚实边界。接口允许最多 5 张，不代表放满 5 张一定更好。需要判断每张参考图承担什么作用时，可以接着看5 张参考图的组合方法；而在 API 层，只需保证数组数量、URL 可访问性与 hdFollowSourceByAuto 条件一致。

你属于哪种接入，答案会不同

内部脚本只有一个维护者、每次运行都能看日志，启动时拉一次通常够用；面向多个账号的 SaaS 控制台，服务端短缓存加错误触发刷新更合适；离线工具可以保留静态字典，但必须把“接口语法”与“账号权限”分开显示；高并发批处理则应在批次开始时协商一次，批内复用，遇到明确能力错误再中止并刷新。

真正的分水岭不是项目大不大，而是失败由谁承担。如果失败只影响开发者本人，简单方案更省成本；如果无效选项会让普通用户付出等待、积分误解或批量返工，能力协商就不是锦上添花。它是在按钮亮起来之前，先把产品能做什么说实话。