For the complete documentation index, see llms.txt. Markdown versions of documentation pages are available by appending .md to the page URL.
主要導覽

建議

開始使用

核心概念

SDK 與 CLI

資源

舊版 API

API Dashboard
試用 ChatGPT

遷移至 Responses API

Responses API 是我們全新的 API 基礎介面，由 Chat Completions 演進而來，讓整合更簡單，並提供強大的智慧體基礎功能。

我們仍持續支援 Chat Completions，但建議所有新專案使用 Responses。

關於 Responses API

Responses API 提供統一介面，可用來建構具備智慧體能力的強大應用程式。它包含：

Responses 的優勢

相較於 Chat Completions，Responses API 具備多項優勢：

  • 表現更好：使用 GPT-5 等推理模型時，搭配 Responses 能比搭配 Chat Completions 發揮更高的模型智慧。我們的內部評估顯示，在使用相同提示詞與設定的情況下，SWE-bench 表現提升了 3%。
  • 預設具備智慧體能力：Responses API 透過智慧體迴圈，讓模型在單次 API 請求中呼叫多項工具，例如 web_search、image_generation、file_search、code_interpreter、遠端 MCP 伺服器，以及你自己的自訂函式。
  • 成本更低：提高快取利用率，進而降低成本（內部測試顯示，快取利用率比 Chat Completions 提升 40% 至 80%）。
  • 保留上下文狀態：使用 store: true 在各輪互動之間維持狀態，保留推理與工具的上下文。
  • 靈活的輸入方式：透過 input 傳入字串或訊息清單；使用 instructions 提供系統層級的指引。
  • 加密推理：即使選擇不保留狀態，仍可享有進階推理的優勢。
  • 為未來做好準備：已為即將推出的模型做好準備。
能力Chat Completions APIResponses API
文字生成
音訊即將推出
視覺
結構化輸出
函式呼叫
網頁搜尋
檔案搜尋
電腦
程式碼解譯器
MCP
圖像生成
推理摘要

範例

查看 Responses API 與 Chat Completions API 在特定情境下的差異。

訊息與項目的比較

這兩個 API 都能讓你輕鬆透過我們的模型生成輸出。呼叫 Chat Completions 時，輸入與傳回結果都是 訊息陣列， 而 Responses API 使用的是 項目。項目是多種類型的聯集，代表模型可能執行的各種動作。 message 是一種項目類型，function_call 和 function_call_output 也是。Chat Completions 的訊息會將多種用途的內容整合在同一個物件中， 項目則彼此獨立，更能代表模型上下文的基本單位。

此外，Chat Completions 可使用 n 參數，以 choices 傳回多個平行生成的結果。在 Responses 中，我們已移除此參數，每次只會生成一個結果。

Chat Completions API
from openai import OpenAI

client = OpenAI()

completion = client.chat.completions.create(
    model="gpt-6-astra",
    messages=[
        {
            "role": "user",
            "content": "Write a one-sentence bedtime story about a unicorn.",
        }
    ],
)

print(completion.choices[0].message.content)
Responses API
from openai import OpenAI

client = OpenAI()

response = client.responses.create(
    model="gpt-6-astra",
    input="Write a one-sentence bedtime story about a unicorn.",
)

print(response.output_text)

Responses API 傳回的回應欄位略有不同。 你收到的是具有明確類型及自身 id 的 response 物件，而非 message。 Responses 預設會儲存回應。對於新帳戶，Chat Completions 也預設會儲存回應。 使用任一 API 時，若要停用儲存功能，請設定 store: false。

這兩個 API 傳回的物件略有不同。在 Chat Completions 中，你會收到 choices 陣列，每個元素都包含一個 message。在 Responses 中，你會收到標示為 output 的項目陣列。

Chat Completions API
{
  "id": "chatcmpl-C9EDpkjH60VPPIB86j2zIhiR8kWiC",
  "object": "chat.completion",
  "created": 1756315657,
  "model": "gpt-5.5",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Under a blanket of starlight, a sleepy unicorn tiptoed through moonlit meadows, gathering dreams like dew to tuck beneath its silver mane until morning.",
        "refusal": null,
        "annotations": []
      },
      "finish_reason": "stop"
    }
  ],
  ...
}
Responses API
{
  "id": "resp_68af4030592c81938ec0a5fbab4a3e9f05438e46b5f69a3b",
  "object": "response",
  "created_at": 1756315696,
  "model": "gpt-5.5",
  "output": [
    {
      "id": "rs_68af4030baa48193b0b43b4c2a176a1a05438e46b5f69a3b",
      "type": "reasoning",
      "content": [],
      "summary": []
    },
    {
      "id": "msg_68af40337e58819392e935fb404414d005438e46b5f69a3b",
      "type": "message",
      "status": "completed",
      "content": [
        {
          "type": "output_text",
          "annotations": [],
          "logprobs": [],
          "text": "Under a quilt of moonlight, a drowsy unicorn wandered through quiet meadows, brushing blossoms with her glowing horn so they sighed soft lullabies that carried every dreamer gently to sleep."
        }
      ],
      "role": "assistant"
    }
  ],
  ...
}

其他差異

  • Responses 預設會儲存回應。對於新帳戶，Chat Completions 也預設會儲存回應。若要在任一 API 中停用儲存功能，請設定 store: false。
  • Responses API 改善了工具使用能力，為推理模型提供更完整的使用體驗。從 GPT-5.4 開始，當 reasoning_effort 的值不是 none 時，Chat Completions 不支援工具呼叫。
  • 結構化輸出的 API 結構有所不同。在 Responses 中，請使用 text.format 取代 response_format。如需詳細資訊，請參閱結構化輸出指南。
  • 函式呼叫的 API 結構有所不同，包括請求中的函式設定，以及回應中傳回的函式呼叫。如需完整的差異說明，請參閱函式呼叫指南。
  • Responses SDK 提供 output_text 輔助功能，Chat Completions SDK 則沒有。
  • 在 Chat Completions 中，你必須手動管理對話狀態。Responses API 可搭配 Conversations API 持續保存對話，也能透過傳入 previous_response_id 輕鬆串接多個回應。

從 Chat Completions 遷移

遷移包含三項相關變更：將請求傳送至 /v1/responses、從具有明確類型的 output 陣列讀取輸出，以及決定應用程式如何在各輪互動之間延續狀態。

1. 更新生成端點

首先，將生成端點從 post /v1/chat/completions 更新為 post /v1/responses。

如果你未使用函式或多模態輸入，簡單的訊息輸入可在這兩個 API 之間通用：

重複使用簡單的訊息輸入
const context = [
  { role: "system", content: "You are a helpful assistant." },
  { role: "user", content: "Hello!" },
];

const completion = await client.chat.completions.create({
  model: "gpt-6-astra",
  messages: context,
});

const response = await client.responses.create({
  model: "gpt-6-astra",
  input: context,
});

使用 Chat Completions 時，你需要建立 messages 陣列， 並從 completion.choices[0].message.content 讀取模型產生的文字。
使用模型生成文字
import OpenAI from "openai";
const client = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });

const completion = await client.chat.completions.create({
  model: "gpt-6-astra",
  messages: [
    { role: "system", content: "You are a helpful assistant." },
    { role: "user", content: "Hello!" },
  ],
});
console.log(completion.choices[0].message.content);

2. 將訊息對應至項目

Chat Completions 的輸入和輸出皆使用 messages。Responses 則使用 input 和 output 陣列，其中包含具有明確類型的項目。message 是其中一種項目類型，其他類型包括 reasoning、function_call 和 function_call_output。

Chat Completions 概念Responses 對應方式
messages[]input，可以是字串或輸入項目陣列
系統或開發人員指示最上層的 instructions；若需保留既有對話紀錄，也可使用相容的訊息項目
使用者訊息帶有 role: "user" 的輸入訊息項目
助理訊息response.output 中的輸出訊息項目；若自行管理狀態，請將該項目放入 input 傳回
工具或函式呼叫function_call 輸出項目
工具或函式結果function_call_output 輸入項目，透過 call_id 與呼叫建立關聯
使用 n 生成多個結果Responses 不支援此功能；若需要多個候選輸出，請分別傳送請求

若只需要最終文字，請使用 SDK 的 output_text 輔助功能。若工作流程涉及推理、工具或多模態輸出，請逐一走訪 response.output，並依各項目的 type 進行處理。

3. 更新多輪對話

如果你的應用程式有多輪對話，請更新上下文處理邏輯。Responses 提供三種常見的狀態管理方式：

  • 若希望由 OpenAI 管理先前回應的上下文，請使用 previous_response_id。每次請求都要重新傳送固定的 instructions，因為 previous_response_id 不會沿用上一個回應最上層的 instructions。
  • 若需自行管理或刪減上下文，請在下一次請求中傳回先前的 output 項目。
  • 若需要持續保存的對話物件，請使用 Conversations API。

使用 Chat Completions 時，你需要儲存對話紀錄，並在每次請求中傳送累積的 messages 陣列。
多輪對話
let messages = [
  { role: "system", content: "You are a helpful assistant." },
  { role: "user", content: "What is the capital of France?" },
];
const res1 = await client.chat.completions.create({
  model: "gpt-6-astra",
  messages,
});

messages = messages.concat([res1.choices[0].message]);
messages.push({ role: "user", content: "And its population?" });

const res2 = await client.chat.completions.create({
  model: "gpt-6-astra",
  messages,
});

即使使用 previous_response_id，回應鏈中先前所有回應的輸入 Token，仍會在 API 中以輸入 Token 計費。

4. 決定何時保留狀態

Responses 預設會儲存回應。對新帳戶而言，Chat Completions 預設也會儲存回應。若要停用任一 API 的儲存功能，請設定 store: false。

部分組織（例如有零資料保留 (ZDR) 要求的組織）受合規要求或資料保留政策限制，無法以保留狀態的方式使用 Responses API。為支援這些情況，OpenAI 提供加密的推理項目，讓你的工作流程無須保留狀態，仍能享有推理項目的優勢。

若要停用狀態保留功能，同時繼續運用推理：

  • 在 store 欄位中設定 store: false。
  • 保留並在後續請求中重新傳入每個傳回的推理項目。建立回應時，每個項目預設都會包含 encrypted_content。

API 接著會傳回加密的推理 Token，你可以像一般推理項目一樣，在後續請求中將其傳回。 對於 ZDR 組織，OpenAI 會自動強制套用 store: false。當請求包含 encrypted_content 時，系統會在記憶體中將其解密，用來生成下一個回應，然後安全地捨棄。任何新產生的推理 Token 都會立即加密並傳回給你，確保不會持續儲存任何中間狀態。

5. 更新函式定義與輸出

Chat Completions 與 Responses 的函式定義方式有兩個細微但需要注意的差異。

  1. 在 Chat Completions 中，函式定義採用外部標記；在 Responses 中，則採用內部標記。
  2. 在 Chat Completions 中，函式預設採用非嚴格模式。在 Responses 中，若省略 strict，系統會嘗試使用嚴格模式；若無法將結構描述調整為相容格式，Responses 就會改用非嚴格模式，盡力完成函式呼叫，並在傳回的最終工具定義中設定 strict: false。若要明確保留 Responses 的非嚴格模式行為，請設定 strict: false。

右側的 Responses API 函式範例與左側的 Chat Completions 範例在功能上相同。

Chat Completions API
{
  "type": "function",
  "function": {
    "name": "get_weather",
    "description": "Determine weather in my location",
    "strict": true,
    "parameters": {
      "type": "object",
      "properties": {
        "location": {
          "type": "string"
        }
      },
      "additionalProperties": false,
      "required": [
        "location"
      ]
    }
  }
}
Responses API
{
  "type": "function",
  "name": "get_weather",
  "description": "Determine weather in my location",
  "parameters": {
    "type": "object",
    "properties": {
      "location": {
        "type": "string"
      }
    },
    "additionalProperties": false,
    "required": [
      "location"
    ]
  }
}

遵循函式呼叫最佳實務

在 Responses 中，工具呼叫及其輸出是兩種不同類型的項目，透過 call_id 建立關聯。如需進一步瞭解 Responses 中函式呼叫的運作方式，請參閱 函式呼叫文件。

6. 更新結構化輸出定義

在 Responses API 中，結構化輸出定義已從 response_format 移至 text.format：
結構化輸出
const completion = await openai.chat.completions.create({
  model: "gpt-6-astra",
  messages: [
    {
      role: "user",
      content: "Jane, 54 years old",
    },
  ],
  response_format: {
    type: "json_schema",
    json_schema: {
      name: "person",
      strict: true,
      schema: {
        type: "object",
        properties: {
          name: {
            type: "string",
            minLength: 1,
          },
          age: {
            type: "number",
            minimum: 0,
            maximum: 130,
          },
        },
        required: ["name", "age"],
        additionalProperties: false,
      },
    },
  },
  reasoning_effort: "medium",
});

7. 更新串流接收端

Chat Completions 串流會逐步傳回包含 delta 欄位的區塊。Responses 串流則使用具有明確類型的伺服器傳送事件。請更新串流接收端，依每個事件的 type 分別處理 UI 或編排層所需的事件。

處理文字串流時，請監聽下列事件：

  • response.created
  • response.output_text.delta
  • response.completed
  • error

函式呼叫串流也可能發出 response.function_call_arguments.delta 和 response.function_call_arguments.done 等事件。請參閱 Responses 串流指南和 Responses 串流事件參考資料。

8. 升級為原生工具

如果應用程式的使用案例適合使用 OpenAI 原生工具，你可以更新工具呼叫，直接使用 OpenAI 提供的工具。

Chat Completions 不原生支援 OpenAI 託管的工具， 因此你必須自行撰寫工具整合程式碼。 此範例使用 GPT-5.6，因為 GPT-6 Astra 必須透過 Responses API 才能呼叫工具。
網頁搜尋工具
async function web_search(query) {
  const res = await fetch(`https://api.example.com/search?q=${query}`);
  const data = await res.json();
  return data.results;
}

const completion = await client.chat.completions.create({
  model: "gpt-5.6",
  messages: [
    { role: "system", content: "You are a helpful assistant." },
    { role: "user", content: "Who is the current president of France?" },
  ],
  functions: [
    {
      name: "web_search",
      description: "Search the web for information",
      parameters: {
        type: "object",
        properties: { query: { type: "string" } },
        required: ["query"],
      },
    },
  ],
});

9. 檢查常見的遷移錯誤

將程式碼從 Chat Completions 遷移至 Responses 時，請留意下列問題：

  • 讀取 choices[0].message.content，而非 response.output_text 或 response.output。
  • 將每個 output 項目都視為訊息。推理、工具呼叫和函式呼叫各自屬於不同的項目類型。
  • 手動將上下文帶入下一個回應時，遺漏推理、函式呼叫或函式呼叫輸出項目。
  • 傳送函式結果時，未附上對應的 call_id。
  • 在 Responses 請求中使用 response_format，而非 text.format。
  • 沿用 Chat Completions 的串流區塊處理常式，卻未處理 Responses 中具有明確類型的事件。
  • 誤以為使用 previous_response_id 就不會對先前的上下文計費。回應鏈中先前的輸入 Token 仍會按輸入 Token 計費。

逐步推出檢查清單

Chat Completions 仍受支援，因此你可以一次遷移一個使用者流程。

  • 先從簡單的文字生成流程開始。
  • 更新端點、請求主體和輸出處理方式。
  • 決定流程要使用 previous_response_id、手動重送項目，還是 Conversations API。
  • 如果流程採用無狀態模式或 ZDR，請加入 store: false，並在需要跨輪次延續推理上下文時，附上加密的推理項目。
  • 遷移函式定義，並確認函式呼叫輸出包含正確的 call_id。
  • 將結構化輸出的結構描述從 response_format 移至 text.format。
  • 更新串流接收端，以處理 Responses 中具有明確類型的事件。
  • 若 OpenAI 託管的工具適合工作流程，就用它們取代自訂編排。
  • 將更多流量導向 Responses 之前，請先比較行為、延遲、Token 用量和錯誤。

我們建議逐步將所有流程遷移至 Responses API，以使用 OpenAI 最新的功能與改進。

Assistants API

我們根據開發人員對 Assistants API 測試版的回饋，將重要改進納入 Responses API，使其更靈活、更快速，也更容易使用。Responses API 代表未來在 OpenAI 上建構智慧體的發展方向。

Assistants API 已於 2026 年 8 月 26 日正式停止服務，目前已無法使用。請依照遷移指南，將你的整合更新為使用 Responses API。