OpenAI 内置联网搜索 (web_search_preview)

说明

概述

OpenAI 在 Responses API 中提供原生内置联网工具 web_search_preview。OpenAI-Hub 完全透传，无需任何额外配置，只要在 tools[] 里加一项即可。

支持模型：gpt-4o、gpt-4o-mini、gpt-5、gpt-5-mini 等开启 search 的型号。Responses API 是 OpenAI 官方推荐路径；Chat Completions 也支持等价的 web_search 工具。

请求示例

1. 最小用法（非流式）

curl https://api.openai-hub.com/v1/responses \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o",
    "input": "苹果公司最近一次财报的营收是多少？",
    "tools": [
      { "type": "web_search_preview" }
    ]
  }'

2. 流式 + 控制搜索深度 + 地理位置

curl https://api.openai-hub.com/v1/responses \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o",
    "stream": true,
    "input": "上海明天天气",
    "tools": [
      {
        "type": "web_search_preview",
        "search_context_size": "medium",
        "user_location": {
          "type": "approximate",
          "country": "CN",
          "city": "Shanghai",
          "region": "Shanghai"
        }
      }
    ]
  }'

3. Chat Completions 兼容写法

如果你的客户端只支持 /v1/chat/completions：

{
  "model": "gpt-4o",
  "messages": [{ "role": "user", "content": "…" }],
  "tools": [{ "type": "web_search" }]
}

行为等价，引用以 tool_calls / tool_results 角色返回。

字段说明

响应（非流式）

{
  "id": "resp_xxx",
  "object": "response",
  "model": "gpt-4o",
  "output": [
    {
      "type": "web_search_call",
      "id": "ws_xxx",
      "status": "completed"
    },
    {
      "type": "message",
      "role": "assistant",
      "content": [
        {
          "type": "output_text",
          "text": "根据彭博社 2025 年 11 月发布的财报，苹果公司 Q4 营收达 949 亿美元...",
          "annotations": [
            {
              "type": "url_citation",
              "url": "https://www.bloomberg.com/...",
              "title": "Apple Q4 Earnings",
              "start_index": 0,
              "end_index": 25
            }
          ]
        }
      ]
    }
  ],
  "usage": { "input_tokens": 80, "output_tokens": 320, "total_tokens": 400 }
}

流式输出（关键事件序列）

event: response.created
event: response.output_item.added         # type=web_search_call status=in_progress
event: response.web_search_call.searching
event: response.web_search_call.completed
event: response.output_item.done          # web_search_call 完成
event: response.output_item.added         # type=message
event: response.content_part.added
event: response.output_text.delta         # 模型回答文字流式 delta
event: response.output_text.annotation.added  # 引用注解（url_citation）
event: response.output_text.done
event: response.content_part.done
event: response.output_item.done
event: response.completed

前端可监听 response.web_search_call.searching 显示「正在搜索」spinner，response.output_text.annotation.added 实时挂引用气泡。

同时使用自定义函数

web_search_preview 与 function 工具可以并行：

{
  "model": "gpt-4o",
  "input": "...",
  "tools": [
    { "type": "web_search_preview" },
    {
      "type": "function",
      "function": {
        "name": "get_weather",
        "description": "获取实时天气",
        "parameters": { "type": "object", "properties": { "city": { "type": "string" } } }
      }
    }
  ]
}

模型自主决定调哪个或两个都调。

请求头

响应