> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mixroute.ai/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 提供了更精细的推理控制、内置工具支持和多模态输入能力。

## 适用场景

* 推理密集型任务：使用 o1、o3-mini、o4-mini、GPT-5 等推理模型
* 需要联网搜索：内置 Web Search Preview 工具
* 高级工具调用：支持 Function Call 和 Custom Tool Call
* 多轮对话延续：通过 `previous_response_id` 实现对话历史管理

## 认证

Bearer Token，如 `Bearer sk-xxxxxxxxxx`

## 请求参数

<ParamField body="model" type="string" required>
  模型标识，如 `gpt-5.5`、`o4-mini`、`o3-mini`
</ParamField>

<ParamField body="input" type="array" required>
  输入消息列表
</ParamField>

<ParamField body="max_output_tokens" type="integer">
  最大输出 token 数
</ParamField>

<ParamField body="stream" type="boolean">
  是否启用流式输出
</ParamField>

<ParamField body="reasoning" type="object">
  推理配置，如 `{"effort": "high", "summary": "detailed"}`
</ParamField>

<ParamField body="tools" type="array">
  工具列表，支持 Web Search 和函数调用
</ParamField>

<ParamField body="previous_response_id" type="string">
  上一条响应的 ID，用于延续对话
</ParamField>

## 基础示例

<Tabs>
  <Tab title="简单对话（非流式）">
    ```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": "请用中文简要介绍人工智能"}
        ]
      }'
    ```
  </Tab>

  <Tab title="简单对话（流式）">
    ```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": "请用中文简要介绍人工智能"}
        ]
      }'
    ```
  </Tab>

  <Tab title="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[0].content[0].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)
    ```
  </Tab>
</Tabs>

## 高级功能

### 联网搜索（Web Search）

<Tabs>
  <Tab title="基础示例">
    ```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"
          }
        ]
      }'
    ```
  </Tab>

  <Tab title="高级配置">
    ```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": "CN"
            }
          }
        ]
      }'
    ```

    **配置说明：**

    * `search_context_size`: 搜索上下文大小，可选 `low`、`medium`、`high`
    * `user_location`: 用户位置，影响搜索结果的地区相关性
  </Tab>
</Tabs>

### 推理控制（Reasoning）

<Tabs>
  <Tab title="自动推理摘要">
    ```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"` 会自动生成推理摘要，适合快速获取结果。
  </Tab>

  <Tab title="详细推理过程">
    ```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`
  </Tab>
</Tabs>

### 自定义函数调用

```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": "北京今天天气怎么样？"}
    ],
    "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"
  }'
```

### 多模态输入

<Tabs>
  <Tab title="图片输入">
    ```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"
              }
            ]
          }
        ]
      }'
    ```
  </Tab>

  <Tab title="文件输入">
    ```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`。
    </Note>
  </Tab>
</Tabs>

### 对话延续

通过 `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": "我叫什么名字？"}
    ]
  }'
```

## 响应格式

<Tabs>
  <Tab title="非流式响应">
    ```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
      }
    }
    ```
  </Tab>

  <Tab title="流式响应（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`            | 响应失败   |
  </Tab>
</Tabs>

## 对比：Responses API vs Chat Completions API

| 特性            | Responses API            | Chat Completions API |
| ------------- | ------------------------ | -------------------- |
| 推理模型支持        | ✅ 完整支持                   | ⚠️ 有限支持              |
| 内置 Web Search | ✅ 原生支持                   | ❌ 不支持                |
| 推理控制          | ✅ 精细控制                   | ❌ 不支持                |
| 对话延续          | ✅ `previous_response_id` | ❌ 需手动管理              |
| 多模态输入         | ✅ 完整支持                   | ✅ 支持                 |
| 适用场景          | 推理、搜索、高级功能               | 通用对话                 |

<RequestExample>
  ```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[0].content[0].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[0].content[0].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
  ```
</RequestExample>

<ResponseExample>
  ```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
    }
  }
  ```
</ResponseExample>

/