搜索接口

POST https://api.lexmount.com/v1/search 通过香港 API 执行网页搜索。

使用未压缩的 application/json 请求体，大小不超过 16 KiB。对外调用需要同时携带 X-API-Key 和 X-Project-Id，凭证获取方式见快速开始。

请求体

{
  "query": "PostgreSQL replication",
  "limit": 20,
  "timeout_ms": 10000,
  "language": "en",
  "region": "US",
  "filters": {
    "include_domains": [
      "postgresql.org"
    ],
    "exclude_domains": [
      "lists.postgresql.org"
    ]
  }
}

除 query 外，以上字段均可省略。

请求字段

字段	类型	默认值	说明
`query`	string	必填	1–512 个 Unicode 字符，不能只有空白
`limit`	integer	`10`	返回数量上限，范围 1–100
`timeout_ms`	integer	`10000`	总处理预算，范围 1000–60000 毫秒
`language`	string	不指定	BCP 47 形式的语言标签，例如 `zh-CN`、`en`；最长 64 字符
`region`	string	不指定	两位大写地区代码，例如 `CN`、`US`、`GB`
`filters`	object	不筛选	返回结果的域名硬筛选，见下表

字段名区分大小写。未知字段、重复 JSON 键、null 和错误的字段类型都会返回 HTTP 400。可选的 language、region 不使用时请省略，不要传空字符串。

域名筛选

字段	类型	说明
`filters.include_domains`	string[]	只保留这些域名及其子域名的结果；指定时必须有 1–20 项
`filters.exclude_domains`	string[]	排除这些域名及其子域名的结果；指定时必须有 1–20 项

填主机名，例如 example.org；不要包含协议、端口、路径、通配符或 IP 地址。
域名统一大小写、国际化域名及末尾根点写法；归一化后的重复项会被拒绝。
同时设置包含和排除条件时，结果必须满足包含条件，且不能命中排除条件。
如果全部包含范围都被排除，请求返回 400 invalid_filter。
域名无法确定的结果不能通过域名筛选；筛选可能使返回数量少于 limit。

site: 可以作为查询词的一部分，但不能替代返回结果的域名硬筛选。需要保证结果域名时，请使用 filters.include_domains。

完整 cURL 示例

BASE_URL='https://api.lexmount.com'
API_KEY='<your-api-key>'
PROJECT_ID='<your-project-id>'

curl -sS "$BASE_URL/v1/search" \
  -H 'Content-Type: application/json' \
  -H "X-API-Key: $API_KEY" \
  -H "X-Project-Id: $PROJECT_ID" \
  --data '{
    "query": "PostgreSQL replication",
    "limit": 20,
    "timeout_ms": 10000,
    "language": "en",
    "region": "US",
    "filters": {
      "include_domains": [
        "postgresql.org"
      ],
      "exclude_domains": [
        "lists.postgresql.org"
      ]
    }
  }'

时间预算与返回数量

timeout_ms 覆盖收到请求体后的处理过程。结果充足时服务可能提前结束；搜索完成或时间预算耗尽时，也可能返回少于指定数量的结果。

语言和地区是搜索偏好，不是对每条结果的硬筛选。请读取响应状态判断是否完整，不要只比较 returned 和 limit。

响应

搜索响应直接在顶层返回 results、status 和 returned，不使用 WebFetch 的 result 包装。反馈问题时，请保留 request_id 或 X-Request-ID 响应头。

完整响应示例

以下示例对应这个请求，内容和耗时为说明用的构造数据：

{
  "query": "PostgreSQL documentation",
  "limit": 1
}

{
  "schema_version": "1.0",
  "request_id": "019a04e0-0000-7000-8000-000000000001",
  "query": "PostgreSQL documentation",
  "status": "complete",
  "results": [
    {
      "id": "web_example_1",
      "kind": "web",
      "position": 1,
      "title": "PostgreSQL Documentation",
      "url": "https://www.postgresql.org/docs/",
      "canonical_url": "https://www.postgresql.org/docs/",
      "url_resolved": true,
      "domain": "www.postgresql.org",
      "snippet": "Documentation for PostgreSQL.",
      "published_at": null
    }
  ],
  "returned": 1,
  "timing": {
    "elapsed_ms": 1280
  }
}

顶层字段

字段	说明
`schema_version`	响应结构版本，当前为 `1.0`
`request_id`	请求关联 ID，排查问题时保留
`query`	本次搜索关键词
`status`	`complete`、`partial`、`empty` 或 `unavailable`
`results`、`returned`	最终排序结果，以及实际返回条数
`timing.elapsed_ms`	服务端搜索处理耗时；不代表客户端端到端耗时
`error`	搜索不可用时返回，包含 `code`、`message`、`retryable`

HTTP 状态与搜索状态

HTTP	`status`	含义
200	`complete`	搜索已完成并返回结果；数量可能少于 `limit`
200	`partial`	搜索返回了部分答案；也可能为 0 条结果
200	`empty`	搜索已完成，没有符合请求条件的结果
503	`unavailable`	搜索未能返回可用答案；查看 `error`

complete 不保证拿满 limit，也不表示找到了全网所有相关页面。partial 的 0 条结果不能视为确认没有相关网页。

网页结果

字段	说明
`id`	结果标识
`kind`	固定为 `web`
`position`	当前响应中的排名，从 1 开始
`title`	网页标题
`url`	可以打开或交给 WebFetch 的链接
`canonical_url`	归一化后的目标 URL；未解析时为 `null`
`url_resolved`	是否已解析目标 URL
`domain`	目标主机名；未知时为 `null`
`snippet`	搜索摘要，不是网页全文
`published_at`	已知时为发布时间；否则为 `null`

启用域名筛选时，无法确定目标域名的结果会被排除。需要页面正文时，请使用 WebFetch。

请求错误

搜索开始前被拒绝的请求使用 request_id 和 error 对象，不返回结果列表。例如：

{
  "request_id": "019a04e0-0000-7000-8000-000000000002",
  "error": {
    "code": "invalid_query",
    "message": "query must contain 1–512 Unicode characters and not be blank",
    "retryable": false
  }
}

HTTP 400 表示参数错误，413 表示请求体超过 16 KiB，415 表示内容类型或编码不支持。鉴权和访问限制使用 HTTP 401 或 403；缺少 Project ID 请求头也可能返回 HTTP 400。网关错误的响应结构可能不同，请先检查 HTTP 状态，再读取搜索字段。暂时的处理失败可能返回 HTTP 500 或 503；请保留请求 ID，并在 error.retryable 为 true 时退避重试。

HTTP 429 和 websearch_quota_exhausted 表示账号共享的月度额度已用完，同一周期内重复重试不会恢复，额外次数暂不开放购买。HTTP 503 和 websearch_quota_unavailable 表示额度检查暂不可用，本次尚未开始搜索。HTTP 403 和 websearch_project_unavailable 表示项目或账号未启用或不可用。

POST https://api.lexmount.com/v1/search 通过香港 API 执行网页搜索。

使用未压缩的 application/json 请求体，大小不超过 16 KiB。对外调用需要同时携带 X-API-Key 和 X-Project-Id，凭证获取方式见快速开始。

请求体

{
  "query": "PostgreSQL replication",
  "limit": 20,
  "timeout_ms": 10000,
  "language": "en",
  "region": "US",
  "filters": {
    "include_domains": [
      "postgresql.org"
    ],
    "exclude_domains": [
      "lists.postgresql.org"
    ]
  }
}

除 query 外，以上字段均可省略。

请求字段

字段	类型	默认值	说明
`query`	string	必填	1–512 个 Unicode 字符，不能只有空白
`limit`	integer	`10`	返回数量上限，范围 1–100
`timeout_ms`	integer	`10000`	总处理预算，范围 1000–60000 毫秒
`language`	string	不指定	BCP 47 形式的语言标签，例如 `zh-CN`、`en`；最长 64 字符
`region`	string	不指定	两位大写地区代码，例如 `CN`、`US`、`GB`
`filters`	object	不筛选	返回结果的域名硬筛选，见下表

字段名区分大小写。未知字段、重复 JSON 键、null 和错误的字段类型都会返回 HTTP 400。可选的 language、region 不使用时请省略，不要传空字符串。

域名筛选

字段	类型	说明
`filters.include_domains`	string[]	只保留这些域名及其子域名的结果；指定时必须有 1–20 项
`filters.exclude_domains`	string[]	排除这些域名及其子域名的结果；指定时必须有 1–20 项

填主机名，例如 example.org；不要包含协议、端口、路径、通配符或 IP 地址。
域名统一大小写、国际化域名及末尾根点写法；归一化后的重复项会被拒绝。
同时设置包含和排除条件时，结果必须满足包含条件，且不能命中排除条件。
如果全部包含范围都被排除，请求返回 400 invalid_filter。
域名无法确定的结果不能通过域名筛选；筛选可能使返回数量少于 limit。

site: 可以作为查询词的一部分，但不能替代返回结果的域名硬筛选。需要保证结果域名时，请使用 filters.include_domains。

完整 cURL 示例

BASE_URL='https://api.lexmount.com'
API_KEY='<your-api-key>'
PROJECT_ID='<your-project-id>'

curl -sS "$BASE_URL/v1/search" \
  -H 'Content-Type: application/json' \
  -H "X-API-Key: $API_KEY" \
  -H "X-Project-Id: $PROJECT_ID" \
  --data '{
    "query": "PostgreSQL replication",
    "limit": 20,
    "timeout_ms": 10000,
    "language": "en",
    "region": "US",
    "filters": {
      "include_domains": [
        "postgresql.org"
      ],
      "exclude_domains": [
        "lists.postgresql.org"
      ]
    }
  }'

时间预算与返回数量

timeout_ms 覆盖收到请求体后的处理过程。结果充足时服务可能提前结束；搜索完成或时间预算耗尽时，也可能返回少于指定数量的结果。

语言和地区是搜索偏好，不是对每条结果的硬筛选。请读取响应状态判断是否完整，不要只比较 returned 和 limit。

响应

搜索响应直接在顶层返回 results、status 和 returned，不使用 WebFetch 的 result 包装。反馈问题时，请保留 request_id 或 X-Request-ID 响应头。

完整响应示例

以下示例对应这个请求，内容和耗时为说明用的构造数据：

{
  "query": "PostgreSQL documentation",
  "limit": 1
}

{
  "schema_version": "1.0",
  "request_id": "019a04e0-0000-7000-8000-000000000001",
  "query": "PostgreSQL documentation",
  "status": "complete",
  "results": [
    {
      "id": "web_example_1",
      "kind": "web",
      "position": 1,
      "title": "PostgreSQL Documentation",
      "url": "https://www.postgresql.org/docs/",
      "canonical_url": "https://www.postgresql.org/docs/",
      "url_resolved": true,
      "domain": "www.postgresql.org",
      "snippet": "Documentation for PostgreSQL.",
      "published_at": null
    }
  ],
  "returned": 1,
  "timing": {
    "elapsed_ms": 1280
  }
}

顶层字段

字段	说明
`schema_version`	响应结构版本，当前为 `1.0`
`request_id`	请求关联 ID，排查问题时保留
`query`	本次搜索关键词
`status`	`complete`、`partial`、`empty` 或 `unavailable`
`results`、`returned`	最终排序结果，以及实际返回条数
`timing.elapsed_ms`	服务端搜索处理耗时；不代表客户端端到端耗时
`error`	搜索不可用时返回，包含 `code`、`message`、`retryable`

HTTP 状态与搜索状态

HTTP	`status`	含义
200	`complete`	搜索已完成并返回结果；数量可能少于 `limit`
200	`partial`	搜索返回了部分答案；也可能为 0 条结果
200	`empty`	搜索已完成，没有符合请求条件的结果
503	`unavailable`	搜索未能返回可用答案；查看 `error`

complete 不保证拿满 limit，也不表示找到了全网所有相关页面。partial 的 0 条结果不能视为确认没有相关网页。

网页结果

字段	说明
`id`	结果标识
`kind`	固定为 `web`
`position`	当前响应中的排名，从 1 开始
`title`	网页标题
`url`	可以打开或交给 WebFetch 的链接
`canonical_url`	归一化后的目标 URL；未解析时为 `null`
`url_resolved`	是否已解析目标 URL
`domain`	目标主机名；未知时为 `null`
`snippet`	搜索摘要，不是网页全文
`published_at`	已知时为发布时间；否则为 `null`

启用域名筛选时，无法确定目标域名的结果会被排除。需要页面正文时，请使用 WebFetch。

请求错误

搜索开始前被拒绝的请求使用 request_id 和 error 对象，不返回结果列表。例如：

{
  "request_id": "019a04e0-0000-7000-8000-000000000002",
  "error": {
    "code": "invalid_query",
    "message": "query must contain 1–512 Unicode characters and not be blank",
    "retryable": false
  }
}

请求体

请求字段

域名筛选

完整 cURL 示例

时间预算与返回数量

响应

完整响应示例

顶层字段

HTTP 状态与搜索状态

网页结果

请求错误

目录

搜索接口

请求体

请求字段

域名筛选

完整 cURL 示例

时间预算与返回数量

响应

完整响应示例

顶层字段

HTTP 状态与搜索状态

网页结果

请求错误

目录