联网搜索API参考-智能开放搜索 OpenSearch(Open Search)-阿里云帮助中心

AI搜索开放平台提供联网搜索功能，支持直接调用联网搜索API或调用内容生成服务时启用联网搜索。

服务列表

服务名称	服务ID	服务描述	API调用QPS限制（含主账号与RAM子账号）
联网搜索服务	ops-web-search-001	提供通用的联网搜索服务，可配合大模型拓展私有知识库场景的回答。	3 说明如需扩充QPS，请通过工单联系技术支持协助。

获取身份鉴权信息

通过API调用AI搜索开放平台服务时，需要对调用者身份进行鉴权，如何获取鉴权信息请参见获取API-KEY。
获取服务调用地址

支持通过公网和VPC两种方式调用服务，详情请参见获取服务接入地址。

请求方式

POST

URL

{host}/v3/openapi/workspaces/{workspace_name}/web-search/{service_id}

host：调用服务的地址，支持通过公网和VPC两种方式调用API服务，可参见获取服务接入地址。

在API Keys页面顶部选择目标工作空间（如default(默认空间)），在访问域名区域切换公网API域名或私网API域名标签查看对应的服务接入地址。

workspace_name：工作空间名称，例如default。
service_id：系统内置服务ID，例如ops-web-search-001。

请求参数

Header参数

API-KEY认证

参数	类型	必填	描述	示例值
Content-Type	String	是	请求类型：application/json	application/json
Authorization	String	是	API-Key	Bearer OS-d1**2a

Body参数

参数	类型	必填	描述	默认值
query	String	是	搜索词。
query_rewrite	Boolean	否	是否启用LLM对query进行重写，默认值为true。	true
top_k	Integer	否	搜索返回结果数。	5
history	List	否	用户与模型的对话历史。list中的每个元素形式为{"role":角色, "content":内容}，角色当前可选值：system、user、assistant。 system：表示系统级消息，只能用于对话历史的第一条（messages[0]）。使用system角色是可选的，如果存在，必须位于列表的最开始。 user和assistant：表示用户和模型的对话。它们应交替出现在对话中，模拟实际对话流程。	null
content_type	String	否	搜索结果内容类型。当content_type取值为summary或mainText时，也会返回snippet。 snippet：网页内容的简短描述，无解析策略。 summary：网页内容的文本摘要，耗时相比snippet会增加，无解析策略。 mainText：网页内容的正文，包含网页解析策略。	snippet
way	String	否	仅搜索+无网页正文解析策略，当content_type=snippet/summary时生效。取值必须使用小写： lite (基础搜索) pro (增强搜索) 不传该参数或传空值时，按pro处理。搜索+网页正文解析策略，以content_type=mainText生效时。取值必须使用小写： lite (基础搜索+快速网页解析) pro (增强搜索+快速网页解析) pro-fetch (增强搜索+深度网页解析) 不传该参数或传空值时，按pro处理。	pro
time_range	String	否	时效性过滤，仅返回发布时间在该时间范围内的搜索结果。取值必须使用小写： day（一天内） week（一周内） month（一个月内） year（一年内） no_limit（不限制，等效于不传该参数）取值大小写敏感，传入其他值将返回错误。	no_limit

Curl请求示例

curl -X POST \
-H "Content-Type: application/json" \
-H "Authorization: Bearer 您的API-KEY" \
"http://xxxx-hangzhou.opensearch.aliyuncs.com/v3/openapi/workspaces/default/web-search/ops-web-search-001" \
-d '{
      "history": [
        {"role": "system", "content": "你是一个机器人助手"},
        {"role": "user", "content": "浙江的省会是哪里"},
        {"role": "assistant", "content": "杭州"}
        ],
      "query":"杭州今日天气怎么样",
      "query_rewrite":true,
      "top_k":5,
      "content_type":"snippet"
}'

指定搜索与正文提取策略

通过way指定更高效果的搜索与正文提取策略，配合content_type取值mainText获取网页正文。

curl -X POST \
-H "Content-Type: application/json" \
-H "Authorization: Bearer 您的API-KEY" \
"http://xxxx-hangzhou.opensearch.aliyuncs.com/v3/openapi/workspaces/default/web-search/ops-web-search-001" \
-d '{
      "query":"杭州今日天气怎么样",
      "top_k":5,
      "content_type":"mainText",
      "way":"pro-fetch"
}'

指定时效性范围

通过time_range限制搜索结果的发布时间范围，例如仅返回一天内的结果。

curl -X POST \
-H "Content-Type: application/json" \
-H "Authorization: Bearer 您的API-KEY" \
"http://xxxx-hangzhou.opensearch.aliyuncs.com/v3/openapi/workspaces/default/web-search/ops-web-search-001" \
-d '{
      "query":"云栖大会",
      "top_k":10,
      "time_range":"day"
}'

返回参数

参数	类型	描述	示例值
result.search_result	List<search_result>	本次联网搜索返回的结果。
result.search_result[].title	String	网页标题。	杭州天气
result.search_result[].link	String	网页链接。	https://www.xxx.com
result.search_result[].snippet	String	网页摘要。	今天夜里多云；明天晴到多云；后天多云到阴
result.search_result[].content	String	网页内容。content_type取值为snippet时返回网页摘要，取值为mainText时返回网页正文，正文长度通常远大于摘要。	杭州气象微博\n较昨日同期持平\n相对湿度： -- % 风力： --
result.search_result[].position	Integer	网页在召回结果中的位置。当前版本该字段固定返回null。	null
result.search_result[].meta_info.publishedTime	String	网页的发布时间。	2026-07-03T04:25:40Z
usage	Object	计费项与对应的调用次数，键名格式为服务ID/策略。当way取值为pro-fetch且content_type=mainText时，深度网页解析生效，会同时产生ops-web-search-001/pro-fetch与ops-web-search-001/pro两个计费项；其余情况下仅产生一个计费项。	"ops-web-search-001/pro": 1

响应示例

正常响应示例

{
  "request_id": "5B9F5A24-8F1D-****-B7E2-3C6A1D9E4F02",
  "latency": 2.3,
  "usage": {
    "ops-web-search-001/pro-fetch": 1,
    "ops-web-search-001/pro": 1
  },
  "result": {
    "search_result": [
      {
        "title": "杭州气象微博",
        "link": "https://www.hzqx.cn/pc/hztq/",
        "snippet": "较昨日同期 持平 相对湿度：-%风力：-气压：-hPa 近1小时降水:-mm 能见度：-m 实时数据、未经人工复核 2026年08月26日 10时55分 ...2026-08-26 08:00 更新 空气质量预报 杭州市环境监测站和杭州市气 ...",
        "position": null,
        "meta_info": {
          "publishedTime": "2026-08-26T10:55:00+08:00"
        },
        "content": "杭州气象微博\n较昨日同期 持平\n相对湿度： -- % 风力： --\n气压： -- hPa 近1小时降水: -- mm\n能见度： -- m\n\n# \\*实时数据、未经人工复核\n\n2026年08月26日 10时55分 过去24小时 未来24小时 未来7天\n\n# 主城区 未来7天天气客观预报 （该预报数据为\n...（此处省略，实际返回为完整网页正文）"
      },
      {
        "title": "杭州7天天气",
        "link": "https://www.ip.cn/tianqi/zhejiang/hangzhou/7day.html",
        "snippet": "杭州天气：2026-08-20至2026-08-26 天气预报 一 二 三 四 五 六 日 08月20日 中雨转多云 25℃～31℃ 日出05:29 日落18:36 08月21日 小雨转阴 25℃～32℃ 日出05:29 日落18:35 0 ...",
        "position": null,
        "meta_info": {
          "publishedTime": "2026-08-21T00:00:00+08:00"
        },
        "content": "杭州7天天气\n27° 多云 20 优\n东风 <3级 湿度 96% 气压 1001 Pa\n最新浙江省杭州市7天天气，包含每天最高气温、最低气温、天气状况及风向等天气信息\n今天 7天 10天 15天 最近30天\n杭州天气：2026-08-20至2026-08-26 天气预报\n\n| 一 | 二 | 三 |\n...（此处省略，实际返回为完整网页正文）"
      }
    ]
  }
}

异常响应示例

在访问请求出错的情况下，输出的结果中会通过code和message指明出错原因。

{
    "request_id": "6F33AFB6-A35C-****-AFD2-9EA16CCF4383",
    "latency": 2.0,
    "code": "InvalidParameter",
    "http_code": 400,
    "message": "JSON parse error: Cannot deserialize value of type `ImageStorage` from String \\"xxx\\"
}

状态码说明

HTTP 状态码	错误码	描述
200	-	请求成功，包括任务失败场景，实际任务状态需从result.status中判断
404	BadRequest.TaskNotExist	任务不存在
400	InvalidParameter	不合法请求
500	InternalServerError	内部错误

详情请参见AI搜索开放平台状态码说明。