腾讯云联网搜索API完全对接指南：从开通到生产级调用
1. 联网搜索API概述
联网搜索API（Web Search API，简称WSA）是腾讯云提供的一项基于互联网全网公开资源的智能搜索服务。该服务的底层搜索引擎来源于中文互联网领先的搜狗搜索，实现了从数据收录、索引构建到召回排序的全链路智能搜索增强。开发者通过检索词发起请求，API将以JSON格式返回包含标题、摘要、内容来源URL、发布时间、相关性得分等在内的搜索结果数据。
联网搜索API的核心价值在于为各类应用赋予实时联网搜索能力。无论是大模型应用需要打破知识截止日期的局限，还是智能体需要获取最新的政策新闻、市场动态，亦或是内容创作平台需要自动检索行业数据与学术资料，联网搜索API都能提供高可用、高性能的搜索服务支撑。API接口请求域名为wsa.tencentcloudapi.com，推荐使用API Explorer进行在线调试与签名验证。
需要先登录腾讯云控制台，点击：腾讯云控制台，还没有账号，点击：注册后再关联，已有账号点击：登录后再关联
2. 两种接入方式的选择
为满足不同开发场景与安全要求，腾讯云联网搜索API提供两种快速接入方式：
2.1 方式一：腾讯云标准方式（AK/SK签名认证）
该方式使用腾讯云账号的SecretId和SecretKey生成签名进行身份认证，鉴权体系基于腾讯云访问管理CAM。服务域名为wsa.tencentcloudapi.com。此方式适合对安全性、审计要求较高的企业级后端服务生产环境。开发门槛相对较高，需要实现签名算法，但腾讯云API 3.0 Explorer支持在线调试、验证签名，并可自动生成Python、Java、PHP、Go、Node.js、.Net等多种语言的SDK代码示例。
2.2 方式二：服务API KEY方式
该方式通过HTTP Header携带Authorization: Bearer YOUR_API_KEY进行认证，由联网搜索API服务自行鉴权。服务域名为api.wsa.cloud.tencent.com。此方式兼容主流大模型服务商、搜索服务商的API KEY认证鉴权机制，特别适合大模型、Agent开发项目的统一开发集成、复用和迁移。开发门槛相对较低，可通过HTTP客户端直接调用。
两种方式的核心差异在于认证机制与适用场景。企业级生产环境推荐使用AK/SK签名方式以获取更完善的CAM权限管理和审计能力；而快速原型开发、大模型应用集成则推荐使用API KEY方式以降低接入成本。
3. 开通服务与获取密钥
3.1 开通联网搜索API服务
注册腾讯云账号并通过实名认证后，登录联网搜索控制台，阅读并同意服务条款，单击立即开通即可获得联网搜索的API接口调用权限。开通后，用户可根据实际需求选择标准版、尊享版等不同服务等级。
3.2 API KEY方式的密钥获取
进入联网搜索API控制台，在概览页面的服务API KEY方式界面，单击创建API KEY。输入服务密钥名称后单击确定，系统将弹窗返回创建的API KEY。建议单击下载CSV文件保存至本地，或单击复制后另行妥善保存。API KEY是调用接口的重要凭证，丢失后需重新创建。
3.3 AK/SK方式的密钥获取
前往腾讯云官网控制台的API密钥管理界面获取密钥。单击新建密钥，系统将生成SecretId和SecretKey。同样建议下载CSV文件保存至本地。SecretId用于标识调用者身份，SecretKey用于生成签名，两者需配套使用。
4. API Explorer在线调试
腾讯云API 3.0 Explorer是一个强大的在线调试工具，支持联网搜索API的在线调用、签名验证、SDK代码生成和快速检索接口等能力。通过API Explorer，开发者可以查看每次调用的请求内容和返回结果，并自动生成SDK调用示例。
使用API Explorer调试联网搜索API的步骤如下：进入API Explorer页面，选择产品为联网搜索（WSA），选择接口SearchPro。填写必要的输入参数后单击发起调用，即可在响应结果中查看返回的搜索结果。API Explorer还提供了签名串生成功能，可选择签名版本为API 3.0签名v1或v3，生成签名过程进行验证。
5. SearchPro接口参数详解
SearchPro是联网搜索API的核心接口，用于执行搜索请求并返回结果。以下对各参数进行详细说明：
5.1 必填参数
Action：公共参数，本接口固定取值SearchPro。Version：公共参数，本接口固定取值2025-05-08。Query：搜索词，字符串类型，例如\"今天北京的天气\"。
5.2 可选参数
Mode：返回结果类型，取值0表示自然检索结果（默认），1表示多模态VR结果，2表示混合结果（多模态VR结果+自然检索结果）。Site：指定域名站内搜索，用于过滤自然检索结果，例如设置为\"zhihu.com\"则仅返回知乎域名的结果。FromTime和ToTime：起始时间和结束时间，用于按时间范围过滤自然检索结果，精确到秒的时间戳格式。Cnt：返回结果条数，可取10、20、30、40、50，最多支持返回50条搜索结果，仅限尊享版使用。Industry：行业过滤，取值gov（党政机关）、news（权威媒体）、acad（学术英文）、finance（金融），仅限尊享版使用。
注意：Mode=1模式下，Site、FromTime、ToTime参数无效；Mode=0模式下，这些参数对所有结果生效；Mode=2模式下，这些参数仅对输出的自然结果生效。
6. 返回数据结构
SearchPro接口返回JSON格式的数据，主要字段如下：
Query：原始查询语句。Pages：搜索结果页面详情数组，每个元素为JSON字符串，包含以下子字段——title（结果标题）、date（内容发布时间）、url（内容来源URL）、passage（标准摘要）、content（动态摘要，尊享版字段）、site（网站名称）、score（相关性得分，取值0~1，越靠近1表示越相关）、images（图片列表）、favicon（网站图标链接）。Version：用户版本，取值standard/premium/lite/flagship。Msg：提示信息。RequestId：唯一请求ID，由服务端生成，每次请求都会返回，定位问题时需要提供该次请求的RequestId。返回JSON数据时最大限制为50MB，如果返回的数据超过最大限制，请求会失败并返回内部错误。
7. Python完整对接示例
7.1 API KEY方式（推荐快速接入）
以下为使用API KEY方式调用联网搜索API的Python完整示例：
import requests
import json
# 配置信息
API_KEY = \"your_api_key_here\"
URL = \"https://api.wsa.cloud.tencent.com/v1/search\"
# 构建请求参数
params = {
\"query\": \"人工智能最新进展\",
\"mode\": 0, # 0-自然检索，1-多模态VR，2-混合
\"cnt\": 20 # 返回结果数量
}
# 构建请求头
headers = {
\"Authorization\": f\"Bearer {API_KEY}\",
\"Content-Type\": \"application/json\"
}
# 发送请求
response = requests.post(URL, json=params, headers=headers)
# 处理响应
if response.status_code == 200:
data = response.json()
print(f\"查询语句: {data.get('Query')}\")
print(f\"返回条数: {len(data.get('Pages', []))}\")
for idx, page in enumerate(data.get('Pages', [])):
page_data = json.loads(page)
print(f\"{idx+1}. {page_data.get('title')} - {page_data.get('site')}\")
print(f\" 摘要: {page_data.get('passage')[:100]}...\")\
print(f\" 链接: {page_data.get('url')}\")
print(f\" 相关性: {page_data.get('score')}\")\
print(\"---\")
else:
print(f\"请求失败: {response.status_code}\")
print(response.text)7.2 AK/SK签名方式（企业级生产环境）
使用腾讯云官方Python SDK进行签名认证调用：
from tencentcloud.common import credential
from tencentcloud.common.profile.client_profile import ClientProfile
from tencentcloud.common.profile.http_profile import HttpProfile
from tencentcloud.wsa.v20250508 import wsa_client, models
import json
# 配置密钥
cred = credential.Credential(\"your_secret_id\", \"your_secret_key\")
# 配置HTTP
httpProfile = HttpProfile()
httpProfile.endpoint = \"wsa.tencentcloudapi.com\"
# 配置客户端
clientProfile = ClientProfile()
clientProfile.httpProfile = httpProfile
client = wsa_client.WsaClient(cred, \"\", clientProfile)
# 构建请求
req = models.SearchProRequest()
params = {
\"Query\": \"新能源汽车市场趋势\",
\"Mode\": 0,
\"Cnt\": 20,
\"FromTime\": 1690000000,
\"ToTime\": 1730000000
}
req.from_json_string(json.dumps(params))
# 发起调用
try:
resp = client.SearchPro(req)
data = json.loads(resp.to_json_string())
print(f\"查询语句: {data.get('Query')}\")
for page in data.get('Pages', []):
page_data = json.loads(page)
print(f\"标题: {page_data.get('title')}\")
print(f\"来源: {page_data.get('site')}\")
print(f\"发布时间: {page_data.get('date')}\")
print(\"---\")
except Exception as e:
print(f\"调用失败: {e}\")8. Node.js完整对接示例
8.1 API KEY方式
const axios = require('axios');
const API_KEY = 'your_api_key_here';
const URL = 'https://api.wsa.cloud.tencent.com/v1/search';
const params = {
query: '深度学习模型部署',
mode: 0,
cnt: 20
};
axios.post(URL, params, {
headers: {
'Authorization': `Bearer ${API_KEY}`,
'Content-Type': 'application/json'
}
})
.then(response => {
const data = response.data;
console.log(`查询语句: ${data.Query}`);
console.log(`返回条数: ${data.Pages ? data.Pages.length : 0}`);
if (data.Pages) {
data.Pages.forEach((page, index) => {
const pageData = JSON.parse(page);
console.log(`${index+1}. ${pageData.title} - ${pageData.site}`);
console.log(` 摘要: ${pageData.passage ? pageData.passage.substring(0, 100) : ''}...`);
console.log(` 链接: ${pageData.url}`);
console.log('---');
});
}
})
.catch(error => {
console.error('请求失败:', error.message);
});8.2 AK/SK签名方式
使用腾讯云官方Node.js SDK：
const tencentcloud = require('tencentcloud-sdk-nodejs');
const WsaClient = tencentcloud.wsa.v20250508.Client;
const clientConfig = {
credential: {
secretId: 'your_secret_id',
secretKey: 'your_secret_key'
},
region: '',
profile: {
httpProfile: {
endpoint: 'wsa.tencentcloudapi.com'
}
}
};
const client = new WsaClient(clientConfig);
const params = {
Query: '量子计算商业化',
Mode: 2,
Cnt: 30,
Site: 'nature.com'
};
client.SearchPro(params).then(
(data) => {
console.log(`查询语句: ${data.Query}`);
if (data.Pages) {
data.Pages.forEach((page, index) => {
const pageData = JSON.parse(page);
console.log(`${index+1}. ${pageData.title}`);
console.log(` 来源: ${pageData.site}`);
console.log(` 相关性得分: ${pageData.score}`);
});
}
},
(err) => {
console.error('调用失败:', err);
}
);9. 请求结构与通信协议
腾讯云API的所有接口均通过HTTPS进行通信，提供高安全性的通信通道。API支持就近地域接入，推荐使用就近地域接入域名wsa.tencentcloudapi.com。根据调用接口时客户端所在位置，系统会自动解析到最近的某个具体地域的服务器。对时延敏感的业务，建议指定带地域的域名，例如广州地域的域名为wsa.ap-guangzhou.tencentcloudapi.com。
支持的HTTP请求方法包括POST（推荐）和GET。POST请求支持的Content-Type类型包括：application/json（推荐，必须使用签名方法v3 TC3-HMAC-SHA256）、application/x-www-form-urlencoded（必须使用签名方法v1 HmacSHA1或HmacSHA256）、multipart/form-data（仅部分接口支持，必须使用签名方法v3）。GET请求的请求包大小不得超过32KB。POST请求使用签名方法v1时不得超过1MB，使用签名方法v3时支持10MB。所有通信均使用UTF-8编码。
10. 应用场景与最佳实践
10.1 大模型与智能体应用
联网搜索API最典型的应用场景是为大语言模型提供实时联网搜索能力。大模型的知识存在截止日期，而联网搜索API可以实时检索互联网最新信息，让模型生成与事实核查同步进行，答案准确率从模糊推测跃升至溯源级精准。开发者可以在构建大模型应用时配置联网搜索能力，提供时效精准的智能问答服务。腾讯云已率先将联网搜索API接入DeepSeek等大模型，实现了国内领先的联网搜索能力。
10.2 内容创作与行业研究
联网搜索API能支撑AI创作的文本生成、续写、改写等核心创作任务，自动检索最新行业数据、市场趋势、学术资料，为内容提供事实支撑和实时更新。在汽车智能座舱场景中，联网搜索API赋予车辆实时搜索能力，驾驶过程中可即时访问最新在线数据，准确获取景点信息、目的地天气等。
10.3 最佳实践建议
在生产环境中使用联网搜索API时，建议注意以下几点：首先，根据业务场景选择合适的接入方式——API KEY方式适合快速迭代和AI应用集成，AK/SK签名方式适合对安全审计有严格要求的企业环境。其次，合理设置Cnt参数控制返回结果数量，避免不必要的数据传输开销。再次，利用Site、FromTime、ToTime等过滤参数精准缩小搜索范围，提升结果相关性。最后，关注QPS限制并根据实际需求选择合适的产品版本。联网搜索API借助分布式计算和边缘节点缓存，最快可在300毫秒内返回搜索结果，处于行业领先水平。
11. 常见问题解答
Q1: 联网搜索API的QPS限制是多少？
QPS指每秒请求的并发数，1QPS即每秒同时支持请求接口1次，50QPS即每秒同时支持请求接口50次。具体QPS限制取决于用户购买的服务版本，标准版和尊享版具有不同的QPS配额。建议根据业务峰值需求选择合适版本，或通过升级服务等级、优化API调用策略来提升并发能力。
Q2: API KEY方式与AK/SK方式应该如何选择？
API KEY方式开发门槛较低，可通过HTTP客户端直接调用，兼容主流大模型服务商的认证机制，适合大模型、Agent开发项目的快速集成。AK/SK签名方式基于腾讯云CAM鉴权体系，安全性更高，适合对审计要求较高的企业级后端生产环境。建议原型验证阶段使用API KEY方式，生产环境根据安全策略选择AK/SK方式。
Q3: 搜索结果的Pages字段为什么是JSON字符串数组？
Pages字段的每个元素都是一个JSON格式的字符串，包含title、date、url、passage、site、score等子字段。这种设计便于在传输过程中保持数据结构的一致性，同时允许服务端灵活扩展字段而无需改动外层结构。开发者需要自行解析每个JSON字符串以提取具体字段内容。
Q4: 如何按时间范围过滤搜索结果？
使用FromTime和ToTime参数可以按发布时间过滤自然检索结果。这两个参数接受精确到秒的Unix时间戳格式。需要注意的是，Mode=1（多模态VR结果）模式下这两个参数无效；Mode=0模式下对所有结果生效；Mode=2模式下仅对输出的自然结果生效。
Q5: 联网搜索API支持站内搜索吗？
支持。通过Site参数可以指定域名进行站内搜索，用于过滤自然检索结果。例如设置Site=\"zhihu.com\"则只返回知乎域名的搜索结果。同样，该参数在Mode=1模式下无效，在Mode=0和Mode=2模式下按上述规则生效。
Q6: 调用失败时如何定位问题？
每次请求无论成功还是失败，服务端都会返回RequestId。定位问题时需要提供该次请求的RequestId。建议在代码中记录每次请求的RequestId和响应状态，便于向腾讯云技术支持反馈问题时快速定位。同时可以利用API Explorer的调试功能验证请求参数和签名是否正确。
