Responses API 與 Chat Completions 比較

Responses API 與 Chat Completions 都能把輸入送給語言模型，但兩者組織輸入、輸出、工具與串流事件的方式不同。選擇時應先看用戶端與模型共同支援的契約，而不是假設較新的端點自然適用於所有供應商。

最精簡的判斷原則是：

• 程式開發 Agent 或應用程式若原生處理 Responses 項目、工具事件與 Responses 串流生命週期，使用 Responses API。
• 通用聊天用戶端，或供應商以原始 Chat Completions 形式提供 OpenAI 相容能力時，使用 Chat Completions。

請先在模型與價格確認所選模型支援的 API 格式。

協定差異一覽

比較項目	Responses API	Chat Completions
主要輸入	input 與具型別的輸入項目	messages 陣列
輸出模型	具型別的輸出項目與事件	Assistant 訊息選項與增量內容
串流	Responses 事件串流	Chat Completions 區塊串流
工具活動	具型別的工具呼叫與工具輸出項目	掛在 Assistant 訊息上的工具呼叫
適合情境	Agent、程式開發工具、原生 Responses 應用	聊天用戶端與廣泛支援 OpenAI 格式的供應商
模型可攜性	僅限已驗證支援 Responses 的模型	僅限已驗證支援 Chat Completions 的模型

表格描述的是傳輸契約，不代表 Modelflare 會在兩種格式之間轉換每一項供應商功能。

何時適合 Responses API

若用戶端把一次模型執行視為一連串具型別的項目，而非單一 Assistant 訊息，請選擇 /v1/responses。程式開發 Agent 常需要分辨可見文字、推理摘要、函式參數、自訂工具輸入與其他事件，這正是 Responses 的使用情境。

最小請求範例：

curl -sS https://modelflare.dev/v1/responses \
  -H "Authorization: Bearer $MODELFLARE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.6-sol",
    "input": "列出 API 遷移前必須完成的三項檢查。",
    "stream": true
  }'

Responses 串流必須端到端驗證。只懂 Chat Completions 區塊、不懂 Responses 事件的用戶端，即使成功建立連線，也可能無法呈現有效內容。

何時 Chat Completions 更穩妥

應用程式若以 system、user、assistant 與 tool 訊息為核心，或供應商明確提供 OpenAI 相容的 Chat Completions 端點，請選擇 /v1/chat/completions。

curl -sS https://modelflare.dev/v1/chat/completions \
  -H "Authorization: Bearer $MODELFLARE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "YOUR_CHAT_MODEL",
    "messages": [
      {"role": "system", "content": "請簡潔回答。"},
      {"role": "user", "content": "API 健康檢查應驗證哪些項目？"}
    ],
    "stream": true
  }'

對非 OpenAI 供應商，Modelflare 可採用原始 Chat Completions 透傳，讓專屬推理或搜尋控制欄位原樣抵達上游。這項能力的範圍刻意比宣稱「全面支援 Responses」更精確。

不要只憑模型名稱決定

至少要分開確認三件事：

1. API 金鑰能存取模型。 權限取決於金鑰與可用群組。
2. 模型支援該端點。 出現在 /v1/models 不代表兩種格式都可用。
3. 用戶端理解串流。 Responses 事件與 Chat Completions 區塊是不同契約。

任一項不成立時，只改端點路徑可能把原本清楚的相容性錯誤，變成空白或只顯示部分內容的回應。

遷移工具與結構化輸出

正式切換整合之前：

• 比對用戶端使用的工具定義結構；
• 確認工具呼叫 ID 與工具結果的回傳方式；
• 保留明確傳入的 0 與 false；
• 確認哪些供應商專屬欄位必須原樣透傳；
• 測試只有工具呼叫、沒有可見文字的回應；
• 確認用戶端如何判斷結束與用量。

相同 Prompt 產生近似文字，並不足以證明協定相容。有效測試必須涵蓋應用程式實際依賴的功能。

實務選擇流程

1. 在模型與價格選擇模型與群組。
2. 確認支援的 API 格式。
3. 若有對應說明，依照 Modelflare 文件中的用戶端指南設定。
4. 先送出一筆非串流請求。
5. 再送出一筆串流請求。
6. 實測工具或結構化輸出。
7. 在用量記錄核對狀態、時間、Token 與費用。

Responses API 不是 Chat Completions 的通用替代品，Chat Completions 也沒有過時。正確格式是用戶端、所選模型與上游契約三者共同支援的那一種。