HiAPI 任务超时与 504 错误：排查与修复指南

HiAPI 的任务在 GET /v1/tasks/{id} 返回的响应里，有时会出现 "status": "fail"、"error": {"code": "TASK_TIMEOUT", "message": "Task timed out"} —— 注意这层响应本身的 HTTP 状态码是 200，这是 HiAPI 文档化的真实失败状态，意思是任务已经开始执行，但没能在内部时间预算内跑完。如果你看到的不是这种 JSON，而是客户端直接抛出一个裸的 HTTP 504 Gateway Timeout，那它根本不是 HiAPI 的 API 返回的：504 不在 HiAPI 文档化的任何状态码列表里。本文把这两种情况分开讲：真正的 TASK_TIMEOUT 怎么读、怎么修；以及 504 到底是从哪冒出来的。

报错到底长什么样

HiAPI 的任务流程是异步的：POST /v1/tasks 立刻返回一个 taskId，之后你轮询 GET /v1/tasks/{id} 拿结果。只有当 status 到达终态时，error 字段才会出现。一个真正的超时长这样：

{
  "code": 200,
  "message": "success",
  "data": {
    "taskId": "tk-hiapi-xxxxxxxx",
    "model": "gpt-image-2",
    "status": "fail",
    "created": 1777282033,
    "completed": 1777282099,
    "error": { "code": "TASK_TIMEOUT", "message": "Task timed out" }
  }
}

注意这条响应的 HTTP 状态码是 200——轮询这个请求本身是成功的，失败的是任务，失败详情在 data.error 里。这和创建阶段的同步失败不一样（比如余额不足是 402，请求体不对是 400），那类错误会在最初的 POST /v1/tasks 调用上立刻返回，这时任务根本还没被创建。TASK_TIMEOUT 只会发生在一个已经创建成功的任务身上。

而 504 在大多数情况下根本不是一个响应体，它是代理、负载均衡器或某些 HTTP 客户端库在放弃等待任何响应时自己吐出来的状态码。HiAPI 文档化的 HTTP 状态码是 200、400、402、404、409、415、422、503——里面没有 504。如果你看到的其实是 401，那是另一个问题（API Key 无效或被禁用，不是超时），不在本文讨论范围。

常见原因(按命中概率排序)

1. 真实的任务级超时。模型接到了任务，但没能在内部时间预算内跑完。这正是上面展示的 TASK_TIMEOUT 场景，在更重的任务上更常见——更长的视频时长、更高的分辨率，或者模型本身短暂过载。
2. 504 来自 HiAPI 之外。绝大多数"504"报告其实是客户端自己的 read timeout(HTTP 库等不及就放弃了),或者你和 api.hiapi.ai 之间的公司代理、VPN、负载均衡器按自己的超时设置掐断了连接。既然 HiAPI 从不返回 504,这就是客户端或网络侧的配置问题,不是 HiAPI 的故障。
3. 任务还在跑,被误判成超时。queued、handling、archiving 都是非终态,这时候 error 字段根本不存在。轮询一次看到状态不是 success,不等于超时。

修复步骤

1. 按 taskId 拉取任务,直接读 status 和 error.code。 不要从客户端代码里一句笼统的异常信息猜原因——调用 GET /v1/tasks/{id},看响应体本身。
2. 如果 status 是 "fail" 且 error.code 是 "TASK_TIMEOUT":重试。 文档化的修复方式就是这么简单——用新的 POST /v1/tasks 调用重新提交(拿到一个新的 taskId),不需要换账号或换 Key。
3. 如果任务本身偏重,先检查输入。 更长的视频时长、更高的分辨率、或者非常庞大/复杂的提示词,都会让模型更接近它的时间预算上限。如果同样的配置反复超时,试试更低的分辨率/时长,或换一个模型。
4. 如果你看到的其实是一个裸的 504(没有带 error.code 的 JSON 响应体),问题在 HiAPI 之外。 检查你自己 HTTP 客户端或 SDK 配置的 read timeout——很多默认值偏短(10-30 秒),在异步流程里本就不该让一次长请求卡住,而是应该分开轮询。同时确认自己是不是走了公司代理、VPN 网关或负载均衡器,它们可能按自己的超时设置和 HiAPI 完全无关地掐断连接。
5. 如果 status 仍然是 queued、handling 或 archiving,先别重试。 没有任何东西真的失败。更完整的排查可以参考 hiapi 任务卡住/超时诊断指南(英文)。

最小验证示例

curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "input": {
      "prompt": "a single red apple on a white background, studio lighting"
    }
  }'

这会立刻返回一个 taskId:

{ "code": 200, "data": { "taskId": "tk-hiapi-xxxxxxxx" }, "message": "success" }

然后轮询它:

curl -s https://api.hiapi.ai/v1/tasks/tk-hiapi-xxxxxxxx \
  -H "Authorization: Bearer $HIAPI_API_KEY"

正常的任务最终会返回 "status": "success" 和输出结果。真正超时的任务会返回前面展示的 TASK_TIMEOUT 结构。如果你拿到的是一个连接层面的 504、完全没有 JSON 响应体,那就说明响应根本没能从 HiAPI 的 API 传回来——按上面的步骤检查自己的客户端超时设置和网络路径,而不是怀疑账号出了问题。

相关内链

• HiAPI 控制台
• 创建异步任务(API 文档)
• hiapi 任务卡住/超时诊断指南(英文)

FAQ

HiAPI 的 TASK_TIMEOUT 和 HTTP 504 Gateway Timeout 是一回事吗? 不是。TASK_TIMEOUT 是 HiAPI 文档化的错误码,出现在一次正常的 200 响应里,代表任务自己的 status 变成了 fail,意思是任务内部跑超时了。504 是某些代理、负载均衡器、HTTP 客户端库在放弃等待响应时给出的通用 HTTP 状态码;HiAPI 的 API 根本不会文档化或返回 504,所以你看到的字面 504 一定是你和 HiAPI 之间的某个环节,或者你自己的客户端,放弃了等待,不是 HiAPI 服务端的故障。

遇到 TASK_TIMEOUT 该怎么办? 重新提交一个新任务就行。TASK_TIMEOUT 文档化的修复方式就是重试,没有单独的解锁步骤,如果不是同样的输入反复超时,也不需要改提示词或参数。

重试一个超时的任务会被扣两次费吗? HiAPI 文档化的错误码表里没有明确写这一点。如果这对你很重要,去控制台用这个具体的 taskId 查用量记录确认,不要凭假设判断。

我的 HTTP 客户端抛出了一个超时异常,不是 JSON 格式的 TASK_TIMEOUT,是一回事吗? 不是。客户端自己的超时(比如 HTTP 库的 ReadTimeout,或者公司代理返回的 504)意味着你的连接在拿到 HiAPI 任何响应之前就自己放弃了,这不代表任务本身失败了。既然 /v1/tasks 是异步的,常见修法是调高客户端的 read timeout(或者干脆别在初始 POST 上阻塞等待),分开轮询 GET /v1/tasks/{id} 直到看到终态。

任务已经 queued 或 handling 好几分钟了,没有报错,这算超时吗? 还不算。queued、handling、archiving 都是非终态,error 字段要等 status 变成 fail 才会出现。如果任务真的一直不收敛,可以看 hiapi 任务卡住/超时诊断指南(英文)里关于排队积压等进行中原因的完整拆解。