API 接入
联网搜索 API 允许您向互联网发起实时搜索，并获取结构化的网页结果列表。您可以将其集成到 AI 问答、内容聚合、舆情监控、知识增强等场景中，为您的应用提供实时、多源的外部知识支撑。
提供 2 种搜索模式：
1. Pro 版，适合复杂问题搜索，提供更相关、更权威的结果，支持搜索全球信源
2. Lite 版，适合日常问题搜索，响应更快、成本更低
认证方式
通过 阿里云 SDK 调用 CleverSee - 联网搜索 服务，具体调用指南请参考：WebSearch - 联网搜
接口详情
请求参数
字段名称 | 类型 | 字段详情 |
body | object | 请求体参数 |
query | string | 查询词，支持自然语言表达。建议长度不超过 100 个字符。 示例值： |
limit | integer<int32> | 返回结果的最大条数。支持 1 至 10，默认值为 10。 示例值： |
includeDomain | array<string> | 白名单站点，配置后、将仅返回指定域名范围内的结果。单次请求最多支持 30 个站点。 注意：仅 region 参数设置为 global 时生效 |
string | 示例值： | |
excludeDomain | array<string> | 黑名单站点，配置后、将排除指定域名范围内的结果。单次请求最多支持 30 个站点 |
string | 示例值： | |
startTime | string | 返回该日期后（包含当天）的搜索结果，格式为 “YYYY-MM-DD”。不填则不限制起始时间。 示例值： |
endTime | string | 返回该日期前（包含当天）的搜索结果，格式为 “YYYY-MM-DD”。不填则不限制截止时间。 示例值： |
region | string | 搜索信源范围。当前支持 mainland_china（中国内地）、 global（全球）。默认值为 mainland_china。 注意：如您选择 global（全球），您的数据可能出境，请您自行评估相关风险。如继续操作视为您已完成评估且相关数据出境的风险和责任由您自行承担。 示例值： 枚举值：
|
searchType | string | 搜索模式。当前支持 pro、lite 两种搜索模式。默认值为 pro。 注意：lite 模式下，不支持传入 region、excludeDomain、includeDomain 参数 示例值： 枚举值：
|
请求说明
start_date与end_date均为可选参数，可单独使用，也可组合使用以限定时间区间。时间过滤基于网页的发布时间（date），若网页未标注发布时间，则该条结果不受时间参数约束。
返回参数
字段名称 | 类型 | 字段详情 |
code | integer<int32> | 业务状态码。200 表示请求成功，其他值表示异常，详见文档「错误码」部分。 示例值： |
message | string | 状态描述。成功时为 successful ，失败时为具体的错误信息。 示例值： |
data | object | 搜索结果数据，仅在 code 字段值为 200 时存在。 |
total | integer<int32> | 本次搜索命中的结果总条数 示例值： |
result | array<object> | 搜索结果列表 |
object | Result 对象 | |
title | string | 网页标题 示例值： |
url | string | 网页原始链接 示例值： |
snippet | string | 网页摘要片段 示例值：
|
date | string | 网页发布时间，格式为 ISO 8601。 示例值： |
source | object | 网页来源信息，包含 favicon、domain、name 字段。 |
name | string | 网站的名称，通常与域名一致 或 为网站的中文名称。 示例值： |
domain | string | 网站的域名。 示例值： |
favicon | string | 网站的图标链接。 示例值： |
返回说明
关于时间过滤精度：start_date 和 end_date 的过滤粒度为天（精确到日期），且依赖于网页自身标注的发布时间。对于未标注发布时间的网页，时间过滤不生效。
关于结果去重：同一 URL 在单次请求中不会重复出现，但不同请求之间不保证结果集完全不同。
关于 snippet 的使用：snippet 为搜索引擎返回的短摘要，内容可能被截断，不代表网页全文。如需完整正文，请自行抓取对应 url 的页面内容。
成功响应示例
{
"code": 200,
"message": "successful",
"data": {
"total": 2,
"result": [
{
"snippet": "阿里云-阿里巴巴集团旗下的云计算及人工智能科技公司之一...",
"date": "2025-12-10T16: 00: 00Z",
"source": {
"favicon": "https://domain.com/sample_img_1.png",
"domain": "www.aliyun.com",
"name": "阿里云"
},
"title": "阿里云-计算，为了无法计算的价值",
"url": "http://www.aliyun.com/"
},
{
"snippet": "云计算服务和云解决方案...",
"date": "2025-12-10T16: 00: 00Z",
"source": {
"favicon": "https://domain.com/sample_img_2.webp",
"domain": "www.alibabacloud.com",
"name": "www.alibabacloud.com"
},
"title": "云计算服务和云解决方案 - 阿里云",
"url": "https://www.alibabacloud.com/zh/iat/homepage-new-test?_p_lc=1"
}
]
}
}
失败响应示例
{
"code": 401,
"message": "Invalid request parameters"
}
错误码
错误码 | message | 说明 | 建议处理方式 |
| Partial results returned due to compliance restrictions | 部分搜索结果因合规要求被拦截 | 检查 Query 是否合规，或忽略被拦截的内容、直接使用当前返回的结果。 |
| Request blocked due to legal and regulatory requirements | 基于安全考虑，请求被拦截。本次请求不计费 | 检查 Query 参数内容是否合法合规，修改后可重新发起请求。 |
| Request was denied due to user flow control | 请求过于频繁，超出 QPS 阈值 | 降低调用频率。 |
| Invalid request parameters | 请求参数不合法 | 检查请求参数格式和长度，修改后重新发起请求。 |
| Internal server error | 服务内部错误 | 稍后重试；若持续出现，请联系技术支持并提供请求时间和参数。 |
| The request has failed due to a temporary failure of the server | 服务器繁忙或正在维护，当前请求无法完成。 | 建议您稍等片刻后刷新页面重试，若问题持续存在，请联系技术支持。 |