搜索

POST https://api.serphubapi.com/v1/search

无论最终由哪个引擎响应，一次调用都返回统一结构的搜索结果。如果某条数据通路出现故障，SerpHubAPI 会自动切换到其他通路——你最多只被计费一次；全部尝试都失败时，不收任何费用。

请求参数

请求体为 JSON，Content-Type: application/json。只有 q 是必填项。

参数	类型	默认值	说明
q	string	—	必填。 搜索词（1–2048 个字符，首尾空格会被去除）。
engine	string	auto	搜索来源：google、bing、yandex、baidu、xiaohongshu、wechat、taobao、deepseek、yuanbao …… auto 优先 Google、Bing 兜底。见服务目录。
type	string	web	该来源提供的结果类型，如 web、news、images、videos、shopping、maps、scholar、autocomplete、notes、articles、products。engine + type 即一个服务。
gl	string	—	国家代码，如 us、gb、de。
hl	string	—	语言代码，如 en、zh-cn。
num	integer	10	返回条数，1–100。
page	integer	1	页码，从 1 开始（最大 100）。
time_range	string	—	day、week、month 或 year，只返回该时间段内的结果。
mode	string	live	live 始终实时获取。cache_first 允许返回 1 小时内的缓存结果，价格减半；命中缓存则免费。
include_content	integer	0	0–5。同时抓取前 N 条结果的网页正文，以 Markdown 返回，每页 3 积分。type=autocomplete 时不可用。

不是每个服务都支持全部可选参数（例如 DeepSeek 搜索没有 page、gl、hl）。对服务不支持的参数传非默认值会返回 400 validation_error；各服务支持的参数见 GET /v1/services。 | format | string | json | json，或 markdown——把整份结果拼成一段 Markdown 文本返回。 |

gl、hl 不区分大小写。请求体中的未知字段会被忽略。

示例

curl -X POST https://api.serphubapi.com/v1/search \
  -H "X-API-Key: shapi_xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "q": "best espresso machine 2026",
    "engine": "google",
    "type": "web",
    "gl": "us",
    "hl": "en",
    "num": 10,
    "time_range": "month"
  }'

服务与价格

每组 engine + type 就是一个服务，单独定价——例如 google/web（10 积分）、deepseek/web（8 积分）。mode=cache_first 为该服务半价。完整列表（价格、支持参数、实时状态）见服务目录页和 GET /v1/services。

• 来源不提供的结果类型（例如 engine=bing, type=shopping）返回 400 validation_error。
• 已列入目录但尚未上线的服务（例如 engine=baidu）返回 503 engine_unavailable。

返回结果（JSON）

{
  "meta": {
    "id": "sch_01J9Z3KQ8W",
    "status": "success",
    "engine": "google",
    "cached": false,
    "credits_charged": 10,
    "time_ms": 812
  },
  "params": {
    "q": "best espresso machine 2026",
    "engine": "google",
    "type": "web",
    "num": 10,
    "page": 1,
    "gl": "us",
    "hl": "en",
    "time_range": "month",
    "mode": "live"
  },
  "results": {
    "organic": [
      {
        "position": 1,
        "title": "The 8 Best Espresso Machines of 2026",
        "link": "https://example.com/espresso",
        "snippet": "We tested 30 machines ...",
        "date": "2026-09-14"
      }
    ],
    "people_also_ask": [
      { "question": "Which espresso machine is best for beginners?", "snippet": "...", "link": "https://..." }
    ],
    "related_searches": ["best espresso machine under 500"],
    "knowledge_graph": {}
  }
}

meta

字段	类型	说明
id	string	调用 ID（sch_...）。用于 GET /v1/searches/{id} 回看，以及联系客服排查。
status	string	200 响应中恒为 success。
service	string	实际应答的服务，格式为 engine/type（如 google/web）。
engine	string	实际应答的来源。engine=auto 时可据此得知用了哪个。
cached	boolean	结果是否来自缓存（仅 mode=cache_first 时可能为 true）。
credits_charged	integer	本次实际扣除的积分。缓存命中、空结果均为 0。
time_ms	integer	本次调用的服务端处理耗时（毫秒）。

params

本次实际生效的参数（已补全默认值），便于记录日志和排查问题。

results

只包含与本次请求相关的字段。引擎未提供的字段会直接省略，不做编造。

字段	出现于	条目字段
organic	web、scholar	position、title、link、snippet、date（有则返回）
news	news	position、title、link、source、date、snippet
images	images	position、title、link（图片所在网页）、image（原图地址）、thumbnail
videos	videos	position、title、link、thumbnail、duration
shopping	shopping	position、title、link、price、currency、merchant、rating
places	maps	position、name、address、rating、reviews、link
suggestions	autocomplete	字符串数组
people_also_ask	web（页面有展示时）	question、snippet、link
related_searches	web（页面有展示时）	字符串数组
knowledge_graph	web（页面有展示时）	自由结构对象

content

仅当 include_content > 0 时出现。每条抓取对应一个元素，顺序与结果一致：

字段	类型	说明
link	string	结果 URL。
markdown	string	清洗后的正文 Markdown。抓取失败时为空字符串。
error	string	抓取失败时为 fetch_failed。失败条目不计费。

正文取自该结果类型的主列表（网页取 organic，新闻取 news，依此类推），重复链接会被跳过。

空结果

搜索成功但没有任何结果时，返回 200，各结果数组为空，meta.credits_charged 为 0。空结果不会触发正文抓取。

Markdown 格式

传入 "format": "markdown" 时，响应类型为 text/markdown 而不是 JSON，可以直接放进 LLM 上下文。由于没有 JSON 中的 meta，关键信息放在响应头里：

响应头	说明
X-Search-Id	调用 ID（同 meta.id）
X-Credits-Charged	扣除积分
X-Cached	true 或 false

限流响应头照常返回。输出示例：

# Search: best espresso machine 2026

_engine: google · type: web · id: sch_01J9Z3KQ8W · credits: 10_

## Results
1. [The 8 Best Espresso Machines of 2026](https://example.com/espresso) — 2026-09-14
   We tested 30 machines ...

## People also ask
- **Which espresso machine is best for beginners?** ...

## Related searches
- best espresso machine under 500

使用 include_content 时，每个网页的正文以 ## Content: <url> 小节附在后面。

计费

动作	积分
mode=live 搜索	10
mode=cache_first 搜索	5（命中缓存为 0）
include_content	每成功抓取一页 +3（cache_first 下命中缓存的页面免费）
空结果	0
调用失败（任何错误响应）	0

调用开始前，余额需足以覆盖本次调用的最高可能费用（例如实时搜索加 include_content: 5 需要 10 + 3 × 5 = 25 积分）。未用掉的部分会立即退回，最终只扣 meta.credits_charged。详见计费。

错误

HTTP	错误码	场景
400	validation_error	参数无效，或引擎与结果类型的组合不受支持
401	invalid_api_key	Key 缺失、无效或已停用
402	insufficient_balance	积分不足
429	rate_limited	触发限流，或达到 Key 的每日积分上限
502	all_upstreams_failed	本次搜索未能完成，不计费
503	engine_unavailable	引擎未上线或暂时不可用

详见错误码。