OpenAI Chat Completions API：功能與使用指南

建置 AI 驅動的應用程式，不只是讓模型產生回應而已。還需要可靠的方法來管理對話、引導回應，並將所有功能串接到應用程式中。OpenAI Chat Completions API 讓開發人員能掌控 AI 處理訊息與生成答案的方式。如果想了解它的運作原理，以及如何在自己的專案中使用，本文將帶您掌握所需知識。

OpenAI Chat Completions API 可讓開發人員將 OpenAI 的語言模型整合至應用程式與服務中。它會根據一連串訊息產生回應，支援對話、問答、內容生成與文字分析等工作。

Chat Completions 仍受支援。對於新專案，OpenAI 建議使用 Responses API。本指南聚焦於 Chat Completions，說明其訊息格式、請求參數，以及如何搭配相容的 SDK 使用。

不同於接受文字提示詞的舊版 Completions 端點（/v1/completions），Chat Completions 接受結構化的訊息清單。每則訊息都具有角色，例如 developer、user 或 assistant，協助模型解讀指令與對話脈絡。支援的角色和內容類型取決於所選模型。

開發人員可使用 API 建置各種 AI 驅動功能，包括：

• 對話式應用程式：建立可回應使用者訊息的 AI 聊天機器人、虛擬助理與客戶支援系統。

• 內容生成：產生文章、產品說明、電子郵件、摘要及其他書面內容。

• 文字分析：為文字分類、擷取資訊、分析情緒，並辨識文件中的重點。

• 程式設計輔助：產生程式碼片段、說明程式設計概念，並協助開發人員排除錯誤。

• 語言處理：跨不同語言翻譯、改寫、簡化及校對文字。

API 提供彈性的方式，將語言模型連接至既有軟體，讓開發人員無須自行建置及託管語言模型，也能將 AI 生成的回應整合到應用程式中。

Chat Completions API 採用請求與回應的工作流程。應用程式會將包含模型識別碼與訊息清單的請求傳送至 API 端點，所選模型處理輸入後，傳回生成的回應。

基本工作流程包含以下步驟：

1. 準備對話：應用程式蒐集使用者輸入，並將其整理成訊息清單。也可納入先前的對話訊息以提供脈絡。

2. 傳送 API 請求：應用程式會將所選模型與訊息清單，以 POST 請求傳送至 https://api.openai.com/v1/chat/completions。請求使用 Authorization: Bearer <API_KEY> 標頭。Python SDK 的 client.chat.completions.create() 方法會處理此請求結構與驗證。

3. 處理輸入：模型會解讀訊息、考量其角色與內容，並根據提供的脈絡與參數生成回應。

4. 接收回應：非串流請求會傳回包含生成完成內容與中繼資料的 JSON 回應。啟用串流時，API 會傳送一連串伺服器傳送事件（SSE），應用程式會在事件到達時逐一處理。

5. 顯示或處理輸出：應用程式擷取生成的訊息，顯示給使用者，或傳遞給另一個應用程式元件。

此工作流程以 OpenAI Chat Completions API 的請求與回應模型為基礎。

若要有效使用 Chat Completions API，開發人員需要了解其主要請求參數，以及這些參數如何影響模型行為。

model 參數指定由哪個語言模型處理請求。不同模型可能提供不同的功能、回應速度、推理效能與定價。

開發人員應根據工作複雜度、預期回應品質、延遲要求與預算選擇模型。

messages 參數包含對話訊息陣列。每則訊息通常包含 role 與 content 欄位。

常見角色包括：

請選擇模型支援的指令角色；同一組指令不需要同時傳送 system 和 developer 訊息。若要在多輪對話中維持脈絡，請在每次請求中納入相關的對話歷程。相容的服務供應商可能支援不同角色，因此調整整合方式時，請遵循其模型文件。

對於支援此參數的模型與設定，temperature 可控制取樣的隨機性。API 參考文件定義的範圍為 0 至 2，預設值為 1。設定自訂值前，請確認所選模型是否支援此參數。

• 較低的 temperature：產生更聚焦且可預測的回應，適合用於分類、資訊擷取與結構化工作。

• 較高的 temperature：讓生成文字有更多變化，適合用於腦力激盪與創意寫作。

部分推理設定不接受自訂的 temperature 或 top_p 值。對於這些設定，請省略這些取樣參數，改用推理投入程度和輸出限制等受支援的控制項。

在支援的情況下，top_p 會透過核心取樣控制 token 的選擇。它會設定用於選擇候選 token 的累積機率閾值。

例如，值為 0.1 表示模型會考量累積機率質量最高 10% 範圍內的 token。較低的值通常會產生更聚焦的輸出，較高的值則允許更多變化。

OpenAI 建議調整 temperature 或 top_p 其中之一，而非同時變更兩者。

max_completion_tokens 參數會設定模型在回應中可生成的最大 token 數量，適用時也包括推理 token。

設定適當的上限可協助開發人員控制輸出長度及管理 token 用量。若模型在完成回應前達到此上限，完成結果可能會以 length 結束原因結束。

stream 參數決定 API 是一次傳回生成的回應，還是在生成過程中逐步傳回。

• false：生成完成後傳回完整回應。

• true：透過伺服器傳送事件（SSE）將回應資料串流至應用程式。

串流適用於聊天介面及其他應用程式，讓使用者能逐步看到回應出現，而不必等待完整輸出。

response_format 參數會在支援的模型上選擇輸出格式。預設為文字。將 type 設為 json_object 可啟用 JSON 模式，該模式會產生有效的 JSON，但不會強制採用特定的結構描述。請在訊息中加入要求傳回 JSON 的指示。

若需要可預期的欄位與資料類型，請在相容模型上使用以 JSON Schema 為基礎的結構化輸出，並設定 type: "json_schema" 及 strict: true。嚴格模式僅能使用 JSON Schema 支援的子集。處理結果前，請檢查是否有拒絕回應或遭截斷的回應。設定詳細資料請參閱結構化輸出指南。

當模型透過 Chat Completions 支援工具呼叫時，tool_choice 參數可控制工具選擇。是否支援取決於模型及其推理設定；部分較新的模型需要使用 Responses API 才能使用工具。在請求中加入工具前，請先確認這些需求。

常見設定包括：

• none：阻止模型呼叫工具。

• auto：允許模型決定是否呼叫可用工具。

• required：要求模型呼叫一個或多個工具。

此功能支援函式呼叫，讓應用程式能將模型生成的決策連結至外部函式、資料庫及服務。應用程式負責執行請求的函式，並將其結果傳回模型。

請使用 Chat Completions API 參考文件查看參數定義及模型相容性需求。以下 Python 範例使用不含工具的基本文字請求。

開發人員可透過 HTTP 請求或官方 SDK 存取 Chat Completions API。以下範例使用 Python 傳送對話請求並取得生成的回應。

步驟 1：取得 API 金鑰

在 OpenAI API 平台建立 API 金鑰，並確認帳戶可存取所選模型，且具有足夠的 API 額度或計費額度。請將金鑰儲存在環境變數中，而非應用程式原始碼。若使用 macOS 或 Linux，請執行：

請將 YOUR_API_KEY 替換為自己的金鑰。若使用 Windows，請在殼層或系統環境中設定相同的 OPENAI_API_KEY 變數。

步驟 2：安裝 OpenAI Python SDK

使用 pip 安裝官方 Python 程式庫：

步驟 3：初始化 API 用戶端

匯入 SDK 並初始化用戶端。OpenAI() 會自動讀取步驟 1 設定的 OPENAI_API_KEY 環境變數。

步驟 4：傳送聊天完成請求

使用模型和訊息清單呼叫 client.chat.completions.create()。此範例使用 gpt-6-astra、低推理強度，以及總計 4,096 個 token 的生成上限。若帳戶無法使用此模型，請選擇支援 Chat Completions 的模型，並依其文件調整參數。

在此範例中：

• model 用來識別生成回應的語言模型。

• messages 提供指示和使用者輸入。

• reasoning_effort 用於設定支援此參數之模型的推理強度。

• max_completion_tokens 限制生成的 token 數量，包括推理 token。它不保證會產生特定數量的可見文字。

• response.choices[0].message.content 會擷取助理的回應。

處理 API 回應

針對這項非串流請求，API 會回傳包含完成結果和請求中繼資料的 JSON。Python SDK 會將其解析為 ChatCompletion 物件，因此範例會透過 response.choices[0].message.content 這類屬性存取欄位。

重要的回應欄位包括：

finish_reason 欄位可協助開發人員了解生成為何結束。常見值包括 stop、length 和 tool_calls。

開發人員也可以檢查 usage 欄位，以監控輸入和輸出 token 的用量，這有助於估算 API 成本及最佳化應用程式使用情況。

此範例示範基本的文字回應。加入串流、結構化輸出或工具時，請同時更新請求和回應處理邏輯，使其符合所選模型和端點。

對於正在尋找 OpenAI Chat Completions API 替代方案的開發人員，Kimi API 透過與 OpenAI 相容的 API 格式，提供 Moonshot AI 大型語言模型的存取方式。

Kimi 提供 Chat Completions、Responses 和 Messages 介面。以下範例使用其與 OpenAI 相容的 Chat Completions 端點，讓您可沿用上述 SDK 工作流程。設定 Kimi API 金鑰、指定 Kimi 基礎 URL，並選擇支援的模型。請參閱 Kimi 自家的文件，了解模型參數、訊息角色和工具支援。

步驟 1：取得 Kimi API 金鑰

在 Kimi API 平台註冊，並在開發人員主控台建立 API 金鑰。首次發出請求前，請檢查餘額、模型存取權限和帳戶速率限制。

將 Kimi 金鑰儲存在獨立的環境變數中。在 macOS 或 Linux 上，請執行：

請將 YOUR_KIMI_API_KEY 替換為您自己的 Kimi 金鑰。在 Windows 上，請在環境中設定相同的 KIMI_API_KEY 變數。

步驟 2：安裝 OpenAI Python SDK

若尚未安裝 SDK，請執行：

步驟 3：設定 Kimi API 用戶端

使用 Kimi 基礎 URL，以及在步驟 1 設定的 KIMI_API_KEY 變數，建立獨立的 kimi_client。透過 os.environ 讀取金鑰，可讓遺漏的環境變數立即以錯誤顯示。

步驟 4：傳送 Chat Completions 請求

使用 Kimi 用戶端呼叫相同的 SDK 方法。此請求選用 kimi-k3，以 Kimi 支援的 system 角色提供指示，並回傳非串流文字回應。

• 適用於不同工作負載的模型選項：Kimi K3.1 Pro 支援複雜推理、長期程式設計和知識工作。其 HighSpeed 版本具備相同模型能力，但輸出速度更快。上述範例使用 Kimi K3；請查看目前模型清單，了解可用性和遷移指引。

• OpenAI API 相容性：熟悉 OpenAI Chat Completions 格式的開發人員，在整合 Kimi 模型時，可沿用相近的請求結構和支援的 SDK 工作流程。

• 多輪對話：開發人員可提供訊息歷史記錄，以支援具備情境感知能力的對話、虛擬助理和互動式應用程式。

• 串流和函式呼叫：API 支援串流回應和工具呼叫工作流程，讓開發人員能建置互動性更高的應用程式，並將模型連接至外部函式。

• 多模態輸入：視模型能力而定，支援的 Kimi 模型可處理不同輸入類型，包括文字、圖像和影片。

使用 Chat Completions API 時，開發人員可能會遇到與驗證、API 設定、模型可用性或請求限制相關的錯誤。了解這些常見問題，有助於找出問題並讓整合順利運作：

• API 金鑰無效或遺漏：API 金鑰不正確、已過期、已撤銷或未正確設定時，可能發生驗證錯誤，例如 HTTP 401。請確認金鑰有效、環境變數已正確載入，且請求包含適當的驗證憑證。

• API 基礎 URL 不正確：傳送至錯誤端點的請求可能會回傳 404 或連線失敗等錯誤。請確認基礎 URL 符合 API 供應商的文件，且請求使用正確的端點路徑。在 OpenAI 與相容供應商之間切換時，請記得相應更新基礎 URL。

• 模型 ID 無效或不可用：若指定的模型名稱不正確、您的帳戶無法使用該模型，或所選端點不支援該模型，請求可能會失敗。請查看供應商的模型文件，並確認模型 ID 與您的 API 帳戶可用的 ID 相符。

• 超出情境長度：如果輸入訊息和生成輸出的合計長度超過模型的情境視窗，API 可能會拒絕請求。請縮短輸入內容、移除不必要的對話歷史，或在重新傳送請求前摘要較早的訊息。

• 輸出遭截斷：若回應達到 max_completion_tokens 限制，可能會在完成所要求的內容前停止。若支援，請提高 token 限制，或將長篇生成工作拆分為較小的請求。您也可以檢查 choices[].finish_reason，確認回應是否因 length 限制而結束。

• 超出速率限制或配額：對 OpenAI 而言，HTTP 429 可能表示請求或 token 速率限制、支出限制或其他使用限制。重試前請檢查錯誤類型和代碼。若為暫時性的速率限制，請降低請求頻率，並在有提供時遵循 Retry-After，或採用指數退避。

若錯誤表示點數已用盡，或達到帳務或支出限制，請檢查帳戶餘額和帳務設定；重複重試不會恢復存取權。使用 Kimi 或其他相容供應商時，請遵循該供應商的錯誤代碼文件，因為狀態碼和配額規則可能不同。

為了更有效率地偵錯，在變更請求參數前，請先檢查 API 回傳的 HTTP 狀態碼和錯誤訊息。這些細節有助於區分驗證問題、設定錯誤和使用限制。

Chat Completions API 可支援廣泛的應用情境。其結構化訊息格式和可自訂的生成參數，使其同時適用於簡單的文字功能與較複雜的 AI 工作流程。

• AI 聊天機器人與虛擬助理：開發人員可使用 API，為網站、行動應用程式和客服平台建置對話式助理。將先前訊息傳入後續請求後，應用程式便能維持對話情境，並提供更相關的回應。

• 內容創作與文字編輯：API 可依使用者指示生成及轉換文字。應用程式可用它起草部落格文章、撰寫行銷文案、摘要長篇內容、改寫段落，以及依不同受眾和目的調整寫作風格。

• 文字分類與資訊擷取：企業可將 API 整合至處理大量文字的工作流程中。例如，可用於分類客戶意見回饋、辨識情緒、從訊息擷取重要資訊，以及將非結構化內容整理至預先定義的類別。

• 程式設計輔助工具： API 可透過生成程式碼、解釋程式設計概念、提出解決方案，以及協助開發人員找出錯誤，支援軟體開發工具。應用程式也能透過函式呼叫，將模型連接至外部開發工具。

• AI 驅動的企業工作流程： 開發人員可將 API 整合至商業應用程式，自動化重複性的語言相關工作。舉例來說，可處理客戶詢問、產生報告、從文件擷取資訊，以及依據預先定義的指示擬定回覆。

OpenAI Chat Completions API 為開發人員提供實用的方法，將對話式 AI 導入應用程式，打造更實用的使用者體驗。選擇合適的模型、理解其參數，並審慎處理 API 回應，會實際影響應用程式的表現。不過，開發人員在建置 AI 驅動的解決方案時，不必依賴單一供應商。如果想探索其他選項，不妨試用 Kimi API，看看其與 OpenAI 相容的設定是否符合您的開發需求。