Image-2 积分对账 FAQ：grossConsume、refund、net 和流水怎么核对

这份 FAQ 写给两类人：一类负责接 Image-2 API，另一类要回答“这段时间到底用了多少积分”。开发常盯着任务是否成功，运营或财务更关心净消耗；两边若只截一张余额图，好家伙，数字能对上才怪。下面只按当前开放平台官方文档里的字段和接口说，不编客户账单，也不把示例值当成真实消费。

图注：账户余额、Key 汇总和逐笔流水是三层不同数据。

Q：grossConsume、refund 和 net 分别代表什么？

直接给关系式：net = grossConsume - refund。grossConsume 是统计窗口内所有 CONSUME 记录绝对值的合计，refund 是所有 REFUND 记录的合计，net 才是这把 API Key 在该窗口里的净消耗。三项单位都是 Image-2 积分，返回类型均为字符串整数。

根据当前仓库内的开放平台官方文档，汇总示例是 grossConsume="3600"、refund="120"、net="3480"。这组数只用于解释字段，不代表任何用户的实际账单。判断是否对得上时，先核算 3600 - 120 = 3480，再去流水里找构成 3600 的消耗项与构成 120 的退款项。

别把 refund 理解成额外奖励。它表示失败任务退回的积分，作用是冲减毛消耗。若团队只报 grossConsume，成本会被高估；只报 net，又看不出失败和退款频率。对外报净额，对内同时保留三项，信息才够用。

Q：为什么账户余额不能直接当成某个 API Key 的成本？

GET /account/balance 返回账户当前的 Image-2 积分余额；GET /usage 返回当前 API Key 的消耗汇总。一个是时点状态，一个是区间流量，口径不同。

余额还可能同时受到多把 API Key、账户充值、消耗和退款影响。开放平台按 Key 的流水只包含 CONSUME 与 REFUND，账户充值记录 RECHARGE 不归属某一把 Key，不会出现在单 Key 的流水接口里。于是“期初余额减期末余额”并不能稳定还原某一把 Key 的成本。

实操时，把余额当预警指标：低于团队设定阈值就提醒补充积分。把 usage 当成本口径：按 Key、按时间窗统计净消耗。两张表可以互相校验，却不能互相替代。咱也不知道咱也不敢问式的余额截图，适合提醒，不适合结账。

Q：汇总接口和消费流水应该先看哪个？

先看汇总，后查流水。顺序反过来也能算，但会把每次对账都变成逐条加法。

第一步，请求 GET /open/api/v1/gptImage2/usage?from=&to=，记录 apiKeyId、grossConsume、refund、net、from 和 to。第二步，只有在净额异常、退款偏多或双方报表不一致时，再请求 GET /open/api/v1/gptImage2/usage/records，按 CONSUME、REFUND 和 taskId 追明细。

流水接口按时间倒序分页，page 从 1 开始，pageSize 最大 100，响应里的 total 是字符串。自动对账程序应循环到取满 total，不能只抓第一页就宣布“已核完”。如果窗口内明细很多，可以分别拉 type=CONSUME 与 type=REFUND，但最终仍要把两组记录放回同一个时间窗核算。

Q：对账时间窗为什么要用左闭右开？

开放平台的时间参数采用 ISO-8601 本地时间，区间语义是 [from, to)：包含起点，不包含终点。按日对账时可以把当天 00:00:00 作为 from，次日 00:00:00 作为 to；按月也是同理。

官方文档给出的请求示例从 2026-06-01T00:00:00 到 2026-07-01T00:00:00。换成自然语言，就是纳入 2026 年 6 月 1 日零点，排除 2026 年 7 月 1 日零点。下一窗口再从 7 月 1 日零点开始，边界记录不会被两边重复计算。

这里有个常见坑：接口使用的是不带时区后缀的本地时间字符串。团队应先确定统一业务时区，再生成窗口；不要一部分服务按 UTC，另一部分按北京时间拼同一组 from/to。存档时把“请求参数原文”和“内部解释时区”一起留住，后续复盘才不会凭感觉补八小时。

Q：CONSUME 和 REFUND 怎么与 taskId 对上？

每条 UsageRecord 都带 taskId、changeType、changeAmount、beforeAmount、afterAmount、description 和 createdAt。其中 CONSUME 的 changeAmount 为负数，REFUND 为正数。按 taskId 分组，就能看到一次任务先扣积分、失败后再退回的完整轨迹。

图注：同一 taskId 下先记消费，再追加退款并汇总净额。

对账脚本可以做三层检查：记录层验证 afterAmount = beforeAmount + changeAmount；任务层把相同 taskId 的变动求和；窗口层再与 net 比较。某个任务只有 CONSUME 没有 REFUND，不代表系统错了，它可能已经成功；任务状态要回到任务详情接口确认。反过来，看到退款也不要把它当作一次新的收入，它只是原消耗的回退。

需要跨系统关联时，taskId 应全程按字符串保存。它当前看起来像一串雪花数字，但开放平台明确要求不要转成 JavaScript Number。一旦精度被截断，任务详情、消费流水和业务订单就会各自拿着“看起来差不多”的 ID，账当然越对越玄学。

Q：程序里为什么要把汇总值当字符串处理？

开放平台对长整数字段有明确类型约定：apiKeyId、grossConsume、refund、net、分页 total 以及任务的 costPoints 都以 JSON 字符串返回。流水中的 changeAmount、beforeAmount、afterAmount 和账户 balance 则是数字。

强类型代码最好在解码层就分开：汇总字符串先验证为十进制整数，再用支持大整数的类型做加减；流水数字按接口类型接收。不要为了图省事，把所有字段都 Number()，也别把所有字段都当字符串拼接。前者可能丢精度，后者会把 3600 + 120 算成 3600120，画面多少有点喜剧效果。

展示层可以格式化，但原始响应应留档。这样接口类型调整或排查差异时，团队能区分“服务端返回值”“本地解析值”和“页面展示值”，不必对着一张表猜是哪一层改坏了。

Q：团队每天应保存哪些对账字段？

给开发、运营和财务共用的最小记录，建议分成汇总表与流水表。

汇总表保存：API Key 的内部标识或安全前缀、from/to 原文、业务时区、grossConsume、refund、net、拉取时间和接口版本。不要保存完整 API Key；它只应在服务端安全环境使用。控制台本身需要登录，并且当前只对白名单用户开放。

流水表保存：taskId、changeType、changeAmount、beforeAmount、afterAmount、description、createdAt，再加本次拉取的页码与批次号。每天先验证三项汇总关系，再抽查或全量核对流水，发现差额时定位到 taskId。等这套记录稳定后，成本预警、退款率观察和异常重试复盘才有同一份底账。

如果还要判断 2K、4K 的选择是否值得，可以接着看 GPT Image 2 的 2K vs 4K 决策规则；需要先确认能力边界，则读 GPT Image 2 能做与不能做的范围。对账 FAQ 只回答“积分怎么核”，不替代画质选型和能力验证。