Skip to main content
模型请求可能因为模型耗时、排队、网络、参考文件下载、流式长时间无数据或结果文件回传失败而超时。超时处理要先区分“客户端等不住了”和“平台或上游已经失败”。
前端 timeout 不等于模型请求一定失败。只要你的后端已经把请求发给 Tapapi，就必须结合 HTTP 响应、request_id、用量日志和结果保存状态判断，不能直接无限补跑。

​
常见原因

​
推荐做法

建议从这些默认值开始，再按模型耗时调优：
这些是你的应用侧建议值，不是平台 SLA。真实上游耗时会随模型、尺寸、质量、并发和排队变化。
Tapapi 平台侧的 relay HTTP client 不一定强制设置统一总超时；你的后端仍应根据业务场景设置自己的等待时间、队列超时和补跑规则。

​
流式请求

文本流式请求可能长时间没有新 token，尤其是推理模型、长上下文、工具调用或上游排队。你的客户端需要同时处理三件事： 流式接口的最终用量以服务端记录为准。客户端断开只代表用户不再等待，不一定代表模型没有完成。 部分推理模型可能收到 ping、空 delta 或 keep-alive 事件。这类事件只表示连接仍然存活，不应展示成正文内容，也不应触发重复提交。

​
图片接口建议

图片 URL 返回后建议尽快由你的后端转存到 COS、S3、R2 或 OSS。不要把上游临时 URL 当作长期存储；如果 image_proxy_error 或下载超时，先重试下载和转存，仍失败再带 request_id 联系支持。 当前图片代理和视频结果代理都有有限取回窗口。生成或任务完成后，应尽快由你的后端拉取并转存结果，不要依赖代理 URL 长期可用。

​
504 / 524 怎么处理

504 和 524 通常代表长时间没有拿到最终结果。后端默认会把这类状态视为不适合盲目自动重试的错误，因为重复提交可能造成重复生成、重复排队或对账复杂。 这里说的是客户业务侧补跑策略，不等同于 Tapapi 平台内部的通道重试策略。你的业务代码应先确认没有有效结果，再决定是否补跑。 建议流程：
  1. 保存业务 task_id、请求时间、模型、参数和错误响应
  2. 保存响应头里的 X-Oneapi-Request-Id
  3. 查询你的业务任务状态、控制台用量和结果存储
  4. 如果确认没有成功结果，再由 worker 做最多 1 次补跑
  5. 对慢模型降低并发或改成离线队列
  6. 仍频繁发生时联系支持确认上游容量

​
connection reset / 网络中断

网络中断可以有限重试，但必须有业务幂等设计。图片生成不是幂等计算，同一个 prompt 重跑可能得到不同结果，也可能让账单和用户体验变复杂。 批量任务推荐把状态拆清楚：
只有确认没有有效结果时，才进入 retrying。 托管异步任务有平台任务超时清理，超时后会进入失败和返还流程；但普通图片同步主路径仍建议由你的业务系统维护队列状态、超时状态和补跑次数。