OpenAI Responses API 原生呼叫指南

/v1/responses 是 OpenAI 當前的原生主力端點。官方原話：“While Chat Completions remains supported, Responses is recommended for all new projects.” API易完整支援該端點，base_url 換成 https://api.apiyi.com/v1 即可。本頁基於 OpenAI 官方文件整理（developers.openai.com/api/docs，2026年6月資料），示例均可直接複製執行。

為什麼用 Responses

相比 Chat Completions，官方給出的三個硬數字：

推理更強：同一個推理模型走 Responses 端點，SWE-bench 成績提升約 3%（推理狀態跨輪保持）
快取更省：快取利用率比 Chat Completions 高 40%–80%（官方內部測試），輸入賬單直接受益
工具更多：web_search、code_interpreter 等內建工具只在 Responses 提供

什麼時候仍然選 Chat Completions：你在用現成框架（LangChain、各類客戶端預設走 /v1/chat/completions），或需要用同一套程式碼調 Claude、Gemini 等非 OpenAI 模型 —— 見相容模式呼叫。

被棄用的是 Assistants API（官方計劃 2026年8月26日關停），不是 Chat Completions。兩個端點都會長期支援，只是新功能優先落在 Responses。

快速開始

curl https://api.apiyi.com/v1/responses \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "gpt-5.4",
    "input": "用一句話介紹你自己",
    "instructions": "你是一個簡潔的助手"
  }'

from openai import OpenAI

client = OpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://api.apiyi.com/v1"
)

response = client.responses.create(
    model="gpt-5.4",
    input="用一句話介紹你自己",
    instructions="你是一個簡潔的助手"
)

print(response.output_text)  # SDK 提供的便捷欄位，自動拼接文本輸出

import OpenAI from 'openai';

const openai = new OpenAI({
  apiKey: 'YOUR_API_KEY',
  baseURL: 'https://api.apiyi.com/v1'
});

const response = await openai.responses.create({
  model: 'gpt-5.4',
  input: '用一句話介紹你自己',
  instructions: '你是一個簡潔的助手'
});

console.log(response.output_text);

取結果優先用 response.output_text，不要手寫 output[0].content[0].text —— 推理模型的 output 陣列第一項往往是 reasoning 而不是 message，手寫下標會取錯。

請求引數速查表

引數	型別	預設值	說明
`model`	string	必填	如 `gpt-5.4`、`gpt-5.5`
`input`	string / array	必填	使用者輸入，支援多模態 content 陣列
`instructions`	string	null	系統指令（相當於 system prompt）
`max_output_tokens`	int	null	最大輸出 token（含推理 token）
`reasoning`	object	medium	`{"effort": "none/low/medium/high/xhigh"}`
`text`	object	—	`format`（輸出格式）、`verbosity`（low/medium/high）
`tools`	array	[]	函式 + 內建工具
`tool_choice`	string	”auto”	`auto` / `required` / `none` / 指定工具
`parallel_tool_calls`	boolean	true	是否允許並行工具呼叫
`store`	boolean	true	服務端保留響應物件 —— ⚠️ API易下不可用，見下方多輪對話一節
`previous_response_id`	string	null	鏈式引用上一個響應 —— ⚠️ API易下不生效，多輪請用 `input` 陣列自帶歷史
`conversation`	string	null	持久會話物件 —— ⚠️ API易下不支援（`/v1/conversations` 返回 404）
`background`	boolean	false	非同步後臺執行（長任務 / Pro 模型）
`stream`	boolean	false	流式輸出（語義化事件）
`prompt_cache_key`	string	null	快取路由鍵，提高命中率，見快取計費
`metadata`	object	自定義後設資料

gpt-5 系列推理模型不支援 temperature / top_p，傳了會報錯。控制輸出風格請改用 reasoning.effort 和 text.verbosity。

響應結構

output 是一個 item 陣列，常見三種類型：reasoning（推理摘要）、message（文本回復）、function_call（函式呼叫請求）。精簡後的響應示例：

{
  "id": "resp_abc123",
  "object": "response",
  "status": "completed",
  "model": "gpt-5.4-2026-03-05",
  "output": [
    { "type": "reasoning", "summary": [] },
    {
      "type": "message",
      "role": "assistant",
      "content": [{ "type": "output_text", "text": "你好！我是一個 AI 助手。" }]
    }
  ],
  "usage": {
    "input_tokens": 24,
    "input_tokens_details": { "cached_tokens": 0 },
    "output_tokens": 58,
    "output_tokens_details": { "reasoning_tokens": 40 },
    "total_tokens": 82
  }
}

usage 裡兩個值得盯的欄位：

input_tokens_details.cached_tokens：命中快取的輸入量（按 0.1× 計費）
output_tokens_details.reasoning_tokens：推理消耗（按輸出價計費，調低 reasoning.effort 可控）

多輪對話：自己維護歷史

經 API易呼叫 Responses API，多輪請把完整歷史作為 input 陣列傳入（每條帶 role / content），與 Chat Completions 的做法一致：

resp = client.responses.create(
    model="gpt-5.4",
    input=[
        {"role": "user", "content": "我叫 Alice，請記住。"},
        {"role": "assistant", "content": "好的，我記住了，你叫 Alice。"},
        {"role": "user", "content": "我叫什麼名字？"},
    ],
)
print(resp.output_text)  # 會回答 Alice

服務端會話狀態在 API易下不可用，請勿依賴。 經閘道實測（多模型、含延遲重試）：

previous_response_id：傳了不報錯（返回 200），但下一輪不會記得上一輪內容（input_tokens 僅為本輪量，未帶入歷史）；
GET /v1/responses/{id}：返回 400，無法取回已存響應；
conversation 持久會話物件（/v1/conversations）：返回 404，不支援。

因此 store / previous_response_id / conversation 這幾個服務端狀態引數在 API易上均不要使用，請統一採用上面的「input 陣列自管理歷史」方式。完整跨格式說明見多輪對話實現指南。

多輪不省輸入費：每輪把完整歷史重新發送，全部上下文按輸入 token 全量計費。長對話省錢靠的是緩存摺扣（歷史字首自動命中 0.1× 快取價）—— 詳見快取計費。

推理與輸出控制

reasoning.effort 檔位選型

檔位	適用場景
`none`	簡單問答、格式轉換，要快要便宜
`low`	常規對話、摘要
`medium`（預設）	日常開發的均衡選擇
`high`	複雜程式碼、多步推理
`xhigh`	最難的題，配合 `gpt-5.5` / `gpt-5.4` 使用

response = client.responses.create(
    model="gpt-5.5",
    input="證明根號2是無理數",
    reasoning={"effort": "xhigh"}
)

text.verbosity 輸出長度

low / medium（預設）/ high 控制回答詳略，僅 Responses 端點支援：

response = client.responses.create(
    model="gpt-5.4",
    input="解釋什麼是閉包",
    text={"verbosity": "low"}  # 給簡短版本
)

流式輸出

Responses 的流式是語義化事件，不是 Chat Completions 那種 choices[0].delta 通用塊。核心事件：

事件	含義
`response.created`	響應開始
`response.output_item.added`	新增一個 output item（message / function_call 等）
`response.output_text.delta`	文本增量
`response.function_call_arguments.delta`	函式引數增量
`response.completed`	全部完成（含最終 usage）
`error`	出錯

stream = client.responses.create(
    model="gpt-5.4",
    input="寫一首關於秋天的短詩",
    stream=True
)

for event in stream:
    if event.type == "response.output_text.delta":
        print(event.delta, end="", flush=True)
    elif event.type == "response.completed":
        print("\n\n用量:", event.response.usage)

內建工具一覽

內建工具是 Responses 獨有能力，在 tools 數組裡宣告即可，無需自己實現執行邏輯：

工具	type 值	說明
網頁搜尋	`web_search`	模型自主聯網檢索
檔案搜尋	`file_search`	檢索已上傳的向量庫
程式碼直譯器	`code_interpreter`	沙箱裡跑 Python
計算機使用	`computer_use`	操作虛擬桌面
遠端 MCP	`mcp`	連線遠端 MCP 伺服器
影像生成	`image_generation`	內嵌生圖
工具搜尋	`tool_search`	海量工具動態檢索（gpt-5.4 及之後模型）

web_search 最小示例：

response = client.responses.create(
    model="gpt-5.4",
    input="今天有哪些重要的 AI 新聞？",
    tools=[{"type": "web_search"}]
)
print(response.output_text)

內建工具依賴 OpenAI 服務端執行，API易通道對各內建工具的透傳支援情況以實測為準。函式呼叫（自定義工具）完整支援，見 FC函式呼叫。

Pro 模型與 background 模式

gpt-5.4-pro、gpt-5.5-pro 是面向專業場景的深度推理模型（$30 / $180 每百萬 tokens，僅 svip 分組可用），實務上僅通過 /v1/responses 呼叫。單次請求耗時可達分鐘級，建議配合 background: true 非同步執行：

# 提交後臺任務
response = client.responses.create(
    model="gpt-5.4-pro",
    input="對這份架構方案做深度評審：...",
    background=True
)

# 輪詢取回結果
import time
while response.status in ("queued", "in_progress"):
    time.sleep(10)
    response = client.responses.retrieve(response.id)

print(response.output_text)

Pro 模型價格高、速度慢，定位是”花幾分鐘換一個更靠譜的答案”。日常開發請用 gpt-5.4 / gpt-5.5，沒有明確的深度推理需求不建議上 Pro。

支援的模型與價格

模型	輸入（每 1M tokens）	輸出（每 1M tokens）	說明
`gpt-5.6-sol`	$5.00	$30.00	最新旗艦，1M 上下文，`gpt-5.6` 別名指向它
`gpt-5.6-terra`	$2.50	$15.00	5.6 系列均衡主力
`gpt-5.6-luna`	$1.00	$6.00	5.6 系列輕量款
`gpt-5.4`	$2.50	$15.00	上代主力，1M 上下文
`gpt-5.4-mini`	$0.75	$4.50	輕量高性價比
`gpt-5.5`	$5.00	$30.00	上代旗艦，複雜推理
`gpt-5.2`	$1.75	$14.00	上代主力
`gpt-5.1` / `gpt-5`	$1.25	$10.00	價格友好
`gpt-5.4-pro`	$30.00	$180.00	僅 svip，僅 responses，專業場景
`gpt-5.5-pro`	$30.00	$180.00	僅 svip，僅 responses，專業場景

日期固定版本（如 gpt-5.4-2026-03-05）同步在售，價格與主版本一致。完整列表見模型與價格總覽。

與 Chat Completions 對照

GPT-5.4 及之後的模型（含 gpt-5.6-sol / gpt-5.6-terra / gpt-5.6-luna）在 /v1/chat/completions 上不再支援「工具呼叫 + 推理」同時開啟：請求帶 tools 且 reasoning_effort 非 none（預設 medium 也算）會直接 400，報 Function tools with reasoning_effort are not supported for ... in /v1/chat/completions。這是 OpenAI 的官方限制，本頁的 /v1/responses 端點沒有此限制——這類模型做工具呼叫請直接用 Responses。

從 /v1/chat/completions 遷移過來的欄位對映：

Chat Completions	Responses	說明
`messages` 陣列	`input`	簡單場景直接傳字串
`messages[0]` 的 system	`instructions`	獨立引數
`max_tokens` / `max_completion_tokens`	`max_output_tokens`	—
`response_format`	`text.format`	—
頂層 `reasoning_effort`	`reasoning.effort`	Responses 裡是巢狀物件
`choices[0].message.content`	`output_text`	取結果
無狀態，自己拼歷史	同樣自己拼歷史（`input` 陣列）⚠️ 服務端狀態在 API易下不可用	—
`usage.prompt_tokens`	`usage.input_tokens`	欄位名不同

response = client.chat.completions.create(
    model="gpt-5.4",
    messages=[
        {"role": "system", "content": "你是一個簡潔的助手"},
        {"role": "user", "content": "你好"}
    ]
)
content = response.choices[0].message.content

response = client.responses.create(
    model="gpt-5.4",
    input="你好",
    instructions="你是一個簡潔的助手"
)
content = response.output_text

客戶端支援現狀

為什麼 Cline、Trae 等 VS Code 系 IDE / 外掛大多隻支援 /v1/chat/completions，不支援本頁的 Responses 端點？

chat/completions 是事實上的行業通用協議：第三方閘道、本地推理框架（Ollama / vLLM / LM Studio）、各家非 OpenAI 廠商全都實現它，客戶端寫一套處理邏輯就能接幾百家供應商；而 /v1/responses 目前基本是 OpenAI 專屬方言
Responses 不是「換個 URL」：語義化事件流（不是 delta 拼接）、item 化輸出、推理狀態傳遞都與 chat/completions 完全不同，客戶端需要重寫整個 agent 迴圈，維護成本高
雞生蛋問題：客戶端不做，是因為大多數自定義端點（閘道）不支援 responses；閘道反過來也不急著做。API易已託管 /v1/responses（即本頁），不存在閘道側障礙

截至 2026 年 7 月的主流客戶端支援情況：

客戶端	Responses 支援	說明
Codex CLI	✅ 原生	OpenAI 官方出品，agent 迴圈整個建在 Responses 上，2026 年初已棄用 chat/completions
opencode	✅	OpenAI provider 預設走 Responses
Roo Code	✅（止步 gpt-5.4）	「OpenAI」provider 走 Responses 且支援自定義 Base URL（「OpenAI Compatible」仍是 chat/completions）；已停更，預置模型止步 `gpt-5.4`；可作為外掛裝進 Trae 等 VS Code 系 IDE
Continue	✅	gpt-5 / o 系預設走 responses；已被 Cursor 收購，獨立產品收尾中
Cline	❌	OpenAI Compatible 方式固定 chat/completions，社群 feature request 尚未落地
Trae	❌	自定義模型僅 chat/completions 與 messages 兩種端點

需要 GPT-5.4+「推理 + 工具呼叫」的場景，首選 Codex CLI / opencode，Base URL 指向 https://api.apiyi.com/v1 即可；只用到 gpt-5.4、又想留在 VS Code 系 IDE（含 Trae）裡的，可裝 Roo Code 外掛並選 OpenAI provider。

常見問題

現象	原因與處理
`model_not_supported` 報錯	該模型不支援 responses 端點，換 gpt-5 系列
多輪不記得上文	API易下 `previous_response_id` / `conversation` 服務端狀態不生效，請用 `input` 陣列自帶完整歷史
`output_text` 為空	輸出全是 `function_call` item（模型在要求調函式），檢查 `output` 陣列逐項處理
傳 `temperature` 報錯	gpt-5 推理模型不支援，刪掉改用 `reasoning.effort`
`Function tools with reasoning_effort are not supported ...`（400）	GPT-5.4+ 在 `/v1/chat/completions` 的官方限制（tools 與非 `none` 的 reasoning_effort 互斥），改用本頁 `/v1/responses` 端點即可

產品基礎

基礎 API

圖片 API（官轉）

影片 API（官轉）

多模態理解 API

文本 API

OpenAI Responses API 原生呼叫指南

為什麼用 Responses

快速開始

請求引數速查表

響應結構

多輪對話：自己維護歷史

推理與輸出控制

reasoning.effort 檔位選型

text.verbosity 輸出長度

流式輸出

內建工具一覽

Pro 模型與 background 模式

支援的模型與價格

與 Chat Completions 對照

客戶端支援現狀

常見問題

相關連結

​為什麼用 Responses

​快速開始

​請求引數速查表

​響應結構

​多輪對話：自己維護歷史

​推理與輸出控制

​reasoning.effort 檔位選型

​text.verbosity 輸出長度

​流式輸出

​內建工具一覽

​Pro 模型與 background 模式

​支援的模型與價格

​與 Chat Completions 對照

​客戶端支援現狀

​常見問題

​相關連結

為什麼用 Responses

快速開始

請求引數速查表

響應結構

多輪對話：自己維護歷史

推理與輸出控制

reasoning.effort 檔位選型

text.verbosity 輸出長度

流式輸出

內建工具一覽

Pro 模型與 background 模式

支援的模型與價格

與 Chat Completions 對照

客戶端支援現狀

常見問題

相關連結