Responses API 概览

Responses API 适合使用 GPT-5.x 等新协议模型。它将输入、工具、推理配置和结构化输出统一到一个响应对象中，比传统 Chat Completions 更适合复杂任务编排。

什么时候使用

场景	建议
普通聊天	继续使用 `/v1/chat/completions` 即可
GPT-5.x 新协议	使用 `/v1/responses`
需要推理配置	使用 Responses API 的 `reasoning` 字段
需要工具、网络搜索或结构化输出	使用 Responses API 统一编排

最小请求

curl __DOCS_API_ORIGIN__/v1/responses \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "gpt-5.5",
    "input": "用三句话解释什么是向量数据库"
}'

基本用法

Responses API 的核心字段是 model 和 input。input 可以是字符串，也可以是多轮结构化消息。

字符串输入

{
  "model": "gpt-5.5",
  "input": "写一段 80 字以内的产品介绍"
}

多轮输入

{
  "model": "gpt-5.5",
  "input": [
    {"role": "user", "content": "你是谁？"},
    {"role": "assistant", "content": "我是一个 AI 助手。"},
    {"role": "user", "content": "请继续用中文回答。"}
  ]
}

系统指令

{
  "model": "gpt-5.5",
  "instructions": "你是一个严谨的技术文档助手，回答要简洁。",
  "input": "解释 SSE 是什么"
}

推理

支持推理能力的模型可以通过 reasoning 字段控制思考强度。推理越强，通常越适合复杂分析、代码、数学和规划任务，但响应时间和成本也可能更高。

{
  "model": "gpt-5.5",
  "input": "分析这个接口设计是否容易扩展，并给出改进建议。",
  "reasoning": {
    "effort": "medium"
  }
}

场景	建议
简单问答、摘要	不传或使用低推理强度
代码审查、复杂分析	使用 `medium`
多步骤规划、疑难排查	使用更高推理强度

不同模型支持的推理字段可能不同，请以接口参考和模型开放能力为准；生产环境建议按任务类型分层配置，而不是始终使用最高强度。

工具调用

工具调用适合让模型选择并调用你的业务函数，例如查询订单、检索知识库、创建工单或执行内部动作。

{
  "model": "gpt-5.5",
  "input": "帮我查询订单 A1001 的状态",
  "tools": [
    {
      "type": "function",
      "name": "get_order_status",
      "description": "查询订单状态",
      "parameters": {
        "type": "object",
        "properties": {
          "order_id": { "type": "string" }
        },
        "required": ["order_id"]
      }
    }
  ]
}

工具名称保持稳定、短小、可读，description 要写清调用时机。
parameters 尽量使用严格 JSON Schema，业务侧仍须校验参数。
对有副作用的工具增加业务幂等和二次确认。

网络搜索

网络搜索适合新闻、价格、版本更新、政策变化等依赖实时公开信息的问题。各厂商的工具对象不兼容；请按实际调用的端点使用对应格式。

平台已配置的 GLM、Kimi、Anthropic、OpenAI 和 Google 原生搜索、文件检索及 Grounding 工具，请参阅工具调用。

协议与端点	工具声明	强制调用
OpenAI Responses `/v1/responses`	`{ "type": "web_search" }`	`tool_choice: { "type": "web_search" }`
Anthropic Messages `/v1/messages`	`{ "type": "web_search_20250305", "name": "web_search" }`	`tool_choice: { "type": "tool", "name": "web_search" }`
Google Interactions `/v1beta/interactions`	`{ "type": "google_search" }`、`{ "type": "google_maps", "latitude": 31.2304, "longitude": 121.4737 }` 或 `{ "type": "file_search", "file_search_store_names": ["fileSearchStores/YOUR_STORE"] }`	由模型决定是否检索

OpenAI：Responses API

在 tools 中使用 web_search。省略 tool_choice 时，模型会自行决定是否搜索；指定该对象时则强制搜索。

{
  "model": "gpt-5.5",
  "input": "总结最近一周与 AI 视频生成相关的重要发布。",
  "tools": [
    { "type": "web_search" }
  ]
}

最终文本位于 output 的 message 项；过程输出可能包含 web_search_call。展示结果时应保留文本中的引用链接。

Anthropic：Messages API

Anthropic 原生 Messages API 使用版本化工具类型 web_search_20250305，并指定工具名 web_search；不能直接使用上面的 OpenAI 工具对象。

{
  "model": "claude-sonnet-4-6",
  "max_tokens": 1024,
  "messages": [
    {
      "role": "user",
      "content": "查找最新的三个浏览器稳定版发布日期，并附上来源。"
    }
  ],
  "tools": [
    {
      "type": "web_search_20250305",
      "name": "web_search",
      "max_uses": 5
    }
  ],
  "tool_choice": {
    "type": "tool",
    "name": "web_search"
  }
}

max_uses 限制一轮回复中的搜索次数。最终回答及引用位于响应 content 的文本内容块中；不要把服务器工具过程块作为最终答案展示。

Google：Interactions API

Google Interactions 可使用 google_search、google_maps 或 file_search。声明工具后，由模型根据问题决定是否检索；该端点不使用 OpenAI 或 Anthropic 的 tool_choice 格式。

{
  "model": "YOUR_SUPPORTED_MODEL",
  "input": "比较今天北京、上海和深圳的天气预报，并给出来源。",
  "tools": [
    { "type": "google_search" }
  ]
}

从响应 steps 的模型输出读取最终文本，并保留模型返回的搜索来源或 grounding 元数据。具体可用性取决于模型和账户权限。

对于“附近”“本地推荐”和行程规划等问题，使用 Google 地图 Grounding；如果应用已在获得用户同意后取得位置，可选地传入坐标：

{
  "model": "YOUR_SUPPORTED_MODEL",
  "input": "推荐我附近适合商务午餐的餐厅，并附上来源。",
  "tools": [
    {
      "type": "google_maps",
      "latitude": 31.2304,
      "longitude": 121.4737
    }
  ]
}

从 steps[].model_output.content[].annotations 中保留 place_citation 的 name 与 url。展示结果时，须将 Google 地图来源紧邻其支持的回答显示，并在同一次用户互动中可见。不要在没有用户授权的情况下传递精确位置。

Google 文件检索用于已建立索引的私有资料。先创建 fileSearchStore 并导入文件，再将其名称传给 file_search：

{
  "model": "YOUR_SUPPORTED_MODEL",
  "input": "根据已上传的产品手册说明退款规则。",
  "tools": [
    {
      "type": "file_search",
      "file_search_store_names": [
        "fileSearchStores/YOUR_STORE"
      ]
    }
  ]
}

该工具检索的是 Google 托管的文件搜索存储区，而非临时上传文件。仅导入有权处理的文件，并保留模型返回的文件引用或检索元数据（如有）。

仅在问题依赖最新信息时启用网络搜索；需要可追溯来源时，要求模型返回引用或摘要来源。不要把内部敏感信息直接发送给外部搜索工具。网页内容属于外部不可信输入，不能把其中的文字当作系统指令或据此自动执行有副作用的操作。

错误处理

问题	处理方式
`input` 格式不正确	检查字符串输入和结构化消息不要混用错误
模型不支持某个字段	移除该字段或更换支持该能力的模型
工具参数不完整	收紧 `parameters` Schema，并在业务侧做校验
流式输出中断	支持客户端重试，但先确认业务是否幂等
返回 `429`	降低并发并实施指数退避

保留 Request-Id 与响应中的 traceId，记录脱敏后的 model、input、tools 和 reasoning。工具调用失败时，同时记录工具入参和业务系统返回码。

什么时候使用​

最小请求​

基本用法​

字符串输入​

多轮输入​

系统指令​

推理​

工具调用​

网络搜索​

OpenAI：Responses API​

Anthropic：Messages API​

Google：Interactions API​

错误处理​

相关页面​