打造專屬ChatGPT：OpenAI Chat Completion API參數解析(20260323更新)

1. API端點

這篇文章主要整理的是 OpenAI 的 Chat Completions API，核心建立回應的端點為：

POST https://api.openai.com/v1/chat/completions

不過到了 2026 年，Chat Completions 已不只是一個建立回應的端點；同一組資源另外還有：

GET    /chat/completions
GET    /chat/completions/{completion_id}
POST   /chat/completions/{completion_id}
DELETE /chat/completions/{completion_id}
GET    /chat/completions/{completion_id}/messages

如果你的需求是建立新回應，主要仍是使用 POST /chat/completions；如果你的需求是查詢先前儲存的 completion，則會用到其他相關端點。官方另外也明確建議：新專案優先考慮 Responses API；但 Chat Completions 目前仍可用，而且在既有專案中仍很常見。

2. OpenAI Python SDK基礎用法

以下是目前較建議的最小範例。若你使用較新的推理模型或 GPT-5.x 系列，建議把原本的 system 訊息改成 developer 訊息；官方文件也明寫，在 o1 與更新模型上，developer message 用來取代舊的 system message。

from openai import OpenAI

client = OpenAI()

completion = client.chat.completions.create(
    model="gpt-5.4",
    messages=[
        {"role": "developer", "content": "You are a helpful assistant."},
        {"role": "user", "content": "Hello!"}
    ],
)

print(completion.choices[0].message.content)
print(completion.usage)

3. 請求參數

本文聚焦在 client.chat.completions.create(...) 與對應的 REST API body 參數。

到了 2026 年，這些參數大致可以分成五類：

1. 基礎輸入：model、messages
2. 輸出控制：response_format、verbosity、max_completion_tokens
3. 抽樣與生成控制：temperature、top_p、frequency_penalty、presence_penalty、stop
4. 工具與串流：tools、tool_choice、parallel_tool_calls、stream、stream_options
5. 平台層功能：reasoning_effort、prompt_cache_key、prompt_cache_retention、safety_identifier、service_tier、store、metadata

4. 回傳結構

Chat Completions 的回傳可分成兩種：

• 非串流：回傳單一 chat.completion 物件
• 串流：回傳一連串 chat.completion.chunk 事件（SSE）

另外要注意，若你開啟 stream_options.include_usage = true，串流時通常會在最後多收到一個帶有整體 usage 的 chunk；這個最後 chunk 的 choices 可能是空陣列，而不是舊文章裡寫的 null。若串流中途中斷，也可能收不到最後的 usage chunk。

5. 為什麼 2026 還要學 Chat Completions？

雖然 OpenAI 對新專案傾向推薦 Responses API，但 Chat Completions 仍然是大量既有系統、舊版 SDK 教學、第三方框架與內部工具鏈常見的介面。理解 Chat Completions 的參數、訊息格式、工具呼叫與串流事件，對維護舊專案、讀懂歷史程式碼、或從 Chat Completions 遷移到 Responses API 都很有幫助。

b-3-1. System message

developer message 是由開發者提供給模型的高優先級指示，用來設定角色、語氣、格式、限制條件、回答規則等。

目前文件明確指出，在 o1 與更新模型上，developer message 用來取代過去的 system message。

格式如下：

{
  "role": "developer",
  "content": "You are a helpful assistant."
}

developer message 的 content 可以是：

• 一般字串
• 由 type: “text” 組成的 content parts 陣列

例如：

{
  "role": "developer",
  "content": [
    {
      "type": "text",
      "text": "你是一位技術寫作者，回答要有條理。"
    }
  ]
}

b-3-2. system message

system message 也是高層級指示訊息，用途和早期 API 中的系統提示相同。不過在較新的模型上，官方已建議優先使用 developer message。

格式如下：

{
  "role": "system",
  "content": "You are a helpful assistant."
}

system message 的 content 也可以是字串或文字 content parts 陣列，但只支援 text 類型。

b-3-3. User message

user message 代表使用者輸入，是最常見的訊息類型。role 固定為 user，content 可以是：

• 一般字串
• content parts 陣列

最簡單的寫法如下：

{
  "role": "user",
  "content": "Hello!"
}

若使用陣列格式，user message 現在支援多種 content part，包含：
text

image_url

input_audio

file

這代表目前的 Chat Completions API 已經支援多模態輸入，不再只限於純文字。

文字輸入範例：

{
  "role": "user",
  "content": [
    {
      "type": "text",
      "text": "請幫我描述這張圖片。"
    }
  ]
}

圖片輸入範例：

{
  "role": "user",
  "content": [
    {
      "type": "text",
      "text": "What is in this image?"
    },
    {
      "type": "image_url",
      "image_url": {
        "url": "https://example.com/image.jpg",
        "detail": "high"
      }
    }
  ]
}

其中 image_url.detail 可用值為：

• auto
• low
• high

音訊輸入範例：

{
  "role": "user",
  "content": [
    {
      "type": "input_audio",
      "input_audio": {
        "data": "BASE64_AUDIO_DATA",
        "format": "mp3"
      }
    }
  ]
}

目前 input_audio.format 支援：

• wav
• mp3

檔案輸入範例：

{
  "role": "user",
  "content": [
    {
      "type": "file",
      "file": {
        "file_id": "file_123"
      }
    }
  ]
}

也可以改用 file_data 直接傳遞 base64 編碼的檔案內容，並搭配 filename：

{
  "role": "user",
  "content": [
    {
      "type": "file",
      "file": {
        "file_data": "BASE64_FILE_DATA",
        "filename": "example.txt"
      }
    }
  ]
}

b-3-4. Assistant message

assistant message 代表模型先前的回覆。在多輪對話時，如果你要保留對話歷史，通常也會把先前 assistant 的回答一併放進 messages 陣列中。

最基本格式如下：

{
  "role": "assistant",
  "content": "Hello! How can I assist you today?"
}

assistant message 的 content 可以是：

• 字串
• 由 text 或 refusal 組成的 content parts 陣列

例如：

{
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "這是一般回覆內容。"
    }
  ]
}

若模型拒絕回答，也可能出現 refusal content part：

{
  "role": "assistant",
  "content": [
    {
      "type": "refusal",
      "refusal": "I can’t help with that request."
    }
  ]
}

assistant message 還可能包含下列欄位：

• refusal
• tool_calls
• function_call（deprecated）
• audio
• name

其中要特別注意的是，當 assistant message 是工具呼叫回應時，content 可以省略，改由 tool_calls 表示模型想呼叫哪個工具。

例如：

{
  "role": "assistant",
  "tool_calls": [
    {
      "id": "call_abc123",
      "type": "function",
      "function": {
        "name": "get_current_weather",
        "arguments": "{\n\"location\": \"Boston, MA\"\n}"
      }
    }
  ]
}

b-3-5. Tool message

tool message 用來把外部工具執行結果送回模型。當 assistant 回傳 tool_calls 之後，你的程式通常會去實際執行工具，再把工具結果用 tool message 放回 messages，讓模型繼續生成最後回答。

格式如下：

{
  "role": "tool",
  "tool_call_id": "call_abc123",
  "content": "The current weather in Boston is 5°C and cloudy."
}

其中：

• role 固定為 tool
• tool_call_id 必填，必須對應 assistant message 中那一筆工具呼叫的 id
• content 可為字串，或文字 content parts 陣列

這樣模型才知道這筆工具結果是對應哪一個工具呼叫。

Tool Call的相關功能請參考〖打造專屬ChatGPT：透過OpenAI Tool Calling深度整合資源〗。

b-3-6. function message

function message 是較舊的格式，屬於 legacy 用法，目前文件仍有保留。它的結構如下：

{
  "role": "function",
  "name": "get_current_weather",
  "content": "{\"temperature\":\"5\",\"unit\":\"celsius\"}"
}

現在較新的做法通常是使用：

• tools
• tool_calls
• tool message

因此 function message 比較偏向舊版相容用途。

d-1. temperature：numbers or null，Optional，Defaults to 1

0-2之間的任意數值，數值越大隨機性越高。通過調整概率分佈的平滑度實現：值越大時，機率分佈會變得更加平坦，模型選擇詞彙時會更隨機且更有創意；值越小時，機率分佈更尖銳，模型更傾向於選擇機率最高的那些詞。

d-2. top_p：numbers or null，Optional，Defaults to 1

0-1間任意數值，相較於temperature的另一種取樣方式，稱為「核心取樣」(nucleus sampling)，模型只考慮部分詞彙，這些詞的累積機率達到指定的`top_p`，其組成的綜合機率視為100%，其他詞則忽略。具體實現是通過按概率從高到低排序，選擇累計機率不超過`top_p`的詞集進行抽樣。

e-1. frequency_penalty：number or null，Optional，Defaults to 0

-2和2之間任意數值，正值會根據新詞在已生成文件中出現的頻率進行懲罰，降低模型逐字重複相同語句的可能性。

e-2. presence_penalty：boolean or null，Optional

-2和2之間任意數值，正值會根據新詞在已生成文件中出現的頻率進行懲罰，增加討論新話題的可能性。

h-1. max_completion_tokens：integer or null，Optional

控制生成的最大token數量。

h-2. n：integer or null，Optional，Defaults to 1

模型回傳結果有幾個版本(choice)，版本越多成本越高。

h-3. logit_bias：map，Optional，Defaults to null

用於調整特定token在生成文本中的出現機率。在數學上，偏差被添加到模型生成的logits中，再進行抽樣。通過為標記指定偏差值，用戶可以增加或減少其被選擇的可能性，從而更好地控制模型生成的結果。這對於引導生成特定風格或內容非常有用。

接收一個JSON object，將tokenizer中的token ID映射到一個-100和100間的值，數值越高出現的可能越高。

h-4. stop：string / array / null，Optional，Defaults to null

最多可以設定4個序列(sequences)，使API停止生成更多的token。像是提到習維尼時，就停止生成更多內容。

i-1. logprobs：boolean or null，Optional，Defaults to false

是否回傳輸出token的對數機率，設定為True時，可以在choices中的logprobs取得資訊。

i-2. top_logprobs：integer or null，Optional

0-20間的整數，當logprobs為True時，控制每個位置上最可能的token數量。

j-1. store：boolean or null，Optional，Defaults to false

是否儲存這次請求的資料，儲存後可以使用OpenAI的model distillation及evals功能。

j-2. metadata：object or null，Optional

開發者定義的資料，能夠在OpenAI Dashboard中用來篩選資料。

j-3. seed：integer or null，Optional。

控制回答隨機性的參數，如果設定為定值，會回傳相同的結果。需要搭配請求API後回傳的system_fingerprint，搭配這個資訊就能夠了解請求結果改變的原因。

j-4. user：string，Optional。

代表終端用戶的唯一標識符，可以幫助OpenAI監控和檢測濫用行為。

k-1. modalities：array or null，Optional

希望模型生成的內容格式，一般都是["text"]，gpt-4o-audio-*可選擇["text", "audio"]。

k-2. prediction：object，Optional

針對預測輸出的設定，可以在預先知道模型回應的大部分內容時大幅提高回應速度。這種情況最常見於僅對大部分內容進行微小更改後重新生成文件的時候。

官方範例：程式碼重構。

{
    "type": "content",
    "content": string or array
}