搜索 API

为你的 Agent 搜索网络数据。

请求路径

GET /api/search/smart

服务地址：https://usearch.xiaosuai.com

请求

请求头（Headers）

参数	类型	描述
`Authorization`	String	值为你的 API Key。将示例中的 `<YOUR_API_KEY>` 替换为真实密钥。
`Pragma`	String	可选值 `no-cache`。填写后每次独立请求，不使用缓存；不填写时，相同查询词的返回结果有 10 分钟缓存。

请求参数（Params）

参数	是否必填	类型	描述
`q`	必填	String	用户的搜索查询词，不能为空。
`count`	选填	Short	返回结果数量，默认 `10`，取值为 `1–50` 的整数，例如 `2`、`10`、`34`。实际返回条目数可能少于设定值。
`freshness`	选填	String	按发布时间筛选： `Day`：近一天 `Week`：近一周 `Month`：近一个月 `SemiYear`：近半年 `Year`：近一年自定义时间段：`YYYY-MM-DD..YYYY-MM-DD` 例如：`2025-05-01..2026-01-01`
`snippetLength`	选填	String	动态摘要长度： `lite` （默认）：轻量版，摘要较短、信息精简 `standard`：标准版，摘要长度和信息量适中 `extended`：扩展版，摘要较长、信息丰富
`enableContent`	选填	Bool	是否返回长摘要： `true` （默认）：返回 `false`：不返回
`contentType`	选填	String	长摘要 `content` 的格式，仅在 `enableContent=true` 时生效： `TEXT` （默认）：纯文本 `MARKDOWN`：Markdown 格式 `HTML`：HTML 格式
`sites`	选填	String	仅返回指定站点的结果，填写 host 地址，例如 `zhihu.com`。
`blockWebsites`	选填	String	去除指定站点的结果，填写 host 地址，例如 `zhihu.com`。

返回值

响应正文（Body）

字段	类型	描述
`queryContext.originalQuery`	String	请求中用户的搜索查询词。
`webPages.value`	Array	返回的详细结果数据。
`webPages.value.id`	Int	结果引用编号，按返回排序取值，用于二次排序和结果引用溯源定位。
`webPages.value.name`	String	网页标题。
`webPages.value.url`	String	网页 URL。
`webPages.value.datePublished`	String	页面发布时间，部分网页包含。
`webPages.value.snippet`	String	描述网页内容的动态摘要，长度受 `snippetLength` 影响。
`webPages.value.siteName`	String	网站名称，部分网页包含。
`webPages.value.contentCrawled`	String	长摘要读取状态（小写字符串）： `true`：读取成功，`content` 包含内容 `false`：读取失败，`content` 为空
`webPages.value.content`	String	从网页正文读取的长摘要。`MARKDOWN`、`HTML` 格式包含有锚点位置的图片链接。
`webPages.value.logo`	String	网页 logo，部分网页包含。
`webPages.value.imageList`	Array	网页内的图片地址列表，数组元素为字符串格式的图片地址。部分网页包含，取决于页面内是否有图。
`webPages.value.score`	Float	内容相关性分数。
`requestId`	String	请求唯一标识。问题反馈时请提供此值，便于定位和排查。

请求示例

curl -X GET "https://usearch.xiaosuai.com/api/search/smart?q=test&count=10" \
  -H "Authorization: <YOUR_API_KEY>" \
  -H "Content-Type: application/json"

import requests

response = requests.get(
    "https://usearch.xiaosuai.com/api/search/smart",
    headers={
        "Authorization": "<YOUR_API_KEY>",
        "Content-Type": "application/json"
    },
    params={
        "q": "test",
        "count": 10
    }
)

data = response.json()
print(data)

状态码说明

HTTP 状态码	错误码	Message	可能原因
400	1103	`[Parameter [q] cannot be empty]`	缺少必要入参 `q`。
400	2112	`No available endpoint`	请求端点错误，或与 API Key 不对应。
401	401	`You are not authorized to access this resource.`	API Key 无效。
404	Not Found	未提供	接口请求 URL 错误或不存在。
405	405	`Method Not Allowed`	HTTP 请求方式错误，例如 POST 请求错用 GET。
429	429	`The request frequency has exceeded the client’s configured limit. Please contact customer support for adjustments.`	QPS 超限。
500	ServerError	`Internal Server Error`	服务内部异常。
502	ServerError	`Bad Gateway`	错误网关。
503	503	`Service Unavailable`	服务不可用。
504	timeout	`Gateway Timeout`	网关超时。