OpenAI 内置联网搜索 (web_search_preview)
POST
/v1/responses
概述
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. 最小用法（非流式）
2. 流式 + 控制搜索深度 + 地理位置
3. Chat Completions 兼容写法
/v1/chat/completions：{
"model": "gpt-4o",
"messages": [{ "role": "user", "content": "…" }],
"tools": [{ "type": "web_search" }]
}tool_calls / tool_results 角色返回。字段说明
| 字段 | 类型 | 默认 | 说明 |
|---|---|---|---|
type | string | — | 固定 web_search_preview |
search_context_size | enum | medium | low / medium / high，越大越贵越准 |
user_location | object | — | 地理位置提示，决定本地化语料 |
user_location.type | string | — | 固定 approximate |
user_location.country | string | — | ISO 3166-1 alpha-2 国家代码（CN / US / JP） |
user_location.city | string | — | 城市英文名 |
user_location.region | string | — | 省/州英文名 |
响应（非流式）
{
"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.completedresponse.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" } } }
}
}
]
}请求参数
Header 参数
返回响应
请求示例请求示例
Shell
JavaScript
Java
Swift
curl --location --request POST 'https://api.openai-hub.com/v1/responses' \
--header 'Authorization: Bearer sk-0ABIEXVjh9****Qckjy'响应示例响应示例
{}