青云TOP API使用教程&开发文档小白用户&专业开发者快速使用指南
控制台
返回模型调用 API 参考
POST/v1/responses

Responses 网络搜索工具

在 Responses 请求的 `tools` 中声明 `web_search`，让支持的模型尝试检索网页并将来源信息放进响应项目。

API Key application/json

功能与适用场景

适用于需要近期网页信息和来源标注的问答。此字段表达工具请求，不保证每个模型、渠道、地区或账号都有可用搜索能力；普通回答中的 URL 也不是已验证的搜索引用。

支持模型与组合

示例使用 gpt-6-astra 的 Responses 工具结构。是否能执行由模型映射和当前渠道决定；若返回参数错误或工具失败，先确认模型权限与搜索能力，再使用不依赖联网的提示。

第一步：设置鉴权

使用青云TOP API 的 API Key：Authorization: Bearer YOUR_API_KEY，替换占位符并保留 Bearer 后的空格。

第二步：声明工具并调用模型

发送 POST https://top.qingyuntop.ai/v1/responses，在 tools 数组中声明 { "type": "web_search" }。不要把 Chat Completions 的 web_search_options 放到 Responses 请求中。

Responses API

调用与返回说明

OpenAI 新项目的首选模型调用协议。它以 output 项目表达文本、工具调用和推理结果，不能按 Chat Completions 的 choices 结构读取。

请求时注意

  • 模型 ID 不要从示例中照抄。先调用 GET /v1/models，再选择返回列表中实际可用且支持当前协议的完整 ID。
  • Responses API 的 input 可以是字符串，也可以是带 role/content 的输入项目数组；图片、文件和工具调用必须使用官方规定的输入项目类型。
  • 不要把 Chat Completions 的 choices、message 或 delta 结构混用于 Responses API。

返回时注意

  • 先检查 HTTP 状态码，再检查 response.status。只有 status=completed 才应视为完整成功；incomplete、failed 等状态必须进入业务失败或补偿流程。
  • 文本优先读取 SDK 的 response.output_text；直接 HTTP 客户端应遍历 output，并提取 message 内容中的 output_text 项。
  • 函数调用的 arguments 是 JSON 字符串，不是已经解析好的对象。解析、校验并在服务端执行后，再以 function_call_output 输入项继续请求。
  • 网络搜索结果可能包含带注释的文本和引用信息；展示给用户前保留引用关系，不要只截取纯文本。
Request

请求

/v1/responses

Body

必填
Bodyapplication/json
Bodyobject
modelstring必填

模型 ID。本站账号可用模型以模型列表和实际权限为准；示例使用 gpt-6-astra。

示例gpt-6-astra
inputoneOf必填

文本或输入项目数组；数组可包含 user/developer 消息、input_text、input_image、input_file。

满足其中一个分支
分支 1string
示例用一句话介绍青云TOP API。
toolsarray<object>

function、web_search、file_search 等工具声明；本站是否能路由到对应上游能力取决于模型和渠道。

元素数量：1–∞
元素object
typestring必填

工具类型，如 function 或 web_search；内置工具受模型和渠道能力约束。

namestring
descriptionstring
parametersobject
strictboolean
Response

返回响应 200

成功响应
响应 200application/json
响应 200object
idstring必填

响应唯一标识。需要关联或排查请求时保存它。

示例resp_...
objectstring必填

固定为 response。不要用 choices 判断 Responses API 的返回。

固定值：response
statusstring必填

响应状态，常见值包括 completed、incomplete、failed、in_progress。业务成功判定应检查此字段。

可选值：queued、in_progress、completed、failed、incomplete
modelstring

实际使用的模型 ID。

示例gpt-6-astra
outputarray<oneOf>必填
元素array<object>

输出项目数组，可能包含 message、function_call、reasoning 等不同类型。

满足其中一个分支
分支 1object
idstring

响应唯一标识。需要关联或排查请求时保存它。

示例msg_...
typeunknown必填
固定值：message
roleunknown必填
固定值：assistant
contentarray<object>必填
元素object
typeunknown必填
固定值：output_text
textstring必填
annotationsarray<object>
元素object
errorobject|null

失败信息。HTTP 200 仍可能对应 failed 或 incomplete 状态，必须同时检查此字段。

incomplete_detailsobject|null

响应未完成时的原因和细节。

usageobject

token 用量，通常包含 input_tokens、output_tokens、total_tokens 及其 details。

input_tokensinteger
output_tokensinteger
total_tokensinteger
Responses API

调用与返回说明

OpenAI 新项目的首选模型调用协议。它以 output 项目表达文本、工具调用和推理结果，不能按 Chat Completions 的 choices 结构读取。

请求时注意

  • 模型 ID 不要从示例中照抄。先调用 GET /v1/models，再选择返回列表中实际可用且支持当前协议的完整 ID。
  • Responses API 的 input 可以是字符串，也可以是带 role/content 的输入项目数组；图片、文件和工具调用必须使用官方规定的输入项目类型。
  • 不要把 Chat Completions 的 choices、message 或 delta 结构混用于 Responses API。

返回时注意

  • 先检查 HTTP 状态码，再检查 response.status。只有 status=completed 才应视为完整成功；incomplete、failed 等状态必须进入业务失败或补偿流程。
  • 文本优先读取 SDK 的 response.output_text；直接 HTTP 客户端应遍历 output，并提取 message 内容中的 output_text 项。
  • 函数调用的 arguments 是 JSON 字符串，不是已经解析好的对象。解析、校验并在服务端执行后，再以 function_call_output 输入项继续请求。
  • 网络搜索结果可能包含带注释的文本和引用信息；展示给用户前保留引用关系，不要只截取纯文本。

结果与引用

检查 Response 的 status，再遍历 output。搜索调用通常是 type: web_search_call 项；文字位于 message 的 output_text，来源可能以 annotations 或相关引用数据返回。保留上游提供的标题、URL 和文字位置；只渲染实际返回的引用，不从普通回答文字推测引用来源。

搜索无结果、工具不可用或请求失败时，向调用者说明来源不足，不要把生成式回答标成实时检索结果。本站不承诺搜索覆盖率或索引时效。

常见错误与参考

400：核对工具类型和模型是否支持；403：检查当前 Key 的模型权限；若请求成功但没有来源标注，按普通模型输出处理并告知未获得可验证引用。

OpenAI web search 指南 · 创建 Response