OpenAI Responses

使用 OpenAI Responses 相容 API 建立文字、圖片、工具呼叫和推理回應。

Responses API 使用 Typed Items 統一表達文字、圖片、檔案、工具呼叫和推理結果，適合需要多模態輸入、內建工具、有狀態互動或語意化串流事件的應用程式。不同模型可使用的 Item 型別、工具和進階欄位可能不同，請以目前帳戶可見模型及實際呼叫結果為準。

POST/v1/responses

根據文字、圖片、檔案或 Typed Input Items 建立模型回應。API 可以傳回訊息、推理項和工具呼叫等不同型別的 Output Items，並支援透過 SSE 傳輸語意事件。

模型是否支援圖片、內建工具、推理、狀態關聯或結構化輸出，取決於目前帳戶可見模型及其上游供應管道。建議先完成最小文字請求，再逐項啟用進階欄位。

授權

bearerAuth

授權Bearer <token>

在 Authorization Header 中使用 Bearer your-api-key。

傳遞位置: header

請求主體

Responses 使用 Typed Items 表達輸入、工具和輸出。請依任務選擇檢視模式；欄位是否生效取決於模型與供應管道。

application/json

文字輸入

最直接的方式是將字串傳入 input，也可以使用訊息形式的 Typed Items。

model: 目前 API Key 可見且支援 Responses 的模型 ID。
input: 字串或 Typed Input Items 陣列。
instructions: 僅套用於本次回應的高階指令。

application/json

{
  "model": "MODEL_ID",
  "input": "請用三句話介紹你自己。"
}

基礎文字回應。input 可以直接使用字串，也可以傳入 Typed Input Items。

background?boolean|null

是否在背景執行回應。背景模式的可用性取決於模型、供應管道與帳戶權限。

預設值false

context_management?array<>|null

目前請求的上下文管理設定，例如在達到指定 Token 門檻時進行壓縮。

conversation?string||null

此回應所屬的 Conversation。可以傳入 Conversation ID 或包含 id 的物件；不能與 previous_response_id 同時使用。

model?string

要使用的 Responses 文字模型 ID。請從目前 API Key 可見的模型中選擇。

長度1 <= length

input?text input|array<||||||||||||||||||||||||||||||>

文字輸入。可以直接傳入字串，也可以傳入訊息和其他 Typed Items。

include?array<>|null

指定需要附加到回應中的擴充資料。

instructions?string|array<||||||||||||||||||||||||||||||>|null

作為本次回應高層指令使用的系統或開發者訊息。使用 previous_response_id 時，上一回應的 instructions 不會自動繼承。

max_output_tokens?integer|null

回應可以生成的 Token 上限，包括可見輸出與推理 Token。

max_tool_calls?integer|null

本次回應能夠處理的內建工具呼叫總數上限，而不是每種工具各自的上限。

範圍0 <= value

metadata?|null

附加到回應物件的鍵值資訊。鍵最長 64 個字元，值最長 512 個字元。

欄位數properties <= 16

parallel_tool_calls?boolean|null

是否允許模型平行執行工具呼叫。

預設值true

moderation?|null

對回應輸入和輸出執行審核的設定。

previous_response_id?string|null

前一個 Response 的唯一 ID，用於繼續有狀態互動。不能與 conversation 同時使用；上一回應的 instructions 不會自動繼承。

prompt?|null

已儲存的 Prompt 模板及其變數引用。

prompt_cache_key?string|null

用於提高相似請求的提示快取命中率，並替代 user 的快取用途。

prompt_cache_options?|null

請求級提示快取設定。內容區塊可以使用 prompt_cache_breakpoint 標記顯式快取邊界。

prompt_cache_retention?string|null

已棄用

已棄用，請使用 prompt_cache_options.ttl。該欄位保留用於舊快取保留策略相容。

可用值

"in_memory"
"24h"
null

reasoning?|null

推理模型的設定。僅適用於支援該能力的模型。

service_tier?string|null

請求使用的服務層級。請求值與回應實際傳回值可能不同，例如請求 fast 時回應可能傳回 priority。

預設值"auto"

可用值

"auto"
"default"
"flex"
"scale"
"priority"
"fast"
"ultrafast"
null

safety_identifier?string|null

用於安全與濫用監測的穩定最終使用者識別碼。建議先進行雜湊處理，避免傳遞可識別個人身分的資訊。

長度length <= 64

store?boolean|null

是否儲存生成的回應。實際儲存、讀取與保留期以平台能力為準。

預設值true

stream?boolean|null

為 true 時，透過 Server-Sent Events 傳回 Responses 語意事件。

預設值false

stream_options?|null

串流回應設定。僅在 stream 為 true 時使用。

temperature?number|null

取樣溫度。通常只調整 temperature 或 top_p 中的一項。

範圍0 <= value <= 2

預設值1

text?

tool_choice?||||||||

控制模型是否以及如何選擇工具。

tools?array<|||||||||||||>

模型可以使用的內建工具或自訂函式。實際支援範圍取決於模型與供應管道。

top_logprobs?integer|null

傳回每個輸出 Token 位置最可能的候選 Token 數量，取值為 0～20。

範圍0 <= value <= 20

top_p?number|null

核取樣機率總和。通常只調整 top_p 或 temperature 中的一項。

範圍0 <= value <= 1

預設值1

truncation?string|null

已棄用

上下文超過視窗時的截斷策略。disabled 會讓超限請求失敗。

預設值"disabled"

可用值

"auto"
"disabled"
null

user?string

已棄用

已棄用。安全識別碼請使用 safety_identifier，快取分組請使用 prompt_cache_key。

Responses 的工具、狀態、推理和多模態功能可能因模型與上游供應管道而異；建議先完成最小文字請求，再逐項啟用進階欄位。

回應主體

`application/json`

curl -X POST "https://example.com/v1/responses" \  -H "Content-Type: application/json" \  -d '{    "model": "MODEL_ID",    "input": "請用三句話講一個關於獨角獸的睡前故事。"  }'

{
  "id": "resp_example",
  "object": "response",
  "created_at": 1741476542,
  "status": "completed",
  "error": null,
  "incomplete_details": null,
  "instructions": null,
  "max_output_tokens": null,
  "model": "MODEL_ID",
  "output": [
    {
      "id": "msg_example",
      "type": "message",
      "status": "completed",
      "role": "assistant",
      "content": [
        {
          "type": "output_text",
          "text": "在月光下，一隻獨角獸發現了通往星空的秘密小徑。",
          "annotations": []
        }
      ]
    }
  ],
  "parallel_tool_calls": true,
  "previous_response_id": null,
  "reasoning": {
    "effort": null,
    "summary": null
  },
  "store": true,
  "temperature": 1,
  "text": {
    "format": {
      "type": "text"
    }
  },
  "tool_choice": "auto",
  "tools": [],
  "top_p": 1,
  "truncation": "disabled",
  "usage": {
    "input_tokens": 18,
    "input_tokens_details": {
      "cached_tokens": 0
    },
    "output_tokens": 22,
    "output_tokens_details": {
      "reasoning_tokens": 0
    },
    "total_tokens": 40
  },
  "user": null,
  "metadata": {}
}

OpenAI Responses 官方文件檢視上游協議定義與最新欄位變更。

授權

請求主體

回應主體

200application/json

400application/json

401application/json

403application/json

404application/json

429application/json

500application/json

502application/json

503application/json

504application/json

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`