网页搜索 API：为应用获取网络信息文档

1. 准备鉴权

在服务端调用，设置 api-key 和 Content-Type: application/json 请求头。请妥善保存密钥。

2. 填写请求参数

请求仅支持 query、count、search_lang 三个字段。query 可填写自然语言问题或关键词。

字段	类型	必填	说明
query	string	是	搜索问题或关键词，不能为空。
count	integer	否	期望结果数量；省略或传 0 时使用服务默认值。
search_lang	string	否	查询语种，例如 zh-hans；传 zh 时服务会规范化为 zh-hans。点击本行查看支持列表。

3. 调用搜索接口

POSThttps://api.starsg.ai/api/product/websearch/search

替换 YOUR_API_KEY，并将 query 改成你要搜索的内容；count 和 search_lang 可按需省略。

bash

curl -X POST 'https://api.starsg.ai/api/product/websearch/search' \
  -H 'api-key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "query": "北京今天的天气",
  "count": 5,
  "search_lang": "zh-hans"
}'

直接发送 JSON 对象，不包 body，不额外添加 /v1。

4. 读取返回结果

先检查 success。成功时读取 data.references 和 data.data；失败时查看 errorCode 与 errorMsg。以下网页内容仅为示例。

成功响应

json

{
  "success": true,
  "data": {
    "references": [
      {
        "website": "example.com",
        "logo": "https://example.com/favicon.ico",
        "title": "智能家居资讯示例",
        "url": "https://example.com/article",
        "summary": "这里是搜索结果摘要。",
        "published": "",
        "extra": {}
      }
    ],
    "data": [
      "这里是搜索结果摘要。"
    ]
  },
  "errorCode": null,
  "errorMsg": null
}

`data.references`	网页引用列表，包含标题、链接和摘要。
`data.data`	搜索结果文本列表；注意它位于外层 data 对象内。
`references[].website / logo`	站点名称或域名、Logo 地址。
`references[].title / url / summary`	结果标题、原网页链接和摘要。
`references[].published / extra`	发布时间和扩展信息，可能为空。

success=true 且 references、data 为空数组，表示本次没有有效结果。可更换关键词或查询语种；不要按接口失败处理。

失败响应

json

{
  "success": false,
  "data": null,
  "errorCode": "PARAM_INVALID",
  "errorMsg": "query is required"
}

常见错误与处理

`PARAM_INVALID`	检查 JSON 格式和 query。修正参数后再试，不要原样重复提交。
`SEARCH_FAILED`	搜索执行失败，稍后有限次重试；持续失败时保留调用时间和请求标识联系支持。