> ## Documentation Index
> Fetch the complete documentation index at: https://mixroute.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# 建立 Responses 請求 (OpenAI)

> OpenAI 新一代對話介面，專為推理模型和進階功能設計

## 簡介

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

> [!NOTE]
>
> `gpt-6.1-sol`：函式呼叫和 `reasoning.effort="max"` 使用 Responses。Chat Completions 支援不帶工具的請求，`reasoning_effort` 可用值為 `low`、`medium`、`high`、`xhigh`。兩種介面均不支援 `none` 或 `minimal`，不要傳入 `temperature`、`top_p` 或 logprobs 相關欄位。詳見 [GPT 6.1 Sol](/docs/zh-Hant/model-api/openai/gpt-6.1-sol)。

## 適用情境

* 推理密集型任務：使用 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.5`、`o4-mini`、`o3-mini`

**input** `string | array` *required*

輸入文本或 Responses 輸入條目陣列。

**max\_output\_tokens** `integer`

最大輸出 token 數

**stream** `boolean`

是否啟用串流輸出

**reasoning** `object`

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

**tools** `array`

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

**previous\_response\_id** `string`

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

## 基礎範例

**簡單對話（非串流）**

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

**簡單對話（串流）**

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

**Python SDK**

```python theme={null}
from openai import OpenAI

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

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

print(response.output_text)

# 串流呼叫
stream = client.responses.create(
    model="gpt-5.5",
    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）

**基礎範例**

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

**進階設定**

```bash theme={null}
curl -X POST "https://api.mixroute.ai/v1/responses" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-xxxxxxxxxx" \
  -d '{
    "model": "gpt-5.5",
    "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）

**自動推理摘要**

```bash theme={null}
curl -X POST "https://api.mixroute.ai/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"` 會自動產生推理摘要，適合快速取得結果。

**詳細推理過程**

```bash theme={null}
curl -X POST "https://api.mixroute.ai/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`

### 自訂函式呼叫

Responses 的函式定義將 name、description、parameters、strict 與 type 放在同一層，不巢狀 function 物件。按型別處理 output 條目；執行函式後通過 function\_call\_output 和對應 call\_id 回傳結果。無狀態請求需在後續 input 中保留完整 output 陣列，包括可能出現的 reasoning 條目；同時將 tool\_choice 恢復為 "auto"，讓模型繼續生成回答。

```bash theme={null}
curl --request POST "https://api.mixroute.ai/v1/responses" \
  --header "Authorization: Bearer $MIXROUTE_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
  "model": "gpt-6.1-sol",
  "input": "Call lookup_status for service demo.",
  "reasoning": {
    "effort": "low"
  },
  "tools": [
    {
      "type": "function",
      "name": "lookup_status",
      "description": "Return the status of a named service.",
      "parameters": {
        "type": "object",
        "properties": {
          "service": {
            "type": "string"
          }
        },
        "required": [
          "service"
        ],
        "additionalProperties": false
      },
      "strict": true
    }
  ],
  "tool_choice": {
    "type": "function",
    "name": "lookup_status"
  },
  "include": [
    "reasoning.encrypted_content"
  ],
  "max_output_tokens": 1024,
  "store": false
}'
```

### 多模態輸入

**圖片輸入**

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

**檔案輸入**

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

> [!NOTE]
>
> 使用檔案輸入前，需要先透過 Files API 上傳檔案取得 `file_id`。

### 對話延續

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

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

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

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

## 回應格式

**非串流回應**

```json theme={null}
{
  "id": "resp_xxx",
  "object": "response",
  "created_at": 1709123456,
  "model": "gpt-5.5",
  "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
  }
}
```

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

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

```text theme={null}
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` | ❌ 需手動管理 |
| 多模態輸入 | ✅ 完整支援 | ✅ 支援 |
| 適用情境 | 推理、搜尋、進階功能 | 通用對話 |

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

```python Python theme={null}
from openai import OpenAI

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

response = client.responses.create(
    model="gpt-5.5",
    max_output_tokens=2048,
    input=[
        {"role": "user", "content": "請用中文簡要介紹人工智慧"}
    ]
)
print(response.output_text)
```

```javascript JavaScript theme={null}
const OpenAI = require('openai');

const client = new OpenAI({
  apiKey: 'sk-xxxxxxxxxx',
  baseURL: 'https://api.mixroute.ai/v1'
});

const response = await client.responses.create({
  model: 'gpt-5.5',
  max_output_tokens: 2048,
  input: [
    { role: 'user', content: '請用中文簡要介紹人工智慧' }
  ]
});
console.log(response.output_text);
```

```php PHP theme={null}
<?php
$client = new GuzzleHttp\Client();
$response = $client->post('https://api.mixroute.ai/v1/responses', [
    'headers' => [
        'Authorization' => 'Bearer sk-xxxxxxxxxx',
        'Content-Type' => 'application/json',
    ],
    'json' => [
        'model' => 'gpt-5.5',
        'max_output_tokens' => 2048,
        'input' => [
            ['role' => 'user', 'content' => '請用中文簡要介紹人工智慧']
        ]
    ]
]);
echo $response->getBody();
```

```go Go theme={null}
package main

import (
    "bytes"
    "encoding/json"
    "net/http"
)

func main() {
    payload := map[string]interface{}{
        "model": "gpt-5.5",
        "max_output_tokens": 2048,
        "input": []map[string]string{
            {"role": "user", "content": "請用中文簡要介紹人工智慧"},
        },
    }
    body, _ := json.Marshal(payload)
    req, _ := http.NewRequest("POST", "https://api.mixroute.ai/v1/responses", bytes.NewBuffer(body))
    req.Header.Set("Authorization", "Bearer sk-xxxxxxxxxx")
    req.Header.Set("Content-Type", "application/json")
    http.DefaultClient.Do(req)
}
```

```java Java theme={null}
import java.net.http.*;
import java.net.URI;

HttpClient client = HttpClient.newHttpClient();
String json = """
    {
      "model": "gpt-5.5",
      "max_output_tokens": 2048,
      "input": [
        {"role": "user", "content": "請用中文簡要介紹人工智慧"}
      ]
    }
    """;
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.mixroute.ai/v1/responses"))
    .header("Authorization", "Bearer sk-xxxxxxxxxx")
    .header("Content-Type", "application/json")
    .POST(HttpRequest.BodyPublishers.ofString(json))
    .build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());
```

```ruby Ruby theme={null}
require 'net/http'
require 'json'

uri = URI('https://api.mixroute.ai/v1/responses')
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true

request = Net::HTTP::Post.new(uri)
request['Authorization'] = 'Bearer sk-xxxxxxxxxx'
request['Content-Type'] = 'application/json'
request.body = {
  model: 'gpt-5.5',
  max_output_tokens: 2048,
  input: [
    { role: 'user', content: '請用中文簡要介紹人工智慧' }
  ]
}.to_json

response = http.request(request)
puts response.body
```

```json Response theme={null}
{
  "id": "resp_xxx",
  "object": "response",
  "created_at": 1768271369,
  "model": "gpt-5.5",
  "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
  }
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.