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

# 原生 OpenAI 格式（Responses）

## 简介

Responses API 是 OpenAI 推出的新一代对话接口，专为 GPT-5 系列与高级功能设计。相比传统的 Chat Completions API，Responses API 提供了更精细的推理控制、内置工具支持和多模态输入能力。

## 适用场景

* **推理密集型任务**：使用 GPT-5.5、GPT-5.4、GPT-5.4 Pro 等具备深度推理能力的模型
* **需要联网搜索**：内置 Web Search Preview 工具
* **高级工具调用**：支持 Function Call 和 Custom Tool Call
* **多轮对话延续**：通过 `previous_response_id` 实现对话历史管理

## 认证

<ParamField header="Authorization" type="string" required>
  Bearer Token，如 `Bearer sk-xxxxxxxxxx`
</ParamField>

## 请求参数

<ParamField body="model" type="string" required>
  模型标识，支持的模型包括：

  * GPT-5 系列：`gpt-5.5`、`gpt-5.4`、`gpt-5.4-pro`、`gpt-5.4-mini`、`gpt-5.4-nano` 等
  * GPT-4 系列：`gpt-4o`、`gpt-4.1`、`gpt-4o-mini` 等
</ParamField>

<ParamField body="input" type="array" required>
  输入消息列表，支持多种格式：

  * **简化格式**：`[{"role": "user", "content": "文本"}]`（类似 Chat Completions）
  * **标准格式**：`[{"type": "input_text", "text": "文本"}]`
  * **多模态**：支持 `input_image`、`input_file` 类型
</ParamField>

<ParamField body="instructions" type="string">
  系统指令，等同于 Chat Completions 中的 system message
</ParamField>

<ParamField body="max_output_tokens" type="number">
  最大输出 token 数，控制回复长度
</ParamField>

<ParamField body="stream" type="boolean" default="false">
  是否启用流式输出，返回 SSE 格式的分片数据
</ParamField>

<ParamField body="temperature" type="number" default="1.0">
  随机性控制，0-2，值越高回复越随机
</ParamField>

<ParamField body="top_p" type="number" default="0.98">
  核采样参数，0-1，控制生成的多样性
</ParamField>

<ParamField body="reasoning" type="object">
  推理配置，用于控制推理模型的行为：

  * `effort`：推理力度，可选 `"none"`、`"low"`、`"medium"`、`"high"`
  * `summary`：推理摘要，可选 `"auto"`、`"none"`、`"detailed"`
</ParamField>

<ParamField body="tools" type="array">
  工具列表，支持三种类型：

  * **内置 Web 搜索工具**：`{"type": "web_search_preview", "search_context_size": "medium"}`
  * **内置文件搜索工具**：`{"type": "file_search"}`
  * **自定义函数工具**：标准 OpenAI Function Call 格式
</ParamField>

<ParamField body="tool_choice" type="string|object" default="auto">
  工具选择策略：

  * `"auto"`：由模型自动决定是否调用工具
  * `"none"`：禁用工具调用
  * `{"type": "function", "function": {"name": "函数名"}}`：强制调用指定函数
</ParamField>

<ParamField body="parallel_tool_calls" type="boolean" default="true">
  是否允许并行调用多个工具
</ParamField>

<ParamField body="max_tool_calls" type="number">
  最大工具调用次数限制
</ParamField>

<ParamField body="previous_response_id" type="string">
  前一个响应的 ID，用于延续对话历史
</ParamField>

<ParamField body="truncation" type="string" default="disabled">
  截断策略：`"auto"` 或 `"disabled"`
</ParamField>

<ParamField body="metadata" type="object">
  请求元数据，用于跟踪和调试
</ParamField>

<ParamField body="user" type="string">
  用户标识符
</ParamField>

## 基础示例

<Tabs>
  <Tab title="简单对话（非流式）">
    ```bash theme={null}
    curl -X POST "https://api.gravitex.ai/v1/responses" \
      -H "Content-Type: application/json" \
      -H "Authorization: Bearer sk-xxxxxxxxxx" \
      -d '{
        "model": "gpt-5.2",
        "max_output_tokens": 2048,
        "input": [
          {"role": "system", "content": "你是一个有用的助手"},
          {"role": "user", "content": "请用中文简要介绍人工智能"}
        ]
      }'
    ```
  </Tab>

  <Tab title="简单对话（流式）">
    ```bash theme={null}
    curl -N -X POST "https://api.gravitex.ai/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": "请用中文简要介绍人工智能"}
        ]
      }'
    ```
  </Tab>

  <Tab title="Python SDK">
    ```python theme={null}
    from openai import OpenAI

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

    # 使用 Responses API
    response = client.responses.create(
        model="gpt-5.2",
        max_output_tokens=2048,
        input=[
            {"role": "user", "content": "请用中文简要介绍人工智能"}
        ]
    )

    print(response.output[0].content[0].text)
    ```
  </Tab>
</Tabs>

## 响应格式

### 非流式响应

```json theme={null}
{
  "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,
    "input_tokens_details": {
      "cached_tokens": 0
    },
    "output_tokens_details": {
      "reasoning_tokens": 50
    }
  }
}
```

### 流式响应（SSE 事件）

流式响应使用 Server-Sent Events 格式，包含以下事件类型：

| 事件类型                         | 说明            |
| ---------------------------- | ------------- |
| `response.created`           | 响应创建          |
| `response.in_progress`       | 响应进行中         |
| `response.output_item.added` | 输出项添加（工具调用开始） |
| `response.output_text.delta` | 文本增量          |
| `response.output_text.done`  | 文本完成          |
| `response.output_item.done`  | 输出项完成         |
| `response.completed`         | 响应完成          |

**示例 SSE 输出**：

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

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

event: response.output_text.delta
data: {"type":"response.output_text.delta","delta":"智能","sequence_number":2}

event: response.completed
data: {"type":"response.completed","response":{"id":"resp_xxx","status":"completed","usage":{...}}}
```

## 高级功能

### 1. 联网搜索（Web Search）

启用内置的 Web 搜索工具，让模型可以实时搜索互联网信息。

<Tabs>
  <Tab title="基础示例">
    ```bash theme={null}
    curl -X POST "https://api.gravitex.ai/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": "今天的新闻头条是什么？"}
        ],
        "tools": [
          {
            "type": "web_search_preview",
            "search_context_size": "medium"
          }
        ]
      }'
    ```
  </Tab>

  <Tab title="高级配置">
    ```bash theme={null}
    curl -X POST "https://api.gravitex.ai/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": "US",
              "region": "NY",
              "city": "New York",
              "timezone": "America/New_York"
            }
          }
        ]
      }'
    ```
  </Tab>
</Tabs>

**Web Search 参数说明**：

* **`search_context_size`**：搜索上下文大小
  * `"low"`：低上下文，更快但结果较少
  * `"medium"`：中等上下文（默认）
  * `"high"`：高上下文，更多搜索结果但更慢

* **`user_location`**（可选）：用户位置信息
  * `country`：国家代码（如 "US"、"CN"）
  * `region`：州/省份
  * `city`：城市
  * `timezone`：时区

### 2. 推理控制（Reasoning）

控制推理模型的思考深度和输出格式。

<Tabs>
  <Tab title="自动推理摘要">
    ```bash theme={null}
    curl -X POST "https://api.gravitex.ai/v1/responses" \
      -H "Content-Type: application/json" \
      -H "Authorization: Bearer sk-xxxxxxxxxx" \
      -d '{
        "model": "gpt-5.5",
        "stream": true,
        "reasoning": {
          "summary": "auto"
        },
        "max_output_tokens": 8192,
        "input": [
          {"role": "user", "content": "汉诺塔的公式是什么？"}
        ]
      }'
    ```
  </Tab>

  <Tab title="详细推理过程">
    ```bash theme={null}
    curl -X POST "https://api.gravitex.ai/v1/responses" \
      -H "Content-Type: application/json" \
      -H "Authorization: Bearer sk-xxxxxxxxxx" \
      -d '{
        "model": "gpt-5.5",
        "stream": true,
        "reasoning": {
          "effort": "high",
          "summary": "detailed"
        },
        "max_output_tokens": 16384,
        "input": [
          {"role": "user", "content": "证明费马大定理"}
        ]
      }'
    ```
  </Tab>
</Tabs>

**Reasoning 参数说明**：

* **`effort`**：推理力度
  * `"none"`：不进行推理
  * `"low"`：轻量推理
  * `"medium"`：中等推理（默认）
  * `"high"`：深度推理

* **`summary`**：推理摘要
  * `"none"`：不输出推理摘要
  * `"auto"`：自动决定是否输出摘要
  * `"detailed"`：输出详细推理过程

### 3. 自定义函数调用

支持标准的 OpenAI Function Calling 格式。

```bash theme={null}
curl -X POST "https://api.gravitex.ai/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": "function",
        "function": {
          "name": "get_weather",
          "description": "获取指定城市的天气信息",
          "parameters": {
            "type": "object",
            "properties": {
              "city": {
                "type": "string",
                "description": "城市名称"
              }
            },
            "required": ["city"]
          }
        }
      }
    ],
    "tool_choice": "auto"
  }'
```

**函数调用响应格式**：

```json theme={null}
{
  "output": [
    {
      "id": "call_xxx",
      "type": "function_call",
      "status": "completed",
      "name": "get_weather",
      "call_id": "call_xxx",
      "arguments": "{\"city\":\"上海\"}"
    }
  ]
}
```

### 4. 多模态输入

支持文本、图片、文件等多种输入类型。

<Tabs>
  <Tab title="图片输入">
    ```bash theme={null}
    curl -X POST "https://api.gravitex.ai/v1/responses" \
      -H "Content-Type: application/json" \
      -H "Authorization: Bearer sk-xxxxxxxxxx" \
      -d '{
        "model": "gpt-5.2",
        "input": [
          {
            "type": "input_text",
            "text": "这张图片里有什么？"
          },
          {
            "type": "input_image",
            "image_url": "https://example.com/image.jpg",
            "detail": "high"
          }
        ]
      }'
    ```
  </Tab>

  <Tab title="文件输入">
    ```bash theme={null}
    curl -X POST "https://api.gravitex.ai/v1/responses" \
      -H "Content-Type: application/json" \
      -H "Authorization: Bearer sk-xxxxxxxxxx" \
      -d '{
        "model": "gpt-5.2",
        "input": [
          {
            "type": "input_text",
            "text": "请分析这个PDF文档的内容"
          },
          {
            "type": "input_file",
            "file_url": "https://example.com/document.pdf"
          }
        ]
      }'
    ```
  </Tab>
</Tabs>

### 5. 对话延续

使用 `previous_response_id` 延续之前的对话。

```bash theme={null}
# 第一次对话
curl -X POST "https://api.gravitex.ai/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://api.gravitex.ai/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": "它的应用场景有哪些？"}
    ]
  }'
```

## 注意事项

<Warning>
  * **模型兼容性**：并非所有模型都支持 Responses API 的全部功能
  * **Web Search**：仅 GPT-4o、GPT-4.1、GPT-5 和 o 系列模型支持
  * **推理功能**：仅 o 系列和部分 GPT-5 系列模型支持 `reasoning` 参数
  * **格式混淆**：流式响应中的 delta 可能包含 `obfuscation` 字段（内容混淆保护），完整明文在 `response.output_text.done` 事件中
</Warning>

<Tip>
  * 如果您需要标准的 Chat Completions 格式，可以使用 `/v1/chat/completions` 接口 + `openai/` 模型前缀
  * 系统会自动转换格式，提供更好的客户端兼容性
</Tip>

## 对比：Responses API vs Chat Completions API

| 特性            | Responses API            | Chat Completions API |
| ------------- | ------------------------ | -------------------- |
| 推理模型支持        | ✅ 完整支持                   | ⚠️ 有限支持              |
| 内置 Web Search | ✅ 原生支持                   | ❌ 不支持                |
| 推理控制          | ✅ 精细控制                   | ❌ 不支持                |
| 对话延续          | ✅ `previous_response_id` | ✅ 通过 messages        |
| 流式输出          | ✅ SSE 格式                 | ✅ SSE 格式             |
| 客户端兼容性        | ⚠️ 需要适配                  | ✅ 标准格式               |
| 适用场景          | 推理、搜索、高级功能               | 通用对话                 |

## 相关资源

<CardGroup cols={2}>
  <Card title="Chat Completions API" icon="comments" href="/cn/api-reference/endpoint/chat-openai">
    标准对话接口文档
  </Card>

  <Card title="模型列表" icon="list" href="/cn/api-reference/models">
    查看所有支持的模型
  </Card>

  <Card title="常见问题" icon="question-circle" href="/cn/faq/chat-completions">
    Responses API 常见问题
  </Card>
</CardGroup>