初次使用联网搜索服务时,如果您通过服务 API KEY 方式接入服务,可参考本文的指引进行准备工作及入门操作。
操作步骤 | 说明 |
注册腾讯云账号,完成实名认证并登录 | |
控制台自助开通联网搜索API 服务 | |
获取联网搜索API 的服务密钥 API KEY | |
按照 API KEY 兼容模式,通过 API 接入 |
步骤一:登录注册
步骤二:开通服务

步骤三:创建服务密钥 API KEY
说明:
1. 每个 subuin(包括主账号)最多同时持有3个服务密钥 API KEY,请合理创建并分配使用。
2. 使用子账号创建和管理服务密钥 API KEY 时,须主账号事先前往 访问管理 控制台 为该子用户授予联网搜索API(WSA)全读写访问权限。
1. 进入联网搜索API 控制台,在概览 > 服务 API KEY 方式界面,单击创建 API KEY。

2. 输入服务密钥名称,单击确定。

3. 弹窗返回您创建的 API KEY,可单击下载 CSV 文件保存至本地。或单击复制后另行保存。
注意:
为降低服务密钥泄漏的风险,仅在创建时提供明文 API KEY,后续不可再进行查询,请保存好您的 API KEY。
服务密钥 API KEY 是您请求腾讯云联网搜索API 时的安全鉴权凭证。为了您的财产和服务安全,请妥善保存 API KEY,请勿通过任何方式上传或者公开分享您的密钥信息。

步骤四:接入 API
请根据下方接入指引,结合实际业务场景完成接入。
接口描述
接口名称:SearchPro
服务域名:api.wsa.cloud.tencent.com
请求协议:HTTPS
请求方式:POST
数据格式:Content-Type: application/json; charset=UTF-8
输入参数
参数名称 | 必选 | 类型 | 位置 | 描述 |
Authorization | 是 | String | Header | 身份验证令牌 示例值:Bearer xxxx |
Query | 是 | String | Body(JSON) | 搜索词 示例值:今天北京的天气 |
Mode | 否 | Integer | Body(JSON) | 返回结果类型,0-自然检索结果(默认),1-多模态 VR 结果,2-混合结果(多模态VR结果+自然检索结果) 示例值:2 |
Site | 否 | String | Body(JSON) | 指定域名站内搜索(用于过滤自然检索结果) 注意: mode=1模式下,参数无效;mode=0模式下,对所有结果生效;mode=2模式下,对输出的自然结果生效 示例值:zhihu.com |
FromTime | 否 | Integer | Body(JSON) | 起始时间(用于过滤自然检索结果),精确到秒时间戳格式 注意: mode=1模式下,参数无效;mode=0模式下,对所有结果生效;mode=2模式下,对输出的自然结果生效 示例值:1745498501 |
ToTime | 否 | Integer | Body(JSON) | 结束时间(用于过滤自然检索结果),精确到秒时间戳格式 注意:mode=1模式下,参数无效;mode=0模式下,对所有结果生效;mode=2模式下,对输出的自然结果生效 示例值:1745498501 |
Cnt | 否 | Integer | Body(JSON) | cnt=10/20/30/40/50,最多可支持返回50条搜索结果,仅限尊享版使用 示例值:10 |
Industry | 否 | String | Body(JSON) | Industry=gov/news/acad/finance,对应党政机关、权威媒体、学术(英文)、金融,仅限尊享版使用 示例值:news |
输出参数
输出媒体类型:application/json
参数名称 | 类型 | 描述 |
Query | String | 原始查询语 示例值:今天北京的天气 |
Pages | Array of String | 搜索结果页面详情,格式为 JSON 字符串。 title:结果标题 date:内容发布时间 url:内容发布源 URL passage:标准摘要 content:动态摘要 (尊享版字段) site:网站名称,部分不知名站点结果可能为空 score:相关性得分,取值0~1,越靠近1表示越相关 images:图片列表 favicon:网站图标链接,部分不知名站点结果可能为空 示例值:["{"passage":"aaa"}", "{"passage":"bbb"}"] |
Version | String | 用户版本:standard/premium/lite 示例值:standard |
Msg | String | 提示信息 示例值:hit black query |
RequestId | String | 唯一请求 ID,由服务端生成,每次请求都会返回(若请求因其他原因未能抵达服务端,则该次请求不会获得 RequestId)。定位问题时需要提供该次请求的 RequestId。 |
示例
输入示例
POST / HTTP/1.1Host: api.wsa.cloud.tencent.comContent-Type: application/jsonAuthorization: Bearer sk-209b****e23d{"Query": "三星堆的由来"}
输出示例
{"Response": {"Pages": ["{\\"passage\\":\\"三星堆名字的由来 三星堆遗址位于四川省广汉市西北部,距离成都约40公里,地理位置独特,被三条河流环绕,形成了天然的地理屏障。据《华阳国志》记载,古蜀国“有三江,皆发源于岷山,流至成都平原”。 这三条河流,即今之鸭子河、石亭江和郪江,在三星堆附近交汇,形成了一片肥沃的土地。三星堆之名,最初来源于这一地区的地形特征——三座小山丘呈三角状分布,犹如夜空中的三星,故得名“三星堆”。 三星堆名称的演变 三星堆遗址的发掘,始于20世纪20年代末期,但其真正引起广泛关注是在1986年两个大型祭祀坑的发现之后。在此之前,三星堆只是当地的一个地名,直到考古学家们在这里发现了大量的古代遗存,三星堆才逐渐成为了世界瞩目的焦点。 随着研究的深入,三星堆之名也从一个简单的地理标识,演变为承载着深厚历史文化的符号。\\",\\"score\\":0.897802,\\"date\\":\\"2024-06-07 19:00:51\\",\\"title\\":\\"三星堆名字的由来,你真的了解吗?三星堆的参观攻略,建议收藏青铜文物玉器古蜀国三星堆遗址_网易订阅\\",\\"url\\":\\"https://www.163.com/dy/article/J43Q2STU0553FV3Z.html\\",\\"site\\":\\"网易\\",\\"images\\":[],\\"favicon\\":\\"http://img01.sogoucdn.com/app/a/200913/a51423369a5d5a.png\\"}","{\\"passage\\":\\"一、地理环境因素三星堆遗址位于四川省广汉市,距离成都约40公里。在四川省广汉市西北部,有三座稍稍隆起的土堆呈直线排列,这种地形布局与夜空中闪烁的三颗星辰相呼应,因此得名“三星堆”。这三个土堆历史悠久,据考古学家研究,它们的存在可以追溯到3000多年前。这三个土堆不仅形态独特,而且在古代具有一定的宗教或象征意义。在三星堆遗址的东北方,有一段残破的城墙,这段城墙呈现出弯月形状,与三个土堆隔河相望。这种自然与人工相结合的景观,在当时的社会背景下,很可能被赋予了一定的神话色彩和宗教意义。这一景观组合在历史上更是被形象地称为“三星伴月”,进一步增添了三星堆名字的文化韵味。其中的“三星”指的就是那三个土堆,而“月”则是指那段弯月般的城墙。当地居民根据这一独特的地理特征,赋予了这片土地以“三星伴月”的美称。这种说法不仅反映了古人对于自然现象的崇拜和敬畏之情,同时也体现了人们对于美好事物的向往和赞美之心。随着时间的推移,这一称谓逐渐深入人心,并最终演变成了“三星堆”这一名称。\\",\\"score\\":0.8887853,\\"date\\":\\"2024-09-03 12:59:00\\",\\"title\\":\\"三星堆名字的由来_腾讯新闻\\",\\"url\\":\\"https://news.qq.com/rain/a/20240903A048N700\\",\\"site\\":\\"腾讯网\\",\\"images\\":[],\\"favicon\\":\\"http://img02.sogoucdn.com/app/a/200913/ab735a258a90e8.png\\"}","{\\"passage\\":\\"最早在1929年,一位当地农民在遗址区域内偶然发现了一个玉器坑,这一发现引起了考古界的关注。在四川省广汉市西北部,有<strong>三座稍稍隆起的土堆呈直线排列</strong>,这种地形布局与夜空中闪烁的<strong>三颗星辰</strong>相呼应,因此得名<strong>“三星堆”</strong>。\\",\\"score\\":0.86471426,\\"date\\":\\"2024-09-03 13:06:46\\",\\"title\\":\\"三星堆名字的由来\\",\\"url\\":\\"https://so.html5.qq.com/page/real/search_news?docid=70000021_14266d6996591252\\",\\"site\\":\\"企鹅号\\",\\"images\\":[],\\"favicon\\":\\"http://img02.sogoucdn.com/app/a/200913/ab735a25.png\\"}"],"Query": "三星堆的由来","RequestId": "6f8df221-9a68-4ea2-90d6-a9590cae244c"}}
错误码
当请求出现错误时,将返回 Error 对象,Error.Code 包含以下错误值:
错误码 | 描述 | 说明 |
InternalError | 内部错误。 | - |
InvalidParameter | 参数错误。 | - |
RequestLimitExceeded | 请求的次数超过了频率限制。 | - |
ResourceNotFound | 用户资源未开通。 | 请联系主账号开通服务。 |
ResourceUnavailable | 用户资源不可用。 | 请检查账号是否欠费。 |
UnauthorizedOperation | 未授权操作。 | 请检查服务密钥 API KEY 是否正确。 |
完整请求代码示例
Python 示例
# 本代码仅供参考,具体请参照接口文档和实际需求进行开发import osimport hashlibimport hmacimport jsonimport sysimport timefrom datetime import datetimeif sys.version_info[0] <= 2:from httplib import HTTPSConnectionelse:from http.client import HTTPSConnection# 密钥信息从环境变量读取,需要提前在环境变量中设置 TENCENTCLOUD_WSA_APIKEY# 使用环境变量方式可以避免密钥硬编码在代码中,提高安全性# 生产环境建议使用更安全的密钥管理方案,如密钥管理系统(KMS)、容器密钥注入等# 密钥可前往官网控制台进行获取secret_key = os.getenv("TENCENTCLOUD_WSA_APIKEY")payload = "{\\"Query\\":\\"三星堆的由来\\"}"params = json.loads(payload)host = "api.wsa.cloud.tencent.com"http_request_method = "POST"uri = "/SearchPro"# ************* 构造并发起请求 *************headers = {"Authorization": "Bearer " + secret_key,"Content-Type": "application/json; charset=utf-8",}try:req = HTTPSConnection(host)req.request(http_request_method, uri, headers=headers, body=payload.encode("utf-8"))resp = req.getresponse()print(resp.read().decode("utf-8"))except Exception as err:print(err)
Java 示例
// 本代码仅供参考,具体请参照接口文档和实际需求进行开发import io.pyroscope.okhttp3.MediaType;import io.pyroscope.okhttp3.OkHttpClient;import io.pyroscope.okhttp3.Request;import io.pyroscope.okhttp3.RequestBody;import io.pyroscope.okhttp3.Response;import java.io.IOException;public class Main {public static void main(String[] args) throws IOException {// 密钥信息从环境变量读取,需要提前在环境变量中设置 TENCENTCLOUD_WSA_APIKEY// 使用环境变量方式可以避免密钥硬编码在代码中,提高安全性// 生产环境建议使用更安全的密钥管理方案,如密钥管理系统(KMS)、容器密钥注入等// 密钥可前往官网控制台进行获取String apiKey = System.getenv("TENCENTCLOUD_WSA_APIKEY");String body = "{\\"Query\\":\\"三星堆的由来\\"}";String resp = doRequest(body, apiKey);System.out.println(resp);}// singleton client for connection reuse and better performanceprivate static final OkHttpClient client = new OkHttpClient();public static String doRequest(String body, String apiKey) throws IOException {Request request = buildRequest(body, apiKey);System.out.println(request.method() + " " + request.url());System.out.println(request.headers());System.out.println(body);Response response = client.newCall(request).execute();return response.body().string();}public static Request buildRequest(String body, String apiKey) {String contentType = "application/json; charset=utf-8";return new Request.Builder().header("Content-Type", contentType).header("Authorization", "Bearer " + apiKey).url("https://api.wsa.cloud.tencent.com/SearchPro").post(RequestBody.create(MediaType.parse(contentType), body)).build();}}