搜索 API

搜索 API 是一个强大的网页搜索服务，支持多种搜索参数和过滤选项，可以返回网页、图片和视频等多种类型的结果。该 API 兼容大部分返回格式。

基本信息

接口地址：/api/web-search
请求方式：POST
数据格式：JSON
字符编码：UTF-8

请求参数

必填参数

参数名	类型	必填	说明
query	string	是	搜索关键词，不能为空

可选参数

参数名	类型	必填	说明
count	int	否	每页返回的结果数，默认10，最大值50
offset	int	否	结果偏移量，用于分页，默认0
freshness	string	否	搜索指定时间范围内的网页，可选值： - noLimit：不限（默认） - oneDay：一天内 - oneWeek：一周内 - oneMonth：一个月内 - oneYear：一年内 - YYYY-MM-DD..YYYY-MM-DD：搜索日期范围，例如："2025-01-01..2025-04-06" - YYYY-MM-DD：搜索指定日期，例如："2025-04-06"

响应参数

响应示例

{
  "_type": "SearchResponse",
  "queryContext": {
    "originalQuery": "搜索关键词"
  },
  "webPages": {
    "webSearchUrl": "搜索URL",
    "totalEstimatedMatches": 1000,
    "value": [
      {
        "id": "结果ID",
        "name": "网页标题",
        "url": "网页URL",
        "displayUrl": "展示URL",
        "snippet": "内容摘要",
        "summary": "详细摘要",
        "siteName": "网站名称",
        "siteIcon": "网站图标",
        "datePublished": "发布时间",
        "dateLastCrawled": "爬取时间",
        "cachedPageUrl": "缓存页面URL",
        "language": "网页语言",
        "isFamilyFriendly": true,
        "isNavigational": false,
        "deepLinks": [
          {
            "name": "深度链接名称",
            "url": "深度链接URL",
            "snippet": "深度链接摘要"
          }
        ]
      }
    ]
  },
 
}

响应字段说明

SearchResponse

字段名	类型	说明
_type	string	响应类型，固定为"SearchResponse"
queryContext	object	查询上下文信息
webPages	object	网页搜索结果
images	object	图片搜索结果
videos	object	视频搜索结果

WebSearchQueryContext

字段名	类型	说明
originalQuery	string	原始搜索关键词

WebSearchWebPages

字段名	类型	说明
webSearchUrl	string	搜索URL
totalEstimatedMatches	int	搜索匹配的网页总数
value	array	搜索结果列表
someResultsRemoved	boolean	结果中是否有被安全过滤

WebPageValue

字段名	类型	说明
id	string	网页的排序ID
name	string	网页的标题
url	string	网页的URL
displayUrl	string	网页的展示URL（url decode后的格式）
snippet	string	网页内容的简短描述
summary	string	网页内容的文本摘要
siteName	string	网页的网站名称
siteIcon	string	网页的网站图标
datePublished	string	网页的发布时间（UTC+8时间）
dateLastCrawled	string	网页的爬取时间（UTC+8时间）
cachedPageUrl	string	网页的缓存页面URL
language	string	网页的语言
isFamilyFriendly	boolean	是否为家庭友好的页面
isNavigational	boolean	是否为导航性页面
deepLinks	array	深度链接列表

WebSearchImages

字段名	类型	说明
id	string	图片结果ID
readLink	string	图片搜索链接
webSearchUrl	string	图片搜索URL
isFamilyFriendly	boolean	是否为家庭友好的内容
value	array	图片结果列表

ImageValue

字段名	类型	说明
webSearchUrl	string	图片搜索URL
name	string	图片名称
thumbnailUrl	string	缩略图URL
datePublished	string	发布时间
contentUrl	string	图片内容URL
hostPageUrl	string	宿主页面URL
contentSize	string	内容大小
encodingFormat	string	编码格式
hostPageDisplayUrl	string	宿主页面展示URL
width	int	图片宽度
height	int	图片高度
thumbnail	object	缩略图信息

WebSearchVideos

字段名	类型	说明
id	string	视频结果ID
readLink	string	视频搜索链接
webSearchUrl	string	视频搜索URL
isFamilyFriendly	boolean	是否为家庭友好的内容
scenario	string	视频场景
value	array	视频结果列表

VideoValue

字段名	类型	说明
webSearchUrl	string	视频搜索URL
name	string	视频名称
description	string	视频描述
thumbnailUrl	string	缩略图URL
publisher	array	发布者信息
creator	object	创作者信息
contentUrl	string	视频内容URL
hostPageUrl	string	宿主页面URL
encodingFormat	string	编码格式
hostPageDisplayUrl	string	宿主页面展示URL
width	int	视频宽度
height	int	视频高度
duration	string	视频时长
motionThumbnailUrl	string	动态缩略图URL
embedHtml	string	嵌入HTML
allowHttpsEmbed	boolean	是否允许HTTPS嵌入
viewCount	int	观看次数
thumbnail	object	缩略图信息
allowMobileEmbed	boolean	是否允许移动端嵌入
isSuperfresh	boolean	是否为最新内容
datePublished	string	发布时间

错误码

错误码	说明
400	请求参数错误
401	未授权
403	禁止访问
404	资源不存在
429	请求过于频繁
500	服务器内部错误

注意事项

时间戳说明：
- datePublished：网页实际发布时间
- dateLastCrawled：网页爬取时间
- 所有时间戳均为UTC+8时间
分页说明：
- 每页最多返回50条结果
- 使用offset参数进行分页
- 建议每次请求不超过1000条数据
安全限制：
- 部分结果可能因安全原因被过滤
- 请检查someResultsRemoved字段确认是否有结果被过滤
性能建议：
- 合理使用freshness参数限制时间范围
- 使用include/exclude参数缩小搜索范围
- 避免频繁请求相同的关键词
兼容性说明：
- 部分字段可能在不同API中略有差异，但核心功能保持一致
- 建议根据实际使用的API版本查看具体的字段说明

调用示例

请求示例

curl -X GET "https://platform.kuaisou.com/api/web-search?query=人工智能&count=10&offset=0"

响应示例

{
  "_type": "SearchResponse",
  "queryContext": {
    "originalQuery": "人工智能"
  },
  "webPages": {
    "webSearchUrl": "https://platform.kuaisou.com/api/web-search?query=人工智能",
    "totalEstimatedMatches": 1000,
    "value": [
      {
        "id": "https://platform.kuaisou.com/api/v1/#WebPages.0",
        "name": "人工智能 - 维基百科",
        "url": "https://zh.wikipedia.org/wiki/人工智能",
        "displayUrl": "zh.wikipedia.org/wiki/人工智能",
        "snippet": "人工智能（Artificial Intelligence，缩写为AI）是指由人制造出来的系统所表现出的智能。",
        "summary": "人工智能是计算机科学的一个分支，它企图了解智能的实质，并生产出一种新的能以人类智能相似的方式做出反应的智能机器。",
      }
    ]
  }
}

搜索 API Python 调用示例

本文档提供了使用 Python 调用搜索 API 的简单示例代码。

基本调用示例

import requests
import json

def search_web(query, api_key, count=10, summary=False):
    """
    执行网页搜索
    
    参数:
        query (str): 搜索关键词
        api_key (str): API密钥
        count (int): 返回结果数量，默认10
        offset (int): 搜索页码
    """
    url = "https://platform.kuaisou.com/api/web-search"
    
    # 构建请求数据
    payload = json.dumps({
        "query": query,
        "offset": 1,
        "count": count
    })
    
    # 设置请求头
    headers = {
        'Authorization': f'Bearer {api_key}',
        'Content-Type': 'application/json'
    }
    
    # 发送请求
    response = requests.post(url, headers=headers, data=payload)
    
    # 检查响应状态
    if response.status_code == 200:
        return response.json()
    else:
        raise Exception(f"搜索请求失败: {response.status_code} - {response.text}")

# 使用示例
if __name__ == "__main__":
    # 设置API密钥
    API_KEY = "sk-********"  # 替换为您的API密钥
    
    try:
        # 执行搜索
        results = search_web(
            query="人活着是为了什么？",
            api_key=API_KEY,
            count=10,
            summary=True
        )
        
        # 打印结果
        print(json.dumps(results, indent=2, ensure_ascii=False))
        
    except Exception as e:
        print(f"发生错误: {str(e)}")

基本信息​

请求参数​

必填参数​

可选参数​

响应参数​

响应示例​

响应字段说明​

SearchResponse​

WebSearchQueryContext​

WebSearchWebPages​

WebPageValue​

WebSearchImages​

ImageValue​

WebSearchVideos​

VideoValue​

错误码​

注意事项​

调用示例​

请求示例​

响应示例​

搜索 API Python 调用示例

基本调用示例​

更多参数示例​

基本信息

请求参数

必填参数

可选参数

响应参数

响应示例

响应字段说明

SearchResponse

WebSearchQueryContext

WebSearchWebPages

WebPageValue

WebSearchImages

ImageValue

WebSearchVideos

VideoValue

错误码

注意事项

调用示例

请求示例

响应示例

基本调用示例

更多参数示例