第一次接 Image-2 API，7 个接口不用一起上：最小可用链路怎么切

为什么图叮 Image-2 开放平台明明列了 7 个端点，第一版却不该把 7 个全接完？问题不在少写几段代码，而在先确认你这一期要交付哪种结果：能拿到图片、服务重启后能找回任务，还是财务能按 Key 对账。本文的可核对样本就是官方文档中的 7 个端点，不拿“业内通常如此”补空白。结论先报：按 3 + 1 + 3 分三期更稳；接口合同的置信度高，延迟、吞吐和业务峰值没有本文实测样本，不能顺手写成保证。

图注：先做三接口出图闭环，再补恢复和积分运营能力。

底层事实：7 个端点服务的是三类不同结果

图注：七个端点应按能出图、可恢复、可运营分成三层。

根据图叮 Image-2 开放平台官方文档，开放 API 一共列出 7 个端点。官方文档注释记录，这套口径在 2026 年 6 月 9 日按后端实现、字段类型和枚举做过逐项核对。它们不是 7 个同优先级的按钮，可以按交付结果分成三层：

交付层	端点	这一层回答的问题
能出图	GET /capabilities、POST /generations、GET /tasks/{taskId}	当前能传什么，任务是否受理，结果什么时候可取
可恢复	GET /tasks	进程中断或本地记录异常后，怎样重新找到任务
可运营	GET /account/balance、GET /usage、GET /usage/records	余额够不够，毛消耗、退款、净消耗和逐笔流水怎么核对

这张表给出第一个推论：首期范围不该按“文档章节数量”定，而要按最短闭环定。只要一层还不能独立验收，多接几个端点不会让它更完整，故障面反而被摊大。

另一个底层事实是异步。POST /generations 成功后只返回字符串 taskId，并不直接返回图片；调用方还要查询任务详情，直到进入终态。于是“提交成功”和“拿到结果”天然是两个验收点。把它们塞进一次同步请求，接口看着少，实际却把等待、超时和失败恢复藏进了同一个黑盒。

第一期只接 3 个端点：先证明能稳定拿到结果

第一期建议接 capabilities、generations 和任务详情。顺序也有含义。

先读 capabilities。画质、比例、参考图上限和高清开关属于动态能力，不应靠前端常量猜。官方文档当前写明 promptMaxLength 为 16000、maxReferenceImages 为 5，hdEnabled=false 时可用画质只有 1k；真正请求时仍以接口返回为准。如果产品要开放 2K、4K 选项，可以先读2K 与 4K 怎么选，再把界面选项收敛到本次能力响应。

再提交 generations。服务端保存完整 API Key，带 X-Api-Key 和非空 User-Agent 请求头；浏览器不接触密钥。若调用方会因网络抖动重发，同一业务请求要保留稳定的 Idempotency-Key，不能每次超时就换一个新 Key。参考图输入也要在提交前清洗；当业务依赖多张参考图时，可先核对5 张参考图的组织方法，避免把顺序问题误判成模型问题。

第三步查 tasks/{taskId}。本地至少保存字符串 taskId、当前状态、最后查询时间和原始失败信息。进入 SUCCESS 后再读取 resultUrl；FAILED 或 VIOLATION 进入失败分支。resultUrl、costPoints、failureReason、errorCode 都可能缺失，解析器要把“字段不存在”和 null 当成同一种可选状态，不能因为少一个字段就把整个响应判成坏 JSON。

这一期的验收很窄，也很硬：能力选项来自实时响应；提交后拿到字符串任务 ID；服务重启前能轮询到真实终态；成功结果能下载到自己的受控存储；失败保留原始原因。五项过了，才算“能出图”。

第二期补 1 个列表接口：让中断后的任务找得回来

只接前三个端点，正常路径已经闭环，恢复路径还缺一块。假设本地数据库写入发生在上游受理之后、业务提交记录落盘之前，远端已经有任务，本地却可能没有可靠的 taskId。这里的“假设”只是故障建模，不是声称发生过真实事故。

GET /tasks 的价值就在于找回。它按 API Key 隔离、按时间倒序返回任务，支持时间窗和状态参数。接入负责人需要把它做成恢复工具，而不是再造一个首页任务看板：固定左闭右开的时间窗，按字符串解析 total，逐页拉取后用本地业务标识或幂等记录做核对。查询参数里的状态只对当前页起过滤提示作用，total 仍是时间窗内总数；若按状态精确翻页，应拉全量后本地筛选。

第二期通过的信号不是“列表能打开”，而是人为停止服务后，重新启动仍能把未完成任务接回来，并且不会重新提交一份相同任务。这里要分清两个动作：查询失败可以重试 GET；重新提交 POST 要遵守原来的幂等键和请求体。恢复层一旦把“查旧任务”写成“再发一次”，积分风险就从异常分支钻回来了。

第三期再接 3 个积分接口：把可运营性补齐

当调用量还只是开发自测，余额页和对账报表不是首期阻断项。进入小流量生产后，三类信号会变成硬需求：提交前的余额预警、时间窗内的净消耗、逐笔消费与退款的解释路径。这时再接 account/balance、usage 和 usage/records。

三者不能互相替代。balance 是某一刻的可用余额；usage 给出 grossConsume、refund 和 net 汇总；usage/records 才能按 taskId 追到 CONSUME 或 REFUND 明细。官方文档明确这些汇总长整数字段按字符串下发，而流水里的 changeAmount 是带符号数字。若统一强转成 JavaScript Number，不是眼前一定报错，而是把本来清楚的类型合同抹平了。

这一期适合用对账差额验收。业务侧按同一左闭右开时间窗汇总明细，结果应与 net = grossConsume - refund 对齐；若不对齐，先查时间窗、API Key 和分页是否一致，再看任务状态。不要用当前余额倒推某一段时间的消耗，因为充值、其他 Key 和窗口外流水都会改变余额。

这里要把判断收住：7 个端点的字段和关系有官方来源，判断置信度高；“多少并发合适”“多久告警一次”没有统一样本，置信度低，只能由你的请求量、预算和故障成本决定。官方只说明图叮侧当前不主动限流，并建议调用方自行控制并发与重试节奏，这不等于无限并发安全。

边界：分期能缩范围，不能替你制造运行数据

3 + 1 + 3 不是所有团队的固定工期表。只做一次性内部演示，第一期可能已经够用；要给外部客户提供可计费服务，恢复层和对账层通常要在正式放量前一起完成。若业务只消费 1K，也不代表可以把画质列表写死，因为能力响应还承担比例、参考图上限和任务状态枚举的协商职责。

接入前还要守住访问边界。开放平台控制台需要登录，并受当前访问门控约束；创建出的 API Key 只在服务端使用。若当前账号没有控制台访问资格，应按页面门控处理，不能把浏览器直连当作替代路线。更完整的产品边界可参考GPT Image 2 能力边界，先确认任务真的属于 Image-2，再决定是否进入这套 API 分期。

同样的推导还能推广到别的异步付费 API：先找“产出闭环”，再补“恢复闭环”，最后建立“资金与审计闭环”。端点数量会变，三层交付目标不会跟着文档目录乱跑。第一版评审时只问一句：这一期承诺的是能出结果、能恢复，还是已经能长期运营？答案不清，范围就会失控。