如何避免接口超时？

简短回答

三条黄金法则，覆盖 90% 的超时问题：

图片类同步接口 timeout 设到 360 秒兜底——图片生成没有异步任务 ID，客户端提前断开 = 照常计费但拿不到图。
推理型模型要留足时间——gemini-3.1-pro-preview、gpt-5.6-sol、gpt-5.5-pro 等模型无论流式还是非流式，总耗时都可能达到几分钟。
别用 CDN 节点跑长请求——api-cf.apiyi.com 走 Cloudflare，超过约 100 秒会返回 524，只适合快速文本调用。

另外：若个别模型频繁出现 429（并发不足），可联系客服排查配额。

一张表看懂该设多少 timeout

调用场景	推荐 timeout	推荐节点	备注
普通文本对话（非推理）	60-120 秒	任意节点	通常几秒内返回
推理型模型（thinking / reasoning）	300-600 秒	`api.apiyi.com` / `vip.apiyi.com`	流式与非流式都可能很慢
长文本输出（万字级）	300 秒以上	`api.apiyi.com` / `vip.apiyi.com`	❌ 不要用 CDN 节点
图片生成 / 编辑	360 秒兜底	`api.apiyi.com` / `vip.apiyi.com`	❌ 不要用 CDN 节点
4K 出图、多图参考	600 秒	同上	详见图片最佳实践

超时断开仍然计费客户端主动断开后，服务端与上游的生成任务仍会跑完，这次请求照常计费。也就是说：timeout 设小了 = 花了钱却拿不到结果。宁可一次性把 timeout 调到安全上限，也不要让请求”快成功了却被自己掐断”。

四个关键点详解

① 图片类同步接口：timeout 设到 360 秒

API易的图片模型全部是同步调用——发出请求后保持连接等待，结果直接在响应体里返回。没有异步任务 ID，也没有轮询接口，断开就丢结果。为什么默认值会误伤：主流 HTTP 客户端默认超时普遍在 30-60 秒，而图片生成是真正的”长请求”：

GPT-Image-2 在 high 质量 + 2K/4K 下实测 3-5 分钟
Nano Banana 系列 4K 出图约 50 秒起步，高峰期更久
多图参考类任务常常超过 5 分钟

实践建议：不清楚具体模型耗时时，统一用 360 秒兜底；4K、多图参考等重任务给到 600 秒。按模型分档的精确推荐值见图片 API 调用须知与最佳实践。

出图偶尔”日志显示 30 秒完成，客户端却等了 5 分钟”，是上游返回尾部数据被扣留导致的，属于正常波动范围——timeout 留足就能正常拿到图。

② 推理型文本模型：流式和非流式都慢

普通文本模型通常几秒内就返回，容易让人误以为”文本调用不用管 timeout”。但推理型（reasoning / thinking）模型是例外：

gemini-3.1-pro-preview
gpt-5.6-sol
gpt-5.5-pro（更贵也更慢）
其他开启了高思考预算（high reasoning effort）的模型

这类模型会先进行长时间的内部推理再产出答案，总耗时达到几分钟是常态。关键提醒：流式输出并不能解决超时问题。很多人以为开了 stream=True 就会立刻有数据，但推理模型在思考阶段可能长时间不吐任何 token，客户端的 read timeout 一样会被触发；而且从首字到最后一个 token 的总时长依旧很长。实践建议：调用推理型模型时把 timeout 设到 300-600 秒，并把思考档位（reasoning_effort / thinking）与预期耗时对应起来——档位越高，需要留的时间越多。

③ Base URL 节点选择：CDN 节点不能跑长请求

API易的 api-cf.apiyi.com 是套了 Cloudflare 全球 CDN 的接口地址。它的优势是全球加速、海外访问延迟低，但存在约 100 秒的请求超时上限，超过就会返回 524 错误。⚠️ 注意：这不只影响图片接口。任何可能超过 100 秒的调用都不适合走这个节点，包括：

❌ 图片生成 / 编辑
❌ 视频生成
❌ 长文本输出（万字级文章、长篇翻译、大段代码生成）
❌ 推理型模型的深度思考任务

✅ 适合：普通文本对话、短文本生成等能在 100 秒内完成的快速调用。实践建议：长请求场景请改用 api.apiyi.com（中国大陆推荐）或 vip.apiyi.com（海外推荐）。完整节点对比见 Base URL 配置指南。

④ 遇到 429 并发不足：联系客服排查

如果超时的同时还伴随大量 429 Too Many Requests，那多半不是 timeout 的问题，而是并发配额问题。并发限制是针对单一模型的，不是整个账号共享。个别模型（尤其是刚上线或供给紧张的模型）可能配额偏低。处理方式：

先实现指数退避重试，避免瞬时打满
若长期、稳定地出现 429，联系本站客服排查——我们可以核查该模型的实际配额并协助调整

并发规则详见 API 可以开多少并发？

代码示例

Python
Node.js
cURL

from openai import OpenAI

client = OpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://api.apiyi.com/v1",  # 长请求不要用 api-cf 节点
)

# 按场景分档设置超时（秒），不要全局用一个值
TIMEOUTS = {
    "text":      120,   # 普通文本
    "reasoning": 600,   # 推理型模型
    "image":     360,   # 图片生成兜底
    "image_4k":  600,   # 4K / 多图参考
}

resp = client.chat.completions.create(
    model="gpt-5.6-sol",
    messages=[{"role": "user", "content": "帮我分析这段代码的复杂度"}],
    timeout=TIMEOUTS["reasoning"],   # 推理模型留足 600 秒
)
print(resp.choices[0].message.content)

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.APIYI_API_KEY,
  baseURL: "https://api.apiyi.com/v1",
  timeout: 600 * 1000,   // 毫秒，推理型模型留 600 秒
  maxRetries: 0,         // 长请求慎用自动重试，避免重复计费
});

const resp = await client.chat.completions.create({
  model: "gemini-3.1-pro-preview",
  messages: [{ role: "user", content: "写一篇 8000 字的技术分析" }],
});
console.log(resp.choices[0].message.content);

# --max-time 控制整个请求的最长时间（秒）
curl https://api.apiyi.com/v1/images/generations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  --max-time 360 \
  -d '{
    "model": "gpt-image-2",
    "prompt": "a serene mountain lake at sunrise",
    "size": "2048x2048"
  }'

长请求慎开自动重试：很多 SDK 默认带 2 次重试。图片和推理任务一旦超时重试，可能变成”扣了三次费、一张图都没拿到”。建议把 max_retries 设为 0，由业务层自己控制重试逻辑。

已经调大 timeout 还是超时？逐层排查

第一步：确认 SDK 的真实 timeout 生效

有些框架会在 HTTP 客户端外再包一层超时。打印实际生效的配置，确认你改的那个参数真的被用上了。

第二步：检查链路上的每一跳

请求链路上任何一层超时小于生成耗时，都会先于你的客户端断开：

自建反向代理：Nginx 的 proxy_read_timeout（默认 60 秒）
云负载均衡：空闲连接超时
API 网关 / CDN：回源超时
Serverless 函数：执行时长上限（很多平台默认 30-60 秒）
任务队列 worker：单任务超时

每一跳都要放宽，只改客户端是没用的。

第三步：确认没有走 CDN 节点

检查 Base URL 是不是 api-cf.apiyi.com。如果是长请求场景，换成 api.apiyi.com 或 vip.apiyi.com。判断依据：报 524 基本可以确定是 Cloudflare 层超时，而不是模型太慢。

第四步：区分超时与并发不足

看错误码：524 / 连接中断是超时问题；429 是并发配额问题。两者的解决方向完全不同。

第五步：查调用日志确认实际耗时

在控制台的调用日志里查看该请求的实际耗时和计费情况，据此反推合理的 timeout 值。

常见疑问

超时断开的请求，能退费吗？

不能。客户端断开后，服务端与上游的生成任务仍然完成了，成本已经真实产生。所以正确做法是一次性把 timeout 调到安全上限，而不是设一个小值再靠重试——重试只会让计费翻倍。

能不能提供异步接口，断线后凭 ID 取回结果？

图片接口目前是原厂透传的同步模式，且我们不记录用户业务数据，因此无法提供”断线后凭 ID 取回”的能力。推荐做法：同步调用 + 合理 timeout + 在自己后台记录任务状态，等价于一个轻量异步队列。详见图片接口是同步还是异步？视频类模型本身是异步任务制，不受此限制。

开启流式输出能避免超时吗？

部分能，但不要依赖它。流式确实能让首字更早到达，降低”整体无响应”的风险。但推理型模型在思考阶段可能长时间不吐 token，read timeout 一样会触发；而且完整输出的总时长并不会变短。正确做法是：流式 + 足够大的 timeout，两者一起用。

timeout 设得特别大会有副作用吗？

对计费没有影响——计费只看实际消耗的 token 和调用，与你等了多久无关。唯一要注意的是业务层的资源占用：长连接会占住一个 worker / 连接池槽位，高并发场景建议用异步 IO 或独立的长任务队列来跑图片和推理请求。

524 和 429 有什么区别？

524：Cloudflare 层的超时，说明你走了 api-cf.apiyi.com 且请求超过约 100 秒。换节点即可。
429：并发或速率超限，与耗时无关。先做指数退避，长期出现请联系客服排查配额。

图片 API 调用须知与最佳实践

各图片模型的 timeout 速查表与输出格式对照

Base URL 怎么填？

四个节点的区别与选择建议

图片接口是同步还是异步？

同步调用模式与客户端任务管理方案

API 可以开多少并发？

各类模型的并发限制与配额申请

联系我们

企业微信客服

扫码添加或点击联系客服超时排查、并发配额申请

邮件咨询

客服邮箱：[email protected]商务合作：[email protected]

网站功能介绍

模型与调用

令牌与日志

企业服务

充值与安全

网络与连接

账号与登录

简短回答

一张表看懂该设多少 timeout

四个关键点详解

代码示例

已经调大 timeout 还是超时？逐层排查

常见疑问

相关文档

图片 API 调用须知与最佳实践

Base URL 怎么填？

图片接口是同步还是异步？

API 可以开多少并发？

联系我们

企业微信客服

邮件咨询

​简短回答

​一张表看懂该设多少 timeout

​四个关键点详解

​代码示例

​已经调大 timeout 还是超时？逐层排查

​常见疑问

​相关文档

图片 API 调用须知与最佳实践

Base URL 怎么填？

图片接口是同步还是异步？

API 可以开多少并发？

​联系我们

企业微信客服

邮件咨询

简短回答

一张表看懂该设多少 timeout

四个关键点详解

代码示例

已经调大 timeout 还是超时？逐层排查

常见疑问

相关文档

联系我们