OpenAI API 的應用開發涉及請求格式、回應驗證、工具結果回填與失敗恢復。Chat Completions 和 Responses 使用不同的資料結構,對話歷史、工具呼叫與串流也各有對應的處理方式。

結構化輸出處理資料格式,工具執行負責外部查詢與業務操作,串流與背景工作則涉及事件和執行狀態。應用程式在這些階段各有驗證與保存需求。

系列與主題索引

目前的工作閱讀方式
建立第一個 Chat Completions 功能先讀(一);再接(二)的功能實作
已經能呼叫,但回傳、用量或紀錄有問題直接查(三)的回傳與診斷
要設計較複雜的結構或業務工具(四)資料模型;(五)業務工具
現有程式要轉向 Responses先完成(六)的遷移對照;再讀新系列
直接以 Responses 建立功能從 Responses(一)開始;接上(二)的工具與資料驗證
串流、取消與長工作要能恢復Responses(三)的狀態與恢復流程

Chat Completions 以 messages 提供完整對話,Responses 以 input/output items 表達文字、推理與工具項目。兩種介面的接續方式和工具資料結構不同,模型可用功能也需和端點一起確認。

Chat Completions API

(一)Chat Completions API 基礎參數解析

Chat Completions 的請求由 model、messages 和生成控制參數組成,回應則包含候選訊息、停止原因與用量。

(二)結構化輸出、Tool Calling 與 Streaming

JSON Schema 約束回答格式,工具由後端執行並回填,串流與多模態則有各自的資料格式。圖片、PDF 和音訊也需配合模型能力處理。

(三)回傳物件、除錯與實務設定

回應的 finish_reason、usage 與串流 chunk 提供完成狀態及用量,請求紀錄則關聯延遲、資料保留設定與版本差異。

(四)Structured Outputs 與複雜 Schema 設計

Pydantic、巢狀及遞迴 Schema 用於描述複雜資料與動態 UI,欄位關係與業務值則由額外的驗證規則處理。

(五)Tool Calling 與業務資料整合

營業額、人流與換匯查詢透過多個業務工具整合,後端驗證授權範圍並回填結果,模型再依資料產生回答。

(六)從 Chat Completions 轉向 Responses API

Chat Completions 與 Responses 在端點、請求欄位、回應項目及對話管理上有所不同,最小遷移程式可用來對照資料結構的變化。

Responses API

技術文件查詢助理使用固定文件資料,分別處理多輪對話、查詢工具、結構化回答與長任務。各項實作也包含失敗狀態、診斷欄位與回歸測試,應用程式驗證和模型品質測試分別記錄。

Responses API 實戰(一):回應解析與對話狀態管理

Response 包含文字、工具與推理項目,回應狀態和完整 output 可用來處理空白回覆、對話接續、歷史重播及上下文成本。

Responses API 實戰(二):工具呼叫與結構化輸出的除錯

工具結果依 call_id 配對,結構化回答經 Schema 與 JSON 解析後,還需核對資料來源、權限和業務值;工具重試則受冪等規則約束。

Responses API 實戰(三):串流、背景任務與失敗恢復

串流以整輪終止狀態判斷生成結果,背景工作透過 response ID 輪詢,事件游標、Webhook 去重與工具紀錄則支援取消和失敗後的恢復。

參數與資料型別索引

查找項目完整說明位置
messages、角色、上下文、model 與生成控制前往對應文章
temperature、top_p、max_completion_tokens、stop、n、懲罰與 logit_bias前往對應文章
response_format、JSON mode、strict schema、tools 與 tool_choice前往對應文章
parallel_tool_calls、stream、stream_options 與工具片段累積前往對應文章
圖片、PDF、audio、modalities 與 prediction前往對應文章
store、metadata、識別欄位、service_tier 與 request log前往對應文章
finish_reason、usage、logprobs、seed 與 system_fingerprint前往對應文章
舊 functions/function_call、max_tokens 與相容性差異前往對應文章
Pydantic、nullable、遞迴結構與 Schema 限制前往對應文章
跨工具資料、授權範圍、金額與幣別驗證前往對應文章
messages → input、response_format → text.format、工具結果格式前往對應文章
output、phase、previous_response_id、conversation 與 compaction前往對應文章
function_call_output、call_id、output_parsed 與業務驗證前往對應文章
typed events、背景工作、sequence_number 與 Webhook前往對應文章

範例環境與模型設定

Chat Completions 的文字與工具程式使用 GPT-6 Sol,工具流程設定 reasoning_effort=none;Responses 程式使用 GPT-6 Astra,推理程度為 low。音訊與 prediction 各使用支援該功能的模型,參數也按對應契約設定。模型可用端點與能力見官方模型指南。

Python 程式使用 OpenAI 官方 SDK,API 金鑰由執行環境提供。回應是否完成、資料是否符合 Schema,以及業務結果是否正確,是三項獨立的檢查;工具往返與錯誤恢復也須保留對應的狀態與執行紀錄。