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 无效或被禁用，不是超时），不在本文讨论范围。
常见原因(按命中概率排序)
- 真实的任务级超时。模型接到了任务，但没能在内部时间预算内跑完。这正是上面展示的
TASK_TIMEOUT场景，在更重的任务上更常见——更长的视频时长、更高的分辨率，或者模型本身短暂过载。 - 504 来自 HiAPI 之外。绝大多数"504"报告其实是客户端自己的 read timeout(HTTP 库等不及就放弃了),或者你和
api.hiapi.ai之间的公司代理、VPN、负载均衡器按自己的超时设置掐断了连接。既然 HiAPI 从不返回 504,这就是客户端或网络侧的配置问题,不是 HiAPI 的故障。 - 任务还在跑,被误判成超时。
queued、handling、archiving都是非终态,这时候error字段根本不存在。轮询一次看到状态不是success,不等于超时。
修复步骤
- 按 taskId 拉取任务,直接读
status和error.code。 不要从客户端代码里一句笼统的异常信息猜原因——调用GET /v1/tasks/{id},看响应体本身。 - 如果
status是"fail"且error.code是"TASK_TIMEOUT":重试。 文档化的修复方式就是这么简单——用新的POST /v1/tasks调用重新提交(拿到一个新的taskId),不需要换账号或换 Key。 - 如果任务本身偏重,先检查输入。 更长的视频时长、更高的分辨率、或者非常庞大/复杂的提示词,都会让模型更接近它的时间预算上限。如果同样的配置反复超时,试试更低的分辨率/时长,或换一个模型。
- 如果你看到的其实是一个裸的
504(没有带error.code的 JSON 响应体),问题在 HiAPI 之外。 检查你自己 HTTP 客户端或 SDK 配置的 read timeout——很多默认值偏短(10-30 秒),在异步流程里本就不该让一次长请求卡住,而是应该分开轮询。同时确认自己是不是走了公司代理、VPN 网关或负载均衡器,它们可能按自己的超时设置和 HiAPI 完全无关地掐断连接。 - 如果
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 传回来——按上面的步骤检查自己的客户端超时设置和网络路径,而不是怀疑账号出了问题。
相关内链
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 任务卡住/超时诊断指南(英文)里关于排队积压等进行中原因的完整拆解。
