中国科技云大模型API接口使用手册

外观

Web Search

约 1482 字大约 5 分钟

2025-06-03

网络搜索 API

请求方式: POST

请求地址: /web-search

请求头

Authorization: Bearer {API KEY}
鉴权参数，示例：Bearer xxxxxx，接口授权请联系cstcloud@cnic.cn。

Content-Type: application/json

请求参数

  • model: 必选 String 值为 web-search
  • query: 必选 String 用户的搜索词
  • freshness: 可选 String 搜索指定时间范围内的网页 可填值:
    • oneDay，一天内
    • oneWeek，一周内
    • oneMonth，一个月内
    • oneYear，一年内
    • noLimit，不限（默认）
    • YYYY-MM-DD..YYYY-MM-DD，搜索日期范围, 例如："2025-01-01..2025-04-06"
    • YYYY-MM-DD，搜索指定日期，例如："2025-04-06"
    • 推荐使用“noLimit”。搜索算法会自动进行时间范围的改写，效果更佳。如果指定时间范围，很有可能出现时间范围内没有相关网页的情况，导致找不到搜索结果。
  • summary: 可选 Boolean 是否显示文本摘要 可填值:
    • true，显示
    • false，不显示（默认）
  • include: 可选 String 指定搜索的 site 范围。多个域名使用|或,分隔，最多不能超过20个 可填值：
    • 根域名
    • 子域名
    • 例如：qq.com|m.163.com 也可以在query中使用site方式来指定搜索范围。例如："query" : "site:qq.com|m.163.com 阿里ESG报告"
  • exclude: 可选 String 排除搜索的网站范围。多个域名使用|或,分隔，最多不能超过20个 可填值：
    • 根域名
    • 子域名
    • 例如：qq.com|m.163.com
  • count: 可选 Int 返回结果的条数（实际返回结果数量可能会小于count指定的数量）。
    • 可填范围：1-50，最大单次搜索返回50条
    • 默认为10

响应格式

  • SearchData
    • _type: "SearchResponse" 搜索的类型
    • queryContext: WebSearchQueryContext
    • webPages: WebSearchWebPages 搜索的网页结果
    • images: WebSearchImages 搜索的图片结果
    • videos: WebSearchVideos 搜索的视频结果
  • WebSearchQueryContext
    • originalQuery:String 原始的搜索关键字
  • WebSearchWebPages
    • webSearchUrl: String
    • totalEstimatedMatches: int 搜索匹配的网页总数
    • value: List<WebPageValue>
    • someResultsRemoved: boolean 结果中是否有被安全过滤

  • WebPageValue

    • id: String 网页的排序ID
    • name: String 网页的标题
    • url: String 网页的URL
    • displayUrl: String 网页的展示URL（url decode后的格式）
    • snippet: String 网页内容的简短描述
    • summary: String 网页内容的文本摘要，当请求参数中 summary 为 true 时显示此属性
    • siteName: String 网页的网站名称
    • siteIcon: String 网页的网站图标
    • datePublished: String 网页的发布时间（例如：2025-02-23T08:18:30+08:00），UTC+8时间
    • dateLastCrawled: String 网页的发布时间（此处其实是发布时间，名字起为LastCrawled是兼容性适配）

    提示

    接口中返回的dateLastCrawled值（例如：2025-02-23T08:18:30Z）实际上要表达的是 UTC+8 北京时间2025-02-23 08:18:30，并非UTC时间。
    实际应用中请使用 datePublished 字段，或将"2025-02-23T08:18:30Z"替换成"2025-02-23T08:18:30+08:00"，即得到正确的UTC+8时间，可以使用 datetime 函数正确解析。
    这个问题我们会在将来v2版本中修复。

    • cachedPageUrl:String 网页的缓存页面URL
    • language: String 网页的语言
    • isFamilyFriendly: boolean 是否为家庭友好的页面
    • isNavigational: boolean 是否为导航性页面
  • WebSearchImages
    • id: String
    • readLink: String
    • webSearchUrl: String
    • isFamilyFriendly: boolean
    • value: List<ImageValue>
  • WebSearchVideos
    • id: String
    • readLink: String
    • webSearchUrl: String
    • isFamilyFriendly: boolean
    • scenario: String
    • value: List<VideoValue>
  • ImageValue
    • webSearchUrl: String
    • name: String
    • thumbnailUrl: String
    • datePublished: String
    • contentUrl: String
    • hostPageUrl: String
    • contentSize: String
    • encodingFormat: String
    • hostPageDisplayUrl: String
    • width: int
    • height: int
    • thumbnail: Thumbnail
  • VideoValue
    • webSearchUrl: String
    • name: String
    • description: String
    • thumbnailUrl: String
    • publisher: List<Publisher>
    • creator: Creator
    • contentUrl: String
    • hostPageUrl: String
    • encodingFormat: String
    • hostPageDisplayUrl: String
    • width: int
    • height: int
    • duration: String
    • motionThumbnailUrl: String
    • embedHtml: String
    • allowHttpsEmbed: boolean
    • viewCount: int
    • thumbnail: Thumbnail
    • allowMobileEmbed: boolean
    • isSuperfresh: boolean
    • datePublished: String
  • Creator
    • name: String
  • Publisher
    • name: String
  • Thumbnail
    • height: int
    • width: int
  • RankingResponse
    • mainline: Mainline
  • Mainline
    • items: List<MainlineItem>
  • MainlineItem
    • answerType: String
    • value: MainlineItemValue
  • MainlineItemValue
    • id: String

调用示例

请求内容

//body
{
    "query": "阿里巴巴2024年的esg报告",
    "freshness": "noLimit",
    "summary": false, // 当设置为 true 的时候显示摘要
    "count": 10
}

响应内容

{
    "code": 200,
    "log_id": "d71841ad20095f61",
    "msg": null,
    "data": {
        "_type": "SearchResponse",
        "queryContext": {
            "originalQuery": "阿里巴巴2024年的esg报告"
        },
        "webPages": {
            "webSearchUrl": "",
            "totalEstimatedMatches": 8912791,
            "value": [
                {
                    "id": null,
                    "name": "阿里巴巴发布2024年ESG报告　持续推进减碳与数字化普惠",
                    "url": "https://www.alibabagroup.com/document-1752073403914780672",
                    "displayUrl": "https://www.alibabagroup.com/document-1752073403914780672",
                    "snippet": "阿里巴巴集团发布《2024财年环境、社会和治理（ESG）报告》（下称“报告”），详细分享过去一年在ESG各方面取得的进展。报告显示，阿里巴巴扎实推进减碳举措，全集团自身运营净碳排放和价值链碳...",
                    "siteName": "www.alibabagroup.com",
                    "siteIcon": "https://th.bochaai.com/favicon?domain_url=https://www.alibabagroup.com/document-1752073403914780672",
                    "dateLastCrawled": "2024-07-22T00:00:00Z",
                    "cachedPageUrl": null,
                    "language": null,
                    "isFamilyFriendly": null,
                    "isNavigational": null
                },
                {
                    "id": null,
                    "name": "阿里巴巴发布2024年ESG报告: 保持前瞻、保持善意、保持务实",
                    "url": "https://mparticle.uc.cn/article_org.html?uc_param_str=frdnsnpfvecpntnwprdssskt#!wm_cid=632457937121448960!!wm_id=b3f0578cbbd8434da8e437702e399f91",
                    "displayUrl": "https://mparticle.uc.cn/article_org.html?uc_param_str=frdnsnpfvecpntnwprdssskt#!wm_cid=632457937121448960!!wm_id=b3f0578cbbd8434da8e437702e399f91",
                    "snippet": "2024财年是阿里巴巴深化ESG治理的一年。在环境保护议题中，阿里巴巴以ESG治理机制的保障为基础，继续探索“在发展中减碳”，通过科技提升能源利用效率，使用可再生能源、带动生态伙伴参与等方式，推进绿色低碳高质量发展。数据显示，2024财年，阿里巴巴实现自身运营碳排放和价值链碳排放强度的“双降”目标；自身运营中的减排量达到232.0万吨，相比上一财年显著提升63.5%；清洁电力使用比例...",
                    "siteName": "大鱼号",
                    "siteIcon": "https://th.bochaai.com/favicon?domain_url=https://mparticle.uc.cn/article_org.html?uc_param_str=frdnsnpfvecpntnwprdssskt#!wm_cid=632457937121448960!!wm_id=b3f0578cbbd8434da8e437702e399f91",
                    "dateLastCrawled": "2024-07-22T11:54:00Z",
                    "cachedPageUrl": null,
                    "language": null,
                    "isFamilyFriendly": null,
                    "isNavigational": null
                },
				......
	    	],
            "someResultsRemoved": true
        },
        "images": {
            "id": null,
            "readLink": null,
            "webSearchUrl": null,
            "value": [
                {
                    "webSearchUrl": null,
                    "name": null,
                    "thumbnailUrl": "http://dayu-img.uc.cn/columbus/img/oc/1002/45628755e2db09ccf7e6ea3bf22ad2b0.jpg",
                    "datePublished": null,
                    "contentUrl": "http://dayu-img.uc.cn/columbus/img/oc/1002/45628755e2db09ccf7e6ea3bf22ad2b0.jpg",
                    "hostPageUrl": "https://mparticle.uc.cn/article_org.html?uc_param_str=frdnsnpfvecpntnwprdssskt#!wm_cid=632457937121448960!!wm_id=b3f0578cbbd8434da8e437702e399f91",
                    "contentSize": null,
                    "encodingFormat": null,
                    "hostPageDisplayUrl": "https://mparticle.uc.cn/article_org.html?uc_param_str=frdnsnpfvecpntnwprdssskt#!wm_cid=632457937121448960!!wm_id=b3f0578cbbd8434da8e437702e399f91",
                    "width": 553,
                    "height": 311,
                    "thumbnail": null
                },
                {
                    "webSearchUrl": null,
                    "name": null,
                    "thumbnailUrl": "http://image.uczzd.cn/15500294364735623464.jpg?id=0&from=export",
                    "datePublished": null,
                    "contentUrl": "http://image.uczzd.cn/15500294364735623464.jpg?id=0&from=export",
                    "hostPageUrl": "https://mparticle.uc.cn/article_org.html?uc_param_str=frdnsnpfvecpntnwprdssskt#!wm_cid=632457937121448960!!wm_id=b3f0578cbbd8434da8e437702e399f91",
                    "contentSize": null,
                    "encodingFormat": null,
                    "hostPageDisplayUrl": "https://mparticle.uc.cn/article_org.html?uc_param_str=frdnsnpfvecpntnwprdssskt#!wm_cid=632457937121448960!!wm_id=b3f0578cbbd8434da8e437702e399f91",
                    "width": 0,
                    "height": 0,
                    "thumbnail": null
                },
				......
	    	],
            "isFamilyFriendly": null
        },
        "videos": null
    }
}

注意

当前版本Web Search API 暂不返回 videos （返回结果为空）。如需视频搜索能力，请先使用 AI Search API中的视频结果。