Responses API 繁體指南

更新時間：2026-08-12

導讀

如果你今天從零整合 OpenAI 的對話能力，官方 文件 指向 Responses API 而非 legacy Chat Completions。Responses 統一文字 / 多模態輸入、工具呼叫與對話狀態，是新功能（託管 web search、file search 等）的預設落點。欄位名、工具列表、model ID、單價以 Responses 指南 與 定價頁 為準——API 仍在快速演進，請用設定項管理 model 與 schema 版本。

定位：Chat Completions 的繼任路徑

OpenAI 將 Responses 作為新整合首選；Chat Completions 進入維護期，新能力優先 Responses。Assistants（Thread / Run）亦向 Responses + Agents SDK 收斂。

能力	Chat Completions	Responses（推薦）
文件主推	否	是
輸入形態	messages[]	instructions + input
輸出形態	choices[].message	output[] + output_text
多模態	支援	同端點，見 Vision
對話狀態	用戶端拼 history	previous_response_id 鏈式引用
託管工具	有限	web search 等（視文件）

實踐結論： 2026 新專案預設 Responses；存量 Completions 計劃 shadow 遷移並保留回滾。

請求—回應模型

POST /v1/responses
  model + instructions + input (+ tools + previous_response_id)
    → output[]: message | function_call | …
    → usage + response.id

欄位	開發者用法
instructions	長期 system 行為、格式約束
input	字串或 items（文字 / 圖片 / 工具結果）
tools	自訂 JSON Schema + 平台託管工具
store	true 時可後續用 id 引用，注意 retention 策略
stream	SSE，改善首 token 體驗

最小可執行範例

from openai import OpenAI

client = OpenAI()
resp = client.responses.create(
    model="gpt-4o",  # 以 Models 頁當前 ID 為準
    instructions="你是簡潔的中文技術助手，回答不超過三句話。",
    input="Responses API 和 Chat Completions 最大區別是什麼？",
)
print(resp.output_text)
print(resp.usage)

curl https://api.openai.com/v1/responses \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-4o","instructions":"You are helpful.","input":"Hi"}'

gpt-4o 僅為占位；替換為 Models 頁當前 ID。

欄位映射速查（Completions → Responses）

Chat Completions	Responses
messages[0] role=system	instructions
messages[-1] role=user	input 或 input items
choices[0].message.content	output_text
tool_calls + 手搓循環	output 中 function_call + 回傳 tool result
response_format: json_object	Responses JSON schema / text.format

遷移時在 Playground 並排對照同一條業務請求，比逐欄位手工翻譯更可靠。

工具呼叫：自訂與託管

自訂 function： 宣告 tools → 模型回傳 function_call → 伺服器端執行 → 結果作為新 input item 再次 create → 直至最終文字。

託管工具： 文件可能提供 web search、file search、code interpreter；啟用前確認資料出境、權限與附加計費（可能高於純 token）。

多 Agent 編排見 Agents SDK 指南；底層仍調 Responses。

串流與冪等

stream = client.responses.create(
    model="gpt-4o",
    input="用四行詩描述 API 設計",
    stream=True,
)
for event in stream:
    pass  # 事件類型以 SDK 為準

帶副作用的工具（寫庫、發郵件、扣款）必須冪等（idempotency key），防止 SSE 斷線重試重複執行。

Shadow 遷移四步

1. 選代表性生產請求，Playground 轉為 Responses JSON
2. Shadow 雙跑：Completions 與 Responses 並行，對比品質、token、延遲
3. 讀流量切 Responses，Completions 保留 2–4 週回滾開關
4. 訂閱 Changelog 追蹤 deprecations

Assistants 存量見 Assistants 指南。

常見組合

場景	棧
RAG	Embeddings 檢索 + Responses 生成
票據 OCR	Vision input items + JSON schema
長對話	previous_response_id 或定期摘要截斷 history

生產清單

• Key 僅伺服器端；timeout + 429 指數退避
• 記錄 response.id 便於 support 工單
• 工具 allowlist + 參數校驗，防 prompt injection
• 監控 token + 託管工具附加費
• 按組織策略設定 store 與資料 retention

常見問題

Chat Completions 會立刻下線嗎？

以官方 Changelog 為準；通常有過渡期，新能力優先 Responses。

只用 output_text 夠嗎？

純文字問答夠；解析 tool calls 或多段 output 需遍歷 output[]。

同 model 下 Responses 更貴嗎？

token 單價一般一致；託管工具可能另計費——用 shadow 對比總帳單。

不用 SDK 可以嗎？

可以；REST 欄位以 API reference 為準，SDK 通常更快跟進新參數。

新 agent 選 Responses 還是 Assistants？

新需求優先 Responses + Agents SDK；勿在新專案重複投資 Thread / Run 模型。

官方資源

• Responses API 指南
• API Reference: Responses
• OpenAI Platform
• API 定價

下一步閱讀

• Agents SDK 與 Apps SDK 入門
• OpenAI API 快速入門
• Assistants API 開發指南
• Embeddings（嵌入）

行動路徑

今天：非串流 Responses 跑通，列印 output_text 與 usage。明天：實作一條自訂 function 的完整 tool 循環。本週：選一條 Completions 流量 shadow 雙跑，輸出遷移時間表。