建立 Responses 請求 (OpenAI)

簡介

Responses API 是 OpenAI 推出的新一代對話介面，專為推理模型（o 系列、GPT-5 系列）和進階功能設計。相比傳統的 Chat Completions API，Responses API 提供了更精細的推理控制、內建工具支援和多模態輸入能力。

適用情境

推理密集型任務：使用 o1、o3-mini、o4-mini、GPT-5 等推理模型
需要聯網搜尋：內建 Web Search Preview 工具
進階工具呼叫：支援 Function Call 和 Custom Tool Call
多輪對話延續：透過 previous_response_id 實現對話歷史管理

認證

Bearer Token，如 Bearer sk-xxxxxxxxxx

請求參數

model

string

required

模型識別碼，如 gpt-5.2、o4-mini、o3-mini

input

array

required

輸入訊息列表

max_output_tokens

integer

最大輸出 token 數

stream

boolean

是否啟用串流輸出

reasoning

object

推理設定，如 {"effort": "high", "summary": "detailed"}

tools

array

工具列表，支援 Web Search 和函式呼叫

previous_response_id

string

上一條回應的 ID，用於延續對話

基礎範例

簡單對話（非串流）
簡單對話（串流）
Python SDK

curl -X POST "https://console.mixroute.io/v1/responses" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-xxxxxxxxxx" \
  -d '{
    "model": "gpt-5.2",
    "max_output_tokens": 2048,
    "input": [
      {"role": "user", "content": "請用中文簡要介紹人工智慧"}
    ]
  }'

curl -X POST "https://console.mixroute.io/v1/responses" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-xxxxxxxxxx" \
  -d '{
    "model": "gpt-5.2",
    "stream": true,
    "max_output_tokens": 2048,
    "input": [
      {"role": "user", "content": "請用中文簡要介紹人工智慧"}
    ]
  }'

from openai import OpenAI

client = OpenAI(
    api_key="sk-xxxxxxxxxx",
    base_url="https://console.mixroute.io/v1"
)

# 非串流呼叫
response = client.responses.create(
    model="gpt-5.2",
    max_output_tokens=2048,
    input=[
        {"role": "user", "content": "請用中文簡要介紹人工智慧"}
    ]
)

print(response.output[0].content[0].text)

# 串流呼叫
stream = client.responses.create(
    model="gpt-5.2",
    stream=True,
    max_output_tokens=2048,
    input=[
        {"role": "user", "content": "請用中文簡要介紹人工智慧"}
    ]
)

for event in stream:
    if event.type == "response.output_text.delta":
        print(event.delta, end="", flush=True)

進階功能

聯網搜尋（Web Search）

基礎範例
進階設定

curl -X POST "https://console.mixroute.io/v1/responses" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-xxxxxxxxxx" \
  -d '{
    "model": "gpt-5.2",
    "stream": true,
    "input": [
      {"role": "user", "content": "今天的新聞頭條是什麼？"}
    ],
    "tools": [
      {
        "type": "web_search_preview"
      }
    ]
  }'

curl -X POST "https://console.mixroute.io/v1/responses" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-xxxxxxxxxx" \
  -d '{
    "model": "gpt-5.2",
    "stream": true,
    "input": [
      {"role": "user", "content": "搜尋最新的人工智慧研究進展"}
    ],
    "tools": [
      {
        "type": "web_search_preview",
        "search_context_size": "high",
        "user_location": {
          "type": "approximate",
          "country": "TW"
        }
      }
    ]
  }'

設定說明：

search_context_size：搜尋上下文大小，可選 low、medium、high
user_location：使用者位置，影響搜尋結果的地區相關性

推理控制（Reasoning）

自動推理摘要
詳細推理過程

curl -X POST "https://console.mixroute.io/v1/responses" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-xxxxxxxxxx" \
  -d '{
    "model": "o4-mini",
    "stream": true,
    "reasoning": {
      "effort": "medium",
      "summary": "auto"
    },
    "max_output_tokens": 4096,
    "input": [
      {"role": "user", "content": "計算 1+2+3+...+100 的和"}
    ]
  }'

說明： summary: "auto" 會自動產生推理摘要，適合快速取得結果。

curl -X POST "https://console.mixroute.io/v1/responses" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-xxxxxxxxxx" \
  -d '{
    "model": "o4-mini",
    "stream": true,
    "reasoning": {
      "effort": "high",
      "summary": "detailed"
    },
    "max_output_tokens": 8192,
    "input": [
      {"role": "user", "content": "證明根號2是無理數"}
    ]
  }'

推理設定參數：

effort：推理強度，可選 low、medium、high
summary：摘要模式，可選 auto、concise、detailed

自訂函式呼叫

curl -X POST "https://console.mixroute.io/v1/responses" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-xxxxxxxxxx" \
  -d '{
    "model": "gpt-5.2",
    "input": [
      {"role": "user", "content": "台北今天天氣怎麼樣？"}
    ],
    "tools": [
      {
        "type": "function",
        "function": {
          "name": "get_weather",
          "description": "取得指定城市的天氣資訊",
          "parameters": {
            "type": "object",
            "properties": {
              "city": {
                "type": "string",
                "description": "城市名稱"
              },
              "unit": {
                "type": "string",
                "enum": ["celsius", "fahrenheit"],
                "description": "溫度單位"
              }
            },
            "required": ["city"]
          }
        }
      }
    ],
    "tool_choice": "auto"
  }'

多模態輸入

圖片輸入
檔案輸入

curl -X POST "https://console.mixroute.io/v1/responses" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-xxxxxxxxxx" \
  -d '{
    "model": "gpt-5.2",
    "input": [
      {
        "role": "user",
        "content": [
          {
            "type": "input_text",
            "text": "這張圖片裡有什麼？"
          },
          {
            "type": "input_image",
            "image_url": "https://console.mixroute.io/demo/sample-image.jpg"
          }
        ]
      }
    ]
  }'

curl -X POST "https://console.mixroute.io/v1/responses" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-xxxxxxxxxx" \
  -d '{
    "model": "gpt-5.2",
    "input": [
      {
        "role": "user",
        "content": [
          {
            "type": "input_text",
            "text": "請總結這份文件的主要內容"
          },
          {
            "type": "input_file",
            "file_id": "file-xxxxxxxx"
          }
        ]
      }
    ]
  }'

使用檔案輸入前，需要先透過 Files API 上傳檔案取得 file_id。

對話延續

透過 previous_response_id 實現多輪對話的上下文延續：

# 第一輪對話
curl -X POST "https://console.mixroute.io/v1/responses" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-xxxxxxxxxx" \
  -d '{
    "model": "gpt-5.2",
    "input": [
      {"role": "user", "content": "我叫小明，請記住我的名字"}
    ]
  }'

# 回應中會返回 id: "resp_abc123"

# 第二輪對話（延續上下文）
curl -X POST "https://console.mixroute.io/v1/responses" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-xxxxxxxxxx" \
  -d '{
    "model": "gpt-5.2",
    "previous_response_id": "resp_abc123",
    "input": [
      {"role": "user", "content": "我叫什麼名字？"}
    ]
  }'

回應格式

非串流回應
串流回應（SSE 事件）

{
  "id": "resp_xxx",
  "object": "response",
  "created_at": 1709123456,
  "model": "gpt-5.2",
  "status": "completed",
  "output": [
    {
      "type": "message",
      "role": "assistant",
      "content": [
        {
          "type": "output_text",
          "text": "人工智慧（Artificial Intelligence，簡稱AI）是電腦科學的一個分支..."
        }
      ]
    }
  ],
  "usage": {
    "input_tokens": 25,
    "output_tokens": 150,
    "total_tokens": 175
  }
}

串流回應使用 Server-Sent Events (SSE) 格式返回：

event: response.created
data: {"type":"response.created","response":{"id":"resp_xxx","status":"in_progress"}}

event: response.output_item.added
data: {"type":"response.output_item.added","output_index":0,"item":{"type":"message","role":"assistant"}}

event: response.content_part.added
data: {"type":"response.content_part.added","part":{"type":"output_text","text":""}}

event: response.output_text.delta
data: {"type":"response.output_text.delta","delta":"人工"}

event: response.output_text.delta
data: {"type":"response.output_text.delta","delta":"智慧"}

event: response.output_text.delta
data: {"type":"response.output_text.delta","delta":"是..."}

event: response.output_text.done
data: {"type":"response.output_text.done","text":"人工智慧是..."}

event: response.completed
data: {"type":"response.completed","response":{"id":"resp_xxx","status":"completed","usage":{"input_tokens":25,"output_tokens":150}}}

常見 SSE 事件類型：

事件類型	說明
`response.created`	回應建立
`response.output_text.delta`	文字增量輸出
`response.output_text.done`	文字輸出完成
`response.completed`	回應完成
`response.failed`	回應失敗

對比：Responses API vs Chat Completions API

特性	Responses API	Chat Completions API
推理模型支援	✅ 完整支援	⚠️ 有限支援
內建 Web Search	✅ 原生支援	❌ 不支援
推理控制	✅ 精細控制	❌ 不支援
對話延續	✅ `previous_response_id`	❌ 需手動管理
多模態輸入	✅ 完整支援	✅ 支援
適用情境	推理、搜尋、進階功能	通用對話

curl --request POST \
  --url https://console.mixroute.io/v1/responses \
  --header 'Authorization: Bearer sk-xxxxxxxxxx' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "gpt-5.2",
    "max_output_tokens": 2048,
    "input": [
      {"role": "user", "content": "請用中文簡要介紹人工智慧"}
    ]
  }'

{
  "id": "resp_xxx",
  "object": "response",
  "created_at": 1768271369,
  "model": "gpt-5.2",
  "status": "completed",
  "output": [
    {
      "id": "msg_xxx",
      "type": "message",
      "status": "completed",
      "role": "assistant",
      "content": [
        {
          "type": "output_text",
          "text": "人工智慧（AI）是計算機科學的一個分支...",
          "annotations": []
        }
      ]
    }
  ],
  "usage": {
    "input_tokens": 25,
    "output_tokens": 150,
    "total_tokens": 175
  }
}

當下熱門模型

OpenAI 官方庫使用

文本系列

文本向量系列

圖像系列

視頻系列

其他

建立 Responses 請求 (OpenAI)

簡介

適用情境

認證

請求參數

基礎範例

進階功能

聯網搜尋（Web Search）

推理控制（Reasoning）

自訂函式呼叫

多模態輸入

對話延續

回應格式

對比：Responses API vs Chat Completions API

當下熱門模型

OpenAI 官方庫使用

文本系列

文本向量系列

圖像系列

視頻系列

其他

​簡介

​適用情境

​認證

​請求參數

​基礎範例

​進階功能

​聯網搜尋（Web Search）

​推理控制（Reasoning）

​自訂函式呼叫

​多模態輸入

​對話延續

​回應格式

​對比：Responses API vs Chat Completions API

簡介

適用情境

認證

請求參數

基礎範例

進階功能

聯網搜尋（Web Search）

推理控制（Reasoning）

自訂函式呼叫

多模態輸入

對話延續

回應格式

對比：Responses API vs Chat Completions API