Image-2 任务轮询怎么写：2–3 秒间隔、终态判断和超时回收

POST 已经返回 code: 200，页面却一直转圈；刷新以后不知道该查哪一笔；网络抖了一下，程序又提交了一次；本地超时了，远端任务过几秒却成功了——这些症状看起来不同，根因常常是同一个：把“提交任务”和“等待任务完成”写成了一步。

图注：提交成功只拿到 taskId，最终图片要靠轮询取得。

截至 2026 年 7 月 18 日，图叮 Image-2 开放平台官方文档给出的标准接入路径是异步提交后轮询，没有给出 webhook 回调接口。提交后拿到字符串 taskId，再查询任务详情。官方建议轮询间隔为 2–3 秒，并要求客户端设置最大等待时长。下面不讨论提示词好不好，也不重复 2K 与 4K 适用场景；只把服务端轮询写成一套能观测、能止损、能恢复的 SOP。

Step 1：先把提交成功和出图成功拆开

调用 POST /open/api/v1/gptImage2/generations 后，先检查响应体里的 code === 200。不要只看 HTTP 状态码，也不要拿 message 文案做程序判断。成功响应的 data 是 taskId，而且必须按字符串保存；它不是安全的 JavaScript Number。这一点如果还没处理，可以先看 2K 与 4K 怎么选 里的任务配置思路，再回到本文收紧任务生命周期。

本地至少要保存这些字段：

{
  "localJobId": "order-20260718-001",
  "taskId": "1902345678901234567",
  "state": "POLLING",
  "submittedAt": "2026-07-18T18:00:00+08:00",
  "lastPolledAt": null,
  "pollCount": 0,
  "resultUrl": null,
  "failureReason": null
}

这里的 POLLING 是你自己的状态，不是服务端枚举。它只表示“本地准备继续查询”。服务端仍可能处于 INIT 或 RUNNING。把两套状态分开，后面才能解释“客户端已经停止等待，但任务仍在远端运行”这种情况。

另外，API Key 只放在服务端。开放平台文档明确要求请求带非空 User-Agent，生产网关缺少该请求头时可能返回非 JSON 的 403 页面。轮询器如果部署在浏览器里，不仅会碰到跨域，还会把账户额度暴露给前端；这条路从架构上就不该走。

Step 2：用五种状态写轮询决策树

任务详情接口是 GET /open/api/v1/gptImage2/tasks/{taskId}。每轮先检查外层 code，再读取 data.status。当前公开状态共有五种：

图注：INIT、RUNNING 继续等，三种终态立即停止轮询。

服务端状态	本地动作	是否终态
INIT	记录仍在排队，等待下一轮	否
RUNNING	记录正在出图，等待下一轮	否
SUCCESS	保存并下载 resultUrl，停止轮询	是
FAILED	保存 failureReason 与可用的 errorCode，停止轮询	是
VIOLATION	按内容违规终态处理，记录 errorCode=10077，停止轮询	是

官方文档建议 2–3 秒查询一次。一个容易维护的基线是 2500 毫秒固定间隔，再给同一进程内的不同任务加少量随机偏移，避免一批任务在同一毫秒同时发请求。随机偏移属于客户端工程策略，不是平台强制口径；真正不能破的是 2–3 秒建议区间和终态判断。

下面是伪代码，重点看分支，不要照抄成前端脚本：

while (Date.now() < deadline) {
  const envelope = await getTask(taskId)
  if (envelope.code !== 200) {
    await retryQueryOrEscalate(envelope.code)
    continue
  }

  const task = envelope.data
  if (task.status === 'SUCCESS') return download(task.resultUrl)
  if (task.status === 'FAILED') return fail(task.failureReason, task.errorCode)
  if (task.status === 'VIOLATION') return rejectForPolicy(task.errorCode)
  if (task.status !== 'INIT' && task.status !== 'RUNNING') {
    return quarantineUnknownStatus(task.status)
  }

  await wait(nextIntervalBetween2And3Seconds())
}
return markLocalPollTimeout(taskId)

未知状态不要当成功，也不要继续无限循环。最稳的处理是把它隔离到人工或告警通道，因为这通常意味着接口枚举升级了，而你的客户端还没跟上。

Step 3：把查询重试和重复提交分成两条路

轮询失败分两类。第一类是“任务已经存在，但这次 GET 没查到结果”，例如临时网络失败、非 JSON 网关页或外层错误码。此时重试查询，不要重新 POST。第二类是“POST 的响应在网络中断时丢了，不知道服务端是否已经受理”。这时才需要提交重试，但必须带同一个 Idempotency-Key 和完全相同的请求体。

官方文档列出的幂等结果很具体：同 Key、同请求体且上次已完成，会返回同一 taskId；仍在处理中可能返回 100044；上次失败可能返回 100045；同 Key 却换了请求体会返回 100043；Key 超过 128 个字符会返回 100047。所以幂等键要在第一次提交前生成并持久化，不能每次重试临时换一个。

这里有一条简单规则：

• 已拿到 taskId：只重试 GET。
• 没拿到 taskId，但 POST 可能已送达：用原幂等键和原请求体重试 POST。
• 想修改 prompt、比例或参考图：新建业务尝试，换新的幂等键，不覆盖旧任务。

图叮侧当前文档说明不会主动替调用方限流，所以并发、查询节奏和重试上限都要由调用方负责。没有上限的 retry 不是可靠性，它只是把一次故障放大成持续请求和积分风险。

Step 4：超时后停止等待，不替服务端判失败

最大等待时长是客户端自己的运营选择，官方没有给出统一秒数。假设你的接口层只愿意同步等 180 秒，可以把 180 秒设为示意 deadline；这不是 Image-2 的固定超时，也不代表服务端会在第 181 秒失败。

本地超时后，建议写 POLL_TIMEOUT 或 WAIT_EXPIRED，保留 taskId、最近一次状态、已轮询次数和最近错误。不要把远端状态伪造为 FAILED，更不要立刻用新幂等键再提交一次。随后由后台回收任务继续做两件事：

图注：本地超时后保留 taskId，再由后台回收远端终态。

1. 用原 taskId 再查详情，确认是否已经进入 SUCCESS、FAILED 或 VIOLATION。
2. 必要时按时间窗读取任务列表，核对本 Key 下是否有仍在运行或已经结束的任务。

回收流程和在线请求要共用同一套终态判断。否则在线轮询认识 VIOLATION，后台对账只认识 SUCCESS/FAILED，违规任务就会永久挂在“处理中”。这类问题比单次报错更难查，因为接口没有坏，坏的是两套状态机不一致。

拿到 SUCCESS 后再下载 resultUrl，并对成图做业务验收。生成成功只说明任务完成，不说明商品结构一定正确。遇到产品轮廓变化，可以沿用 五步判定商品几何失真 的检查法，把任务成功和图片可交付继续分开。

Step 5：按验收表确认轮询器真的可上线

上线前至少做下面 10 项。这里的目标不是写一个“能跑”的 while，而是确认每条异常路径都能停、能查、能恢复。

• 提交成功时，taskId 原样按字符串落库。
• 外层响应只用 code === 200 判成功。
• INIT 与 RUNNING 会继续轮询，间隔保持在 2–3 秒。
• SUCCESS 会保存结果地址并停止轮询。
• FAILED 会保存 failureReason，有 errorCode 时一并记录。
• VIOLATION 被当成独立终态，而不是继续等待。
• 未知状态会告警或隔离，不会被吞掉。
• 查询失败只重试 GET；提交重试复用原幂等键与原请求体。
• 超时只结束本地等待，后台仍能用 taskId 对账。
• API Key 只在服务端，日志会脱敏，所有请求都有非空 User-Agent。

上线前再做三组故障注入：让一次 GET 返回非 JSON，让一个任务停在 RUNNING 直到本地超时，再让一个提交响应丢失但服务端实际已受理。三组都没有死循环、重复提交和状态丢失，才算把轮询链路闭合。

防复发规则可以压成一句：taskId 是任务身份，服务端状态是事实，本地 deadline 只是等待策略。三者不要混成一个字段。要开始接入时，可先登录图叮开放平台控制台确认访问资格并创建 API Key；如果控制台未开放给当前账号，就先按页面引导处理，不要在浏览器里绕过鉴权。