如需完整的文件索引,請參閱 llms.txt。在文件頁面的網址末尾加上 .md ,即可取得該頁面的 Markdown 版本。
主要導覽
主題

遷移至 Responses API

Responses API 是我們在 Chat Completions 的基礎上發展出的新一代基礎 API,可簡化整合作業,並提供建構智慧體所需的強大基本功能。

我們持續支援 Chat Completions,並建議所有新專案使用 Responses。

關於 Responses API

Responses API 提供統一的介面,讓你建構具備智慧體能力的強大應用程式。它提供下列功能:

Responses 的優點

與 Chat Completions 相比,Responses API 有以下優點:

  • 模型表現更好:使用 GPT-5 等推理模型時,模型在 Responses 上的表現優於 Chat Completions。內部評估顯示,使用相同提示詞和設定時,SWE-bench 的成績提升了 3%。
  • 預設支援智慧體迴圈:在單一 API 請求中,模型可以呼叫多種工具,包括 web_search、image_generation、file_search、code_interpreter、遠端 MCP 伺服器,以及你自訂的函式。
  • 成本更低:Responses 能更有效地利用快取,因而降低成本。在內部測試中,快取利用率比 Chat Completions 高出 40% 至 80%。
  • 可跨輪保留上下文:使用 store: true 即可在各輪互動之間維持狀態,保留推理和工具的上下文。
  • 輸入彈性高:可以透過 input 傳入字串或訊息清單,並透過 instructions 提供系統層級的指示。
  • 加密推理:無須儲存狀態即可使用進階推理功能。
  • 支援未來模型:設計上已考量即將推出的模型。
功能 Chat Completions API Responses API
文字生成
音訊 即將推出
視覺
結構化輸出
函式呼叫
網頁搜尋
檔案搜尋
電腦
程式碼解譯器
MCP
圖像生成
推理摘要

範例

以下範例比較 Responses API 與 Chat Completions API 在特定情境下的用法。

訊息與項目的差異

這兩種 API 都能讓模型生成輸出。呼叫 Chat Completions 時,輸入與結果都是 訊息 陣列,而 Responses API 使用的是 項目。項目是由多種型別組成的聯集,可表示模型的各種動作。message 是一種項目,function_call 和 function_call_output 也各自是一種項目。Chat Completions 將多種用途的資料放在同一個訊息物件中,而 Responses 會將它們區分為獨立的項目,更能反映模型上下文的基本單位。

此外,Chat Completions 可將多個平行生成的結果放在 choices 中傳回,結果數量由 n 參數指定。Responses API 沒有這個參數,每次只傳回一個生成結果。

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 傳回的欄位略有不同。原本會收到 message,改用 Responses API 後,則會收到具備明確型別的 response 物件,該物件有自己的 id。 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 起,在 Chat Completions 中,如果 reasoning_effort 的值不是 none,就無法呼叫工具。
  • 兩種 API 定義結構化輸出的方式不同。請將 response_format 改為 Responses 使用的 text.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" | "user"; content: string }[] = [
  { 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: OpenAI.Chat.Completions.ChatCompletionMessageParam[] = [
  { 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,API 仍會將回應鏈中先前各次回應的所有輸入 Token 按輸入 Token 計費。

4. 決定何時儲存狀態

Responses 預設會儲存回應。新帳戶使用 Chat Completions 時,預設也會儲存生成結果。如要停用任一 API 的儲存功能,請設定 store: false。

部分組織受合規要求或資料保留政策限制,例如必須符合零資料保留(ZDR)要求的組織,無法以保留狀態的方式使用 Responses API。為了支援這些情境,OpenAI 提供加密推理項目,讓工作流程在不儲存狀態的情況下仍能使用推理項目。

如要停止儲存狀態並繼續使用推理功能:

  • 設定 store: false,即可透過 store 欄位停用儲存功能。
  • 保留並再次傳入所有傳回的推理項目。建立回應時,每個推理項目預設都包含 encrypted_content。

API 隨後會傳回加密的推理 Token。你可以像使用一般推理項目一樣,在後續請求中再次傳入這些 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 分別處理使用者介面或協調層所需的事件。

若要以串流方式接收文字,可以監聽的事件包括:

  • 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 Terra,並停用推理。GPT-6 Astra 和 GPT-6.1 Sol 必須透過 Responses API 才能呼叫工具。

網頁搜尋工具
async function web_search(query: string) {
  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-terra",
  reasoning_effort: "none",
  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 Beta 測試期間提供的意見,我們在 Responses API 中做了幾項重要改進,使其更靈活、速度更快,也更容易使用。Responses API 是未來在 OpenAI 平台上建構智慧體的方向。

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