AI API 串流指南：SSE、首輸出與逾時

AI API 串流會在模型生成期間逐步傳回事件，而不是等待完整 Response Body。它能改善感知速度，卻不一定縮短模型運算時間；用戶端還必須正確解析所選端點的事件契約。

第一條規則是讓 Parser 與端點一致。Chat Completions 傳回分段 completion chunk，Responses 則使用具類型的 response event。即使 HTTP 狀態是 200，若解析器期待錯誤格式，畫面仍可能沒有文字。

從未緩衝的請求開始

curl -N -sS https://modelflare.dev/v1/responses \
  -H "Authorization: Bearer $MODELFLARE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"YOUR_RESPONSES_MODEL","input":"Explain SSE.","stream":true}'

先以同一請求關閉串流測試，可把請求驗證問題與串流解析問題分開。模型 ID 應從模型與價格取得。

把 SSE 當作協定處理

Server-Sent Events 是有框架的記錄，不是任意 JSON 片段。正式用戶端應保持 HTTP、Proxy 與 UI 層不緩衝；累積網路片段直到事件完整；處理文字、推理、工具、完成與錯誤事件；保留取消和最終用量；收到終止事件後主動結束。

分開測量延遲

指標	意義
連線與驗證	到達 Gateway 並驗證 Key 的時間
上游 Response Header	選定路由開始回應的時間
首個有效輸出	第一個有用的文字、推理或工具事件
首個可見文字	使用者實際能看到的第一段文字
總回應時間	到完成、失敗或取消的時間

工具呼叫可能早於任何可見文字，因此營運監控更適合使用「首個有效輸出」，體驗分析再看「首個可見文字」。

依階段設定逾時

分別設定連線逾時、Header 或首輸出逾時、串流空閒逾時與整體 Deadline。推理或工具任務的可見文字可能較晚，應依真實工作負載資料設定，而不是套用單一很短的全域逾時。

若下游用戶端、瀏覽器或 Proxy 先關閉連線，Modelflare 可記錄 499。這表示下游在完成前中斷，不能單獨證明模型或渠道失敗。比較 Abort、Proxy 逾時、首輸出時間、模型、群組、請求 ID 與取消時間。

沒有可見文字時的順序

1. 以 "stream": false 重做相同請求。
2. 確認模型支援所選端點。
3. 在 UI 轉換前捕捉原始事件。
4. 檢查是否只有工具或推理事件。
5. 排除中間層緩衝。
6. 確認 Parser 能處理終止事件。
7. 查閱狀態、首輸出、總時間與取消記錄。

非串流正常且原始事件存在時，問題通常位於用戶端解析或渲染。若沒有任何原始事件，繼續閱讀 AI API 錯誤指南。端點選擇則可參考 Responses API 與 Chat Completions。