如何避免介面超時？

簡短回答

三條黃金法則，覆蓋 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 還是超時？逐層排查

常見疑問

相關文件

聯絡我們