服务与引擎

SerpHubAPI 是搜索服务的聚合 hub。来源（source）是一个搜索产品——搜索引擎（Google、Bing、Yandex、百度）、App 内搜索（小红书、微信、淘宝）或 AI 搜索（DeepSeek、腾讯元宝）。服务（service）是一个来源加一种结果类型，写作 engine/type：google/news、xiaohongshu/notes、deepseek/web。所有服务都通过 POST /v1/search 的 engine 和 type 调用，从同一个钱包扣费。

GET /v1/services

GET https://api.serphubapi.com/v1/services

完整目录：每个服务的价格、支持参数和实时可用性。调用免费。Agent 和 MCP 客户端可以借此发现能调用什么。同一份列表也展示在服务目录页。

curl https://api.serphubapi.com/v1/services \
  -H "X-API-Key: shapi_xxxxxxxx"

{
  "sources": [
    { "id": "google", "name": "Google", "name_zh": "Google", "category": "engine", "blurb": "The world's largest web index.", "blurb_zh": "全球最大的网页索引。" },
    { "id": "deepseek", "name": "DeepSeek Search", "name_zh": "DeepSeek 搜索", "category": "ai", "blurb": "Search index built for agents.", "blurb_zh": "为 Agent 设计的搜索索引。" }
  ],
  "services": [
    {
      "id": "google/web", "engine": "google", "type": "web", "name": "Google", "name_zh": "Google", "category": "engine",
      "credits": 10, "cache_first_credits": 5, "status": "live", "availability": "operational",
      "params": ["gl", "hl", "num", "page", "time_range"], "include_content": true
    },
    {
      "id": "deepseek/web", "engine": "deepseek", "type": "web", "name": "DeepSeek Search", "name_zh": "DeepSeek 搜索", "category": "ai",
      "credits": 8, "cache_first_credits": 4, "status": "beta", "availability": "operational",
      "params": ["num"], "include_content": true
    },
    {
      "id": "xiaohongshu/notes", "engine": "xiaohongshu", "type": "notes", "name": "Xiaohongshu", "name_zh": "小红书", "category": "app",
      "credits": 20, "cache_first_credits": 10, "status": "planned", "availability": "planned",
      "params": ["num", "page"], "include_content": true
    }
  ]
}

字段	类型	说明
id	string	engine/type。
engine、type	string	调用 /v1/search 时传的值。
category	string	engine（搜索引擎）、app（App 内搜索）或 ai（AI 搜索）。
credits	integer	一次成功实时调用的价格（积分）。
cache_first_credits	integer	mode=cache_first 时的价格（半价，向上取整）；命中缓存免费。
status	string	产品状态。live：已验收。beta：可调用，返回结构可能微调。planned：已列入目录，暂不可调用。
availability	string	当前可用性。operational、degraded（可用但近期错误率偏高）、unavailable（暂时没有可用线路）、planned。
params	string[]	该服务支持的可选参数（gl、hl、num、page、time_range 的子集）。对其他参数传非默认值返回 400 validation_error。
include_content	boolean	是否支持 include_content。

价格按成功调用计：失败、空结果、缓存命中均为 0。详见计费。

GET /v1/engines

GET https://api.serphubapi.com/v1/engines

同一份数据按来源汇总：每个来源的状态，以及当前可调用的结果类型。

{
  "engines": [
    { "engine": "google", "name": "Google", "category": "engine", "status": "operational", "types": ["web", "news", "images", "videos", "shopping", "maps", "scholar", "autocomplete"] },
    { "engine": "deepseek", "name": "DeepSeek Search", "category": "ai", "status": "operational", "types": ["web"] },
    { "engine": "baidu", "name": "Baidu", "category": "engine", "status": "planned", "types": [] }
  ]
}

status	含义
operational	运行正常。
degraded	可用，但近期错误率偏高，可能偶发 502。
disabled	已上线，但暂时没有可用线路。
planned	已列入目录、尚未上线。调用返回 503 engine_unavailable。

错误

HTTP	错误码	场景
401	invalid_api_key	Key 缺失、无效或已停用