服务 API KEY 方式

最近更新时间:2026-04-17 11:29:11

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

步骤一:登录注册

注册并通过个人实名认证或企业认证后,登录 腾讯云。如果没有账号,请参考 注册腾讯云

步骤二:开通服务

进入联网搜索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.1
Host: api.wsa.cloud.tencent.com
Content-Type: application/json
Authorization: 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 os
import hashlib
import hmac
import json
import sys
import time
from datetime import datetime
if sys.version_info[0] <= 2:
from httplib import HTTPSConnection
else:
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 performance
private 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();
}

}