文档

选择下方的搜索 API，查看请求示例和字段说明。通用鉴权和账户接口见本页。

搜索 API

Google

• 谷歌网页搜索 API
• 谷歌图片搜索 API
• 谷歌视频搜索 API
• 谷歌新闻搜索 API
• 谷歌购物搜索 API
• 谷歌论坛搜索 API
• 谷歌图书搜索 API
• 谷歌地图搜索 API
• 谷歌专利搜索 API

Bing

• 必应网页搜索 API
• 必应图片搜索 API
• 必应视频搜索 API
• 必应新闻搜索 API
• 必应地图搜索 API

接入准备

在控制台创建 API Key，然后将它存入 SERP_API_KEY 环境变量。

export SERP_API_KEY='YOUR_API_KEY'

身份验证

通过 bearer token 或 x-api-key 请求头传入你的 API key。密钥在控制台中创建，且仅显示一次。

Authorization: Bearer YOUR_API_KEY
# or
x-api-key: YOUR_API_KEY

不要把密钥放在 URL 查询字符串中，务必保留在服务端。

接口一览

支持的搜索类型

通过 type 选择搜索类型，省略时进行网页搜索。Google 支持下列全部 9 种类型；Bing 支持网页、新闻、图片、视频和地图搜索。横线表示该引擎不支持此类型。

发送搜索前，可携带 API Key 调用 GET /v1/engines，查看可用引擎及其 verticals 搜索类型列表。

GET /v1/engines

列出可用搜索引擎及各自支持的搜索类型，搜索请求中使用对应的引擎 ID 和类型值。

需要 API Key，无需查询参数或请求正文。

请求示例

curl https://api.serqo.io/v1/engines \
  -H "Authorization: Bearer $SERP_API_KEY"

200 响应

{
  "success": true,
  "requestId": "req_example",
  "data": {
    "engines": [
      {
        "id": "google",
        "displayName": "Google",
        "verticals": [
          "web",
          "images",
          "videos",
          "news",
          "shopping",
          "forums",
          "books",
          "maps",
          "patents"
        ],
        "pagination": "start"
      },
      {
        "id": "bing",
        "displayName": "Bing",
        "verticals": [
          "web",
          "news",
          "images",
          "videos",
          "maps"
        ],
        "pagination": "start"
      }
    ]
  }
}

以上为简化示例。引擎条目还包含 requiresSession 和 captchaSolve，用于描述引擎行为，不是搜索请求参数。本接口不消耗搜索额度；Key 无效时返回 401，读取引擎列表失败时可能返回 5xx。

GET /v1/me

查看当前请求所使用的账户和 API Key，响应不包含完整 Key 或额度余额。

需要 API Key，无需查询参数或请求正文。

请求示例

curl https://api.serqo.io/v1/me \
  -H "Authorization: Bearer $SERP_API_KEY"

200 响应

{
  "success": true,
  "requestId": "req_example",
  "data": {
    "account": {
      "id": "account_example",
      "email": "developer@example.com",
      "role": "user"
    },
    "key": {
      "id": "key_example",
      "prefix": "sk_example"
    }
  }
}

账户信息为示例。本接口不消耗搜索额度，无效、已撤销或已过期的 Key 返回 401 UNAUTHORIZED。

GET /v1/health

检查 API 服务是否响应，不检查搜索引擎、账户权限或可用额度。

无需 API Key、查询参数或请求正文。

请求示例

curl https://api.serqo.io/v1/health

200 响应

{
  "success": true,
  "data": {
    "status": "ok"
  }
}

服务正常响应时，data.status 为 ok。此接口的响应正文不包含常规的 requestId，不消耗搜索额度。

GET /healthz

查看服务器状态和进程运行时长。简单的 API 健康检查可使用 /v1/health。

无需 API Key、查询参数或请求正文。

请求示例

curl https://api.serqo.io/healthz

200 响应

{
  "status": "ok",
  "uptimeMs": 12345
}

以上为简化响应，uptimeMs 是示例运行时长，单位为毫秒。响应还包含 env 和 serp.integration。此接口直接返回状态对象，没有 success 或 data 包装，不检查搜索引擎，也不消耗搜索额度。

错误

搜索失败时，可查看错误原因和重试建议；排查问题时请提供请求 ID。

{
  "success": false,
  "requestId": "req_01H…",
  "error": {
    "code": "INVALID_PARAM",
    "message": "Invalid search parameter",
    "retryable": false
  }
}

常见错误

读取 JSON 前先检查 HTTP 状态。网络故障或代理返回的响应可能不包含 API 错误正文；如有请求 ID，请保留用于排查。

仅在 error.retryable 为 true 时重试；若返回 error.retryAfterMs，至少等待对应的毫秒数。若响应丢失后需要安全重试，请使用相同参数和相同的 Idempotency-Key；24 小时内会重放首次成功响应，不会重复搜索或扣费。不带此请求头时，重试会作为新请求处理并按适用费率计费。

请求 ID 同时出现在响应正文和 x-request-id 响应头中。

限流与额度

请求频率限制

每个 API Key 按账户的每秒请求上限限流，Playground 会话单独计数。管理员 API Key 不受此套餐上限限制。429 响应会给出等待时长（毫秒），请等待后再重试。

额度使用

费用由搜索类型、引擎、国家和缓存状态决定，搜索失败和超时不扣费。可在套餐与额度中查看可用余额及额度明细。

默认费率下，缓存命中不扣费。搜索开始前，可用余额仍需足够支付完整费用，即使随后命中缓存。