{"openapi":"3.1.0","info":{"title":"聚搜GO API","version":"0.9.11","description":"一个 Key 调多家搜索引擎。按次扣固定积分（当前 1–4 积分/次），失败不扣。文档：https://jusouai.cn/docs"},"servers":[{"url":"https://jusouai.cn"}],"tags":[{"name":"统一接口"},{"name":"原生兼容 · Exa"},{"name":"原生兼容 · SerpApi"},{"name":"原生兼容 · Tavily"},{"name":"原生兼容 · Serper"},{"name":"原生兼容 · AnySearch"},{"name":"原生兼容 · Brave"},{"name":"原生兼容 · 博查"},{"name":"原生兼容 · 百度"},{"name":"账户"}],"paths":{"/v1/search":{"post":{"operationId":"search","summary":"统一搜索","description":"一种写法调任意引擎，返回统一结构。想用某家就指定 engine；不指定则用默认引擎；想对比就传 engines。返回的 engine 字段与响应头 x-engine 是实际使用的引擎。某引擎不支持的公共参数返回 400 说明，不静默忽略。传 engines 数组时返回 by_engine 按引擎分组（每家各自的 results / points_charged / error），points_charged 为合计；只调你点名的引擎，不替换、不追加。","tags":["统一接口"],"responses":{"200":{"description":"成功","content":{"application/json":{"example":{"request_id":"js-20261031120000-a1b2c3d4e5f6","engine":"exa","results":[{"title":"…","url":"https://example.com/a","snippet":"…","content":"…","published_at":"…","score":null}],"points_charged":1,"points_tier":"standard","billing":{"points":1,"balance":999,"summary":"本次：Exa -1 积分，剩余 999"}}}}},"400":{"description":"invalid_request：参数错误（网关拦截或引擎判定参数错）","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"unauthorized：缺少密钥或密钥无效","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"insufficient_points：积分不足","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"engine_not_found：引擎不存在","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited：超过套餐每秒请求数（排队超过上限）；engine_busy：引擎繁忙","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"engine_error：引擎暂时异常（已自动重试）","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"engine_unavailable：引擎暂不可用或暂未开放","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"engine":{"type":"string","description":"引擎：exa / serpapi / tavily / serper / anysearch / brave / bocha / baidu。不填则用默认引擎（anysearch）；和 engines 二选一。失败不会自动换别家"},"engines":{"type":"array","items":{},"description":"同时搜几个引擎，如 [\"a\", \"b\"]；只调你点名的引擎，各自按价目扣分，失败的那家不扣"},"merge":{"type":"boolean","description":"多引擎时 true：另给一份去重合并的 results，每条带 engines 标出哪几家搜到"},"query":{"type":"string","description":"搜索词"},"num_results":{"type":"integer","description":"每个引擎返回条数 1-10；Exa 1-100（超过 10 条每多 10 条加收积分）；超出返回 400，不扣分"},"depth":{"type":"string","description":"basic（默认，基础档）/ advanced / deep；引擎不支持时报错"},"time_range":{"type":"string","description":"day / week / month / year"},"include_domains":{"type":"array","items":{},"description":"只搜这些域名"},"exclude_domains":{"type":"array","items":{},"description":"排除这些域名"},"language":{"type":"string","description":"语言，如 zh"},"raw":{"type":"boolean","description":"true 时附带该引擎官方原生返回"},"extra":{"type":"object","description":"引擎专属参数，原样透传"}},"required":["query"]},"example":{"engine":"exa","query":"量子计算","num_results":5}}}}}},"/v1/exa/search":{"post":{"operationId":"exa_search","summary":"Exa 搜索","description":"与 Exa 官方 /search 一致：请求体、返回体原样，只把 requestId 换成我方的。档位按 type 计（lite / auto / deep）；numResults 1-100，超过 10 条后每多 10 条（不足 10 条按 10 条）加收积分，要 summary 另加收。","tags":["原生兼容 · Exa"],"responses":{"200":{"description":"成功","content":{"application/json":{"example":{"requestId":"js-20261031120000-a1b2c3d4e5f6","results":[{"id":"https://example.com/a","title":"…","url":"https://example.com/a","publishedDate":"2026-10-01","author":"…","highlights":["…"]}],"billing":{"points":2,"balance":998,"summary":"本次：Exa -2 积分，剩余 998"}}}}},"400":{"description":"invalid_request：参数错误（网关拦截或引擎判定参数错）；operation_unavailable：该引擎的这个接口 / 档位暂未开放","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"unauthorized：缺少密钥或密钥无效","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"insufficient_points：积分不足","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited：超过套餐每秒请求数（排队超过上限）；engine_busy：引擎繁忙","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"engine_error：引擎暂时异常（已自动重试）","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"engine_unavailable：引擎暂不可用或暂未开放","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"query":{"type":"string","description":"搜索词"},"type":{"type":"string","description":"lite / auto（默认）/ deep（deep-lite 按 deep 计）；neural、keyword 已停用。lite 只接受 query / numResults / category / userLocation / 域名与发布时间过滤 / moderation / contents.highlights / contents.text，其它参数返回 400、不扣分"},"numResults":{"type":"integer","description":"返回条数 1-100，默认 10；超过 10 条后每多 10 条（不足 10 条按 10 条）加收积分；超过 100 返回参数错误（不扣分）"},"includeDomains":{"type":"array","items":{},"description":"只搜这些域名"},"excludeDomains":{"type":"array","items":{},"description":"排除这些域名"},"startPublishedDate":{"type":"string","description":"发布时间起，ISO 8601"},"endPublishedDate":{"type":"string","description":"发布时间止，ISO 8601"},"startCrawlDate":{"type":"string","description":"收录时间起"},"endCrawlDate":{"type":"string","description":"收录时间止"},"includeText":{"type":"array","items":{},"description":"结果正文必须包含的词"},"excludeText":{"type":"array","items":{},"description":"结果正文不能包含的词"},"category":{"type":"string","description":"官方选项：company / people / publication（论文）/ news / personal site / financial report；其它字符串按提示词处理"},"userLocation":{"type":"string","description":"两位国家代码，如 CN"},"contents":{"type":"object","description":"要返回的内容：text / highlights / summary / livecrawl 等，原样透传"},"additionalQueries":{"type":"array","items":{},"description":"deep 档的补充查询词"},"moderation":{"type":"boolean","description":"过滤不安全内容"}},"required":["query"]},"example":{"query":"latest research on solid-state batteries","type":"auto","numResults":5,"contents":{"highlights":true}}}}}}},"/v1/exa/answer":{"post":{"operationId":"exa_answer","summary":"Exa 答案","description":"与 Exa 官方 /answer 一致：先搜再生成带引用的答案。暂只支持非流式（stream=false）。","tags":["原生兼容 · Exa"],"responses":{"200":{"description":"成功","content":{"application/json":{"example":{"requestId":"js-20261031120000-a1b2c3d4e5f6","answer":"…","citations":[{"id":"https://example.com/a","url":"https://example.com/a","title":"…"}],"billing":{"points":2,"balance":998,"summary":"本次：Exa -2 积分，剩余 998"}}}}},"400":{"description":"invalid_request：参数错误（网关拦截或引擎判定参数错）；operation_unavailable：该引擎的这个接口 / 档位暂未开放","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"unauthorized：缺少密钥或密钥无效","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"insufficient_points：积分不足","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited：超过套餐每秒请求数（排队超过上限）；engine_busy：引擎繁忙","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"engine_error：引擎暂时异常（已自动重试）","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"engine_unavailable：引擎暂不可用或暂未开放","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"query":{"type":"string","description":"问题"},"text":{"type":"boolean","description":"引用里是否带正文"},"outputSchema":{"type":"object","description":"要求按 JSON Schema 输出"},"stream":{"type":"boolean","description":"只能为 false"}},"required":["query"]},"example":{"query":"2026 年诺贝尔物理学奖颁给了谁？"}}}}}},"/v1/serpapi/search":{"post":{"operationId":"serpapi_search","summary":"SerpApi Google 搜索","description":"Google 搜索结果，参数名与返回结构与 SerpApi 官方 Google Search API 一致（engine=google，q / num / start / hl / gl / location / tbs …；鉴权用你的聚搜 Key，不用 api_key），返回 organic_results（title / link / snippet / date / source），有时还有 answer_box（精选摘要）、knowledge_graph（知识面板）、related_questions（相关问题）、related_searches。没有结果不扣积分。","tags":["原生兼容 · SerpApi"],"responses":{"200":{"description":"成功","content":{"application/json":{"example":{"search_metadata":{"id":"js-20261102200000-a1b2c3d4e5f6","status":"Success"},"search_parameters":{"engine":"google","q":"固态电池 量产 2026","hl":"zh-cn","gl":"cn"},"search_information":{"total_results":1230000},"organic_results":[{"position":1,"title":"…","link":"https://example.com/a","displayed_link":"https://example.com › a","snippet":"…","date":"2026-10-01","source":"Example"}],"related_questions":[{"question":"…","snippet":"…","link":"https://example.com/b"}],"billing":{"points":4,"balance":996,"summary":"本次：SerpApi -4 积分，剩余 996"}}}}},"400":{"description":"invalid_request：参数错误（网关拦截或引擎判定参数错）；operation_unavailable：该引擎的这个接口 / 档位暂未开放","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"unauthorized：缺少密钥或密钥无效","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"insufficient_points：积分不足","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited：超过套餐每秒请求数（排队超过上限）；engine_busy：引擎繁忙","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"engine_error：引擎暂时异常（已自动重试）","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"engine_unavailable：引擎暂不可用或暂未开放","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"engine":{"type":"string","description":"固定为 google（与 SerpApi 一致，可不传）；只提供 Google 网页搜索"},"q":{"type":"string","description":"搜索词，支持 site: / intitle: / inurl: 等 Google 搜索语法"},"num":{"type":"integer","description":"1-10（最多 10 条）；注意 Google 已不再支持 num，目前基本固定返回一页约 10 条（11-03 实测 num=5 返回 10 条）；统一接口 /v1/search 会按 num_results 截断"},"start":{"type":"integer","description":"翻页偏移：跳过前几条结果，如 10 = 第 2 页（0-100）"},"hl":{"type":"string","description":"界面 / 结果语言，如 zh-cn / zh-tw / en / ja"},"gl":{"type":"string","description":"搜索所在国家，两位代码如 us / cn / jp / hk"},"location":{"type":"string","description":"搜索发起地（城市级最准），如 Austin, Texas, United States"},"google_domain":{"type":"string","description":"Google 域名，默认 google.com，如 google.com.hk / google.co.jp"},"safe":{"type":"string","description":"成人内容过滤：active / off"},"tbs":{"type":"string","description":"高级筛选，时间范围如 qdr:d（24 小时）/ qdr:w / qdr:m / qdr:y"},"lr":{"type":"string","description":"只要这些语言的网页，如 lang_zh-CN|lang_en"},"cr":{"type":"string","description":"只要这些国家的网页，如 countryUS|countryJP"},"nfpr":{"type":"integer","description":"1 = 不要自动纠错后的结果，0 = 允许（默认）"},"filter":{"type":"integer","description":"1 = 合并相似结果（默认），0 = 不合并"},"device":{"type":"string","description":"desktop（默认）/ tablet / mobile"},"no_cache":{"type":"boolean","description":"true = 不用 1 小时内的相同搜索缓存，强制重新搜索"}},"required":["q"]},"example":{"engine":"google","q":"固态电池 量产 2026","num":5,"hl":"zh-cn","gl":"cn"}}}}}},"/v1/tavily/search":{"post":{"operationId":"tavily_search","summary":"Tavily 搜索","description":"与 Tavily 官方 /search 一致：请求体、返回体原样，只把 request_id 换成我方的。档位按 search_depth 计。","tags":["原生兼容 · Tavily"],"responses":{"200":{"description":"成功","content":{"application/json":{"example":{"query":"…","answer":"…","images":[],"request_id":"js-20261031120000-a1b2c3d4e5f6","results":[{"title":"…","url":"https://example.com/a","content":"…","score":0.81}],"response_time":1.2,"billing":{"points":1,"balance":999,"summary":"本次：Tavily -1 积分，剩余 999"}}}}},"400":{"description":"invalid_request：参数错误（网关拦截或引擎判定参数错）；operation_unavailable：该引擎的这个接口 / 档位暂未开放","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"unauthorized：缺少密钥或密钥无效","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"insufficient_points：积分不足","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited：超过套餐每秒请求数（排队超过上限）；engine_busy：引擎繁忙","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"engine_error：引擎暂时异常（已自动重试）","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"engine_unavailable：引擎暂不可用或暂未开放","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"query":{"type":"string","description":"搜索词"},"search_depth":{"type":"string","description":"basic（默认）/ fast / ultra-fast（与 basic 同价）/ advanced；advanced 进入高级档"},"topic":{"type":"string","description":"general（默认）/ news / finance"},"max_results":{"type":"integer","description":"返回条数 0-10，默认 5"},"time_range":{"type":"string","description":"day / week / month / year"},"start_date":{"type":"string","description":"起始日期 YYYY-MM-DD"},"end_date":{"type":"string","description":"截止日期 YYYY-MM-DD"},"days":{"type":"integer","description":"topic=news 时最近几天"},"chunks_per_source":{"type":"integer","description":"advanced 档每个来源返回几段，1-3"},"include_answer":{"type":"boolean","description":"附带简短答案（也可传 basic / advanced）"},"include_raw_content":{"type":"boolean","description":"附带网页正文（也可传 markdown / text）"},"include_images":{"type":"boolean","description":"附带图片"},"include_image_descriptions":{"type":"boolean","description":"图片附说明"},"include_favicon":{"type":"boolean","description":"附带站点图标"},"include_domains":{"type":"array","items":{},"description":"只搜这些域名"},"exclude_domains":{"type":"array","items":{},"description":"排除这些域名"},"country":{"type":"string","description":"优先某国结果，如 china（topic=general）"},"exact_match":{"type":"boolean","description":"只要精确包含引号短语的结果"},"include_published_date":{"type":"boolean","description":"每条结果带 published_date（topic=news 时自动开）"},"filter_by_published_date":{"type":"boolean","description":"去掉发布时间不在 time_range / start_date / end_date 内或无日期的结果"},"include_domains_mode":{"type":"string","description":"restrict（默认，只要 include_domains）/ prefer（优先，不排除其它）；需同时传 include_domains"},"language":{"type":"string","description":"优先某语言结果，如 en / zh-cn"},"filter_by_language":{"type":"boolean","description":"严格只要 language 的结果（需同时传 language）"},"safe_search":{"type":"boolean","description":"过滤成人 / 不安全内容（fast / ultra-fast 不支持）"}},"required":["query"]},"example":{"query":"2026 年固态电池量产进展","search_depth":"basic","max_results":5,"include_answer":true}}}}}},"/v1/serper/search":{"post":{"operationId":"serper_search","summary":"Serper 网页搜索","description":"Google 网页搜索结果，参数名与返回结构与 Serper 官方 /search 一致（q / gl / hl / num / page …；鉴权用你的聚搜 Key，不用 X-API-KEY）。返回 organic（title / link / snippet / date / position / sitelinks），有时还有 knowledgeGraph（知识面板）、answerBox（精选摘要）、peopleAlsoAsk（相关问题）、relatedSearches、topStories。","tags":["原生兼容 · Serper"],"responses":{"200":{"description":"成功","content":{"application/json":{"example":{"searchParameters":{"q":"固态电池 量产 2026","num":5,"gl":"cn","hl":"zh-cn","type":"search","engine":"google"},"organic":[{"title":"…","link":"https://example.com/a","snippet":"…","date":"2026-10-01","position":1}],"relatedSearches":[{"query":"…"}],"billing":{"points":1,"balance":999,"summary":"本次：Serper -1 积分，剩余 999"}}}}},"400":{"description":"invalid_request：参数错误（网关拦截或引擎判定参数错）；operation_unavailable：该引擎的这个接口 / 档位暂未开放","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"unauthorized：缺少密钥或密钥无效","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"insufficient_points：积分不足","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited：超过套餐每秒请求数（排队超过上限）；engine_busy：引擎繁忙","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"engine_error：引擎暂时异常（已自动重试）","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"engine_unavailable：引擎暂不可用或暂未开放","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"q":{"type":"string","description":"搜索词，支持 site: / intitle: / filetype: 等 Google 搜索语法"},"gl":{"type":"string","description":"搜索所在国家，两位代码如 us / cn / jp / hk"},"hl":{"type":"string","description":"结果语言，如 zh-cn / zh-tw / en / ja"},"location":{"type":"string","description":"搜索发起地（城市级最准），如 Shanghai, China / Austin, Texas, United States"},"num":{"type":"integer","description":"返回条数 1-10（最多 10 条），默认 10"},"page":{"type":"integer","description":"页码，从 1 开始（1-100）"},"tbs":{"type":"string","description":"时间范围：qdr:h（1 小时）/ qdr:d（24 小时）/ qdr:w / qdr:m / qdr:y"},"autocorrect":{"type":"boolean","description":"false = 不要自动纠错后的结果（默认 true）"}},"required":["q"]},"example":{"q":"固态电池 量产 2026","num":5,"gl":"cn","hl":"zh-cn"}}}}}},"/v1/serper/images":{"post":{"operationId":"serper_images","summary":"Serper 图片搜索","description":"Google 图片搜索结果，参数名与返回结构与 Serper 官方 /images 一致（q / gl / hl / num / page …；鉴权用你的聚搜 Key，不用 X-API-KEY）。返回 images（title / imageUrl / imageWidth / imageHeight / thumbnailUrl / source / domain / link / position）。","tags":["原生兼容 · Serper"],"responses":{"200":{"description":"成功","content":{"application/json":{"example":{"searchParameters":{"q":"埃菲尔铁塔 夜景","num":5,"gl":"cn","hl":"zh-cn","type":"images","engine":"google"},"images":[{"title":"…","imageUrl":"https://example.com/a.jpg","source":"Example","link":"https://example.com/a","position":1}],"billing":{"points":1,"balance":999,"summary":"本次：Serper -1 积分，剩余 999"}}}}},"400":{"description":"invalid_request：参数错误（网关拦截或引擎判定参数错）；operation_unavailable：该引擎的这个接口 / 档位暂未开放","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"unauthorized：缺少密钥或密钥无效","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"insufficient_points：积分不足","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited：超过套餐每秒请求数（排队超过上限）；engine_busy：引擎繁忙","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"engine_error：引擎暂时异常（已自动重试）","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"engine_unavailable：引擎暂不可用或暂未开放","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"q":{"type":"string","description":"搜索词，支持 site: / intitle: / filetype: 等 Google 搜索语法"},"gl":{"type":"string","description":"搜索所在国家，两位代码如 us / cn / jp / hk"},"hl":{"type":"string","description":"结果语言，如 zh-cn / zh-tw / en / ja"},"location":{"type":"string","description":"搜索发起地（城市级最准），如 Shanghai, China / Austin, Texas, United States"},"num":{"type":"integer","description":"返回条数 1-10（最多 10 条），默认 10"},"page":{"type":"integer","description":"页码，从 1 开始（1-100）"},"tbs":{"type":"string","description":"时间范围：qdr:h（1 小时）/ qdr:d（24 小时）/ qdr:w / qdr:m / qdr:y"},"autocorrect":{"type":"boolean","description":"false = 不要自动纠错后的结果（默认 true）"}},"required":["q"]},"example":{"q":"埃菲尔铁塔 夜景","num":5,"gl":"cn","hl":"zh-cn"}}}}}},"/v1/serper/news":{"post":{"operationId":"serper_news","summary":"Serper 新闻搜索","description":"Google 新闻搜索结果，参数名与返回结构与 Serper 官方 /news 一致（q / gl / hl / num / page …；鉴权用你的聚搜 Key，不用 X-API-KEY）。返回 news（title / link / snippet / date / source / imageUrl / position）。","tags":["原生兼容 · Serper"],"responses":{"200":{"description":"成功","content":{"application/json":{"example":{"searchParameters":{"q":"固态电池","num":5,"gl":"cn","hl":"zh-cn","type":"news","engine":"google"},"news":[{"title":"…","link":"https://example.com/news/1","snippet":"…","date":"3 小时前","source":"Example"}],"billing":{"points":1,"balance":999,"summary":"本次：Serper -1 积分，剩余 999"}}}}},"400":{"description":"invalid_request：参数错误（网关拦截或引擎判定参数错）；operation_unavailable：该引擎的这个接口 / 档位暂未开放","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"unauthorized：缺少密钥或密钥无效","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"insufficient_points：积分不足","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited：超过套餐每秒请求数（排队超过上限）；engine_busy：引擎繁忙","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"engine_error：引擎暂时异常（已自动重试）","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"engine_unavailable：引擎暂不可用或暂未开放","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"q":{"type":"string","description":"搜索词，支持 site: / intitle: / filetype: 等 Google 搜索语法"},"gl":{"type":"string","description":"搜索所在国家，两位代码如 us / cn / jp / hk"},"hl":{"type":"string","description":"结果语言，如 zh-cn / zh-tw / en / ja"},"location":{"type":"string","description":"搜索发起地（城市级最准），如 Shanghai, China / Austin, Texas, United States"},"num":{"type":"integer","description":"1-10（最多 10 条）；该类型目前忽略 num、固定返回一页（11-03 实测：news / videos / places / scholar 约 10 条，shopping 约 40 条），统一接口不涉及；扣分与条数无关"},"page":{"type":"integer","description":"页码，从 1 开始（1-100）"},"tbs":{"type":"string","description":"时间范围：qdr:h（1 小时）/ qdr:d（24 小时）/ qdr:w / qdr:m / qdr:y"},"autocorrect":{"type":"boolean","description":"false = 不要自动纠错后的结果（默认 true）"}},"required":["q"]},"example":{"q":"固态电池","num":5,"gl":"cn","hl":"zh-cn"}}}}}},"/v1/serper/videos":{"post":{"operationId":"serper_videos","summary":"Serper 视频搜索","description":"Google 视频搜索结果，参数名与返回结构与 Serper 官方 /videos 一致（q / gl / hl / num / page …；鉴权用你的聚搜 Key，不用 X-API-KEY）。返回 videos（title / link / snippet / imageUrl / duration / source / channel / date / position）。","tags":["原生兼容 · Serper"],"responses":{"200":{"description":"成功","content":{"application/json":{"example":{"searchParameters":{"q":"Python 入门教程","num":5,"gl":"cn","hl":"zh-cn","type":"videos","engine":"google"},"videos":[{"title":"…","link":"https://www.youtube.com/watch?v=x","duration":"3:21","source":"YouTube","channel":"…","position":1}],"billing":{"points":1,"balance":999,"summary":"本次：Serper -1 积分，剩余 999"}}}}},"400":{"description":"invalid_request：参数错误（网关拦截或引擎判定参数错）；operation_unavailable：该引擎的这个接口 / 档位暂未开放","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"unauthorized：缺少密钥或密钥无效","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"insufficient_points：积分不足","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited：超过套餐每秒请求数（排队超过上限）；engine_busy：引擎繁忙","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"engine_error：引擎暂时异常（已自动重试）","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"engine_unavailable：引擎暂不可用或暂未开放","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"q":{"type":"string","description":"搜索词，支持 site: / intitle: / filetype: 等 Google 搜索语法"},"gl":{"type":"string","description":"搜索所在国家，两位代码如 us / cn / jp / hk"},"hl":{"type":"string","description":"结果语言，如 zh-cn / zh-tw / en / ja"},"location":{"type":"string","description":"搜索发起地（城市级最准），如 Shanghai, China / Austin, Texas, United States"},"num":{"type":"integer","description":"1-10（最多 10 条）；该类型目前忽略 num、固定返回一页（11-03 实测：news / videos / places / scholar 约 10 条，shopping 约 40 条），统一接口不涉及；扣分与条数无关"},"page":{"type":"integer","description":"页码，从 1 开始（1-100）"},"tbs":{"type":"string","description":"时间范围：qdr:h（1 小时）/ qdr:d（24 小时）/ qdr:w / qdr:m / qdr:y"},"autocorrect":{"type":"boolean","description":"false = 不要自动纠错后的结果（默认 true）"}},"required":["q"]},"example":{"q":"Python 入门教程","num":5,"gl":"cn","hl":"zh-cn"}}}}}},"/v1/serper/places":{"post":{"operationId":"serper_places","summary":"Serper 地点搜索","description":"Google 地点搜索结果，参数名与返回结构与 Serper 官方 /places 一致（q / gl / hl / num / page …；鉴权用你的聚搜 Key，不用 X-API-KEY）。返回 places（title / address / latitude / longitude / rating / ratingCount / category / phoneNumber / website / cid）。","tags":["原生兼容 · Serper"],"responses":{"200":{"description":"成功","content":{"application/json":{"example":{"searchParameters":{"q":"咖啡馆 上海 静安","num":5,"type":"places","engine":"google"},"places":[{"position":1,"title":"…","address":"…","latitude":31.23,"longitude":121.47,"rating":4.5}],"billing":{"points":1,"balance":999,"summary":"本次：Serper -1 积分，剩余 999"}}}}},"400":{"description":"invalid_request：参数错误（网关拦截或引擎判定参数错）；operation_unavailable：该引擎的这个接口 / 档位暂未开放","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"unauthorized：缺少密钥或密钥无效","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"insufficient_points：积分不足","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited：超过套餐每秒请求数（排队超过上限）；engine_busy：引擎繁忙","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"engine_error：引擎暂时异常（已自动重试）","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"engine_unavailable：引擎暂不可用或暂未开放","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"q":{"type":"string","description":"搜索词，支持 site: / intitle: / filetype: 等 Google 搜索语法"},"gl":{"type":"string","description":"搜索所在国家，两位代码如 us / cn / jp / hk"},"hl":{"type":"string","description":"结果语言，如 zh-cn / zh-tw / en / ja"},"location":{"type":"string","description":"搜索发起地（城市级最准），如 Shanghai, China / Austin, Texas, United States"},"num":{"type":"integer","description":"1-10（最多 10 条）；该类型目前忽略 num、固定返回一页（11-03 实测：news / videos / places / scholar 约 10 条，shopping 约 40 条），统一接口不涉及；扣分与条数无关"},"page":{"type":"integer","description":"页码，从 1 开始（1-100）"},"autocorrect":{"type":"boolean","description":"false = 不要自动纠错后的结果（默认 true）"}},"required":["q"]},"example":{"q":"咖啡馆 上海 静安","num":5}}}}}},"/v1/serper/shopping":{"post":{"operationId":"serper_shopping","summary":"Serper 购物搜索","description":"Google 购物搜索结果，参数名与返回结构与 Serper 官方 /shopping 一致（q / gl / hl / num / page …；鉴权用你的聚搜 Key，不用 X-API-KEY）。返回 shopping（title / source / link / price / imageUrl / rating / ratingCount / productId / position）。","tags":["原生兼容 · Serper"],"responses":{"200":{"description":"成功","content":{"application/json":{"example":{"searchParameters":{"q":"降噪耳机","num":5,"type":"shopping","engine":"google"},"shopping":[{"title":"…","source":"Example Store","link":"https://example.com/p/1","price":"$99.00","position":1}],"billing":{"points":2,"balance":998,"summary":"本次：Serper -2 积分，剩余 998"}}}}},"400":{"description":"invalid_request：参数错误（网关拦截或引擎判定参数错）；operation_unavailable：该引擎的这个接口 / 档位暂未开放","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"unauthorized：缺少密钥或密钥无效","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"insufficient_points：积分不足","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited：超过套餐每秒请求数（排队超过上限）；engine_busy：引擎繁忙","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"engine_error：引擎暂时异常（已自动重试）","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"engine_unavailable：引擎暂不可用或暂未开放","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"q":{"type":"string","description":"搜索词，支持 site: / intitle: / filetype: 等 Google 搜索语法"},"gl":{"type":"string","description":"搜索所在国家，两位代码如 us / cn / jp / hk"},"hl":{"type":"string","description":"结果语言，如 zh-cn / zh-tw / en / ja"},"location":{"type":"string","description":"搜索发起地（城市级最准），如 Shanghai, China / Austin, Texas, United States"},"num":{"type":"integer","description":"1-10（最多 10 条）；该类型目前忽略 num、固定返回一页（11-03 实测：news / videos / places / scholar 约 10 条，shopping 约 40 条），统一接口不涉及；扣分与条数无关"},"page":{"type":"integer","description":"页码，从 1 开始（1-100）"},"autocorrect":{"type":"boolean","description":"false = 不要自动纠错后的结果（默认 true）"}},"required":["q"]},"example":{"q":"降噪耳机","num":5}}}}}},"/v1/serper/scholar":{"post":{"operationId":"serper_scholar","summary":"Serper 学术搜索","description":"Google 学术搜索结果，参数名与返回结构与 Serper 官方 /scholar 一致（q / gl / hl / num / page …；鉴权用你的聚搜 Key，不用 X-API-KEY）。返回 organic（title / link / publicationInfo / snippet / year / citedBy / pdfUrl / id）。","tags":["原生兼容 · Serper"],"responses":{"200":{"description":"成功","content":{"application/json":{"example":{"searchParameters":{"q":"large language model evaluation","num":5,"type":"scholar","engine":"google"},"organic":[{"title":"…","link":"https://example.org/paper","publicationInfo":"…","year":2025,"citedBy":120}],"billing":{"points":1,"balance":999,"summary":"本次：Serper -1 积分，剩余 999"}}}}},"400":{"description":"invalid_request：参数错误（网关拦截或引擎判定参数错）；operation_unavailable：该引擎的这个接口 / 档位暂未开放","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"unauthorized：缺少密钥或密钥无效","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"insufficient_points：积分不足","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited：超过套餐每秒请求数（排队超过上限）；engine_busy：引擎繁忙","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"engine_error：引擎暂时异常（已自动重试）","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"engine_unavailable：引擎暂不可用或暂未开放","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"q":{"type":"string","description":"搜索词，支持 site: / intitle: / filetype: 等 Google 搜索语法"},"gl":{"type":"string","description":"搜索所在国家，两位代码如 us / cn / jp / hk"},"hl":{"type":"string","description":"结果语言，如 zh-cn / zh-tw / en / ja"},"num":{"type":"integer","description":"1-10（最多 10 条）；该类型目前忽略 num、固定返回一页（11-03 实测：news / videos / places / scholar 约 10 条，shopping 约 40 条），统一接口不涉及；扣分与条数无关"},"page":{"type":"integer","description":"页码，从 1 开始（1-100）"},"autocorrect":{"type":"boolean","description":"false = 不要自动纠错后的结果（默认 true）"}},"required":["q"]},"example":{"q":"large language model evaluation","num":5}}}}}},"/v1/anysearch/search":{"post":{"operationId":"anysearch_search","summary":"AnySearch 搜索","description":"与 AnySearch 官方 /v1/search 一致：请求体、返回体原样，只把 request_id 换成我方的。","tags":["原生兼容 · AnySearch"],"responses":{"200":{"description":"成功","content":{"application/json":{"example":{"code":0,"message":"success","request_id":"js-20261031120000-a1b2c3d4e5f6","data":{"results":[{"title":"…","url":"https://example.com/a","snippet":"…","content":"…"}]},"billing":{"points":1,"balance":999,"summary":"本次：AnySearch -1 积分，剩余 999"}}}}},"400":{"description":"invalid_request：参数错误（网关拦截或引擎判定参数错）；operation_unavailable：该引擎的这个接口 / 档位暂未开放","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"unauthorized：缺少密钥或密钥无效","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"insufficient_points：积分不足","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited：超过套餐每秒请求数（排队超过上限）；engine_busy：引擎繁忙","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"engine_error：引擎暂时异常（已自动重试）","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"engine_unavailable：引擎暂不可用或暂未开放","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"query":{"type":"string","description":"搜索词"},"max_results":{"type":"integer","description":"返回条数，1-10"},"tag":{"type":"string","description":"官方垂直领域参数，原样透传"},"params":{"type":"object","description":"官方扩展参数，原样透传"},"format":{"type":"string","description":"官方返回格式参数，原样透传"}},"required":["query"]},"example":{"query":"量子计算 最新进展","max_results":5}}}}}},"/v1/brave/web/search":{"post":{"operationId":"brave_web/search","summary":"Brave 网页搜索","description":"与 Brave 官方 web/search 参数同名、返回结构一致（官方是 GET 查询参数，这里放进 JSON 请求体）。返回 web.results（title / url / description 等），按需还有 news / videos / discussions。","tags":["原生兼容 · Brave"],"responses":{"200":{"description":"成功","content":{"application/json":{"example":{"type":"search","query":{"original":"…"},"web":{"type":"search","results":[{"title":"…","url":"https://example.com/a","description":"…","page_age":"2026-10-01T08:00:00","extra_snippets":["…"]}]},"billing":{"points":2,"balance":998,"summary":"本次：Brave -2 积分，剩余 998"}}}}},"400":{"description":"invalid_request：参数错误（网关拦截或引擎判定参数错）；operation_unavailable：该引擎的这个接口 / 档位暂未开放","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"unauthorized：缺少密钥或密钥无效","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"insufficient_points：积分不足","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited：超过套餐每秒请求数（排队超过上限）；engine_busy：引擎繁忙","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"engine_error：引擎暂时异常（已自动重试）","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"engine_unavailable：引擎暂不可用或暂未开放","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"q":{"type":"string","description":"搜索词（≤ 600 字符、≤ 75 个词）"},"country":{"type":"string","description":"结果来源国家，两位代码如 US / JP / CN，或 ALL；默认 US"},"search_lang":{"type":"string","description":"结果语言，如 en / zh-hans / zh-hant / ja；默认 en"},"ui_lang":{"type":"string","description":"返回界面语言，如 en-US / zh-CN"},"count":{"type":"integer","description":"返回条数 1-10（最多 10 条），默认 10"},"offset":{"type":"integer","description":"翻页：跳过几页（每页 count 条），0-9"},"safesearch":{"type":"string","description":"off / moderate（默认）/ strict"},"spellcheck":{"type":"boolean","description":"是否拼写纠正，默认 true"},"freshness":{"type":"string","description":"pd（24 小时）/ pw（7 天）/ pm（31 天）/ py（一年），或 2026-01-01to2026-06-30"},"text_decorations":{"type":"boolean","description":"摘要里是否带高亮标记，默认 true"},"result_filter":{"type":"string","description":"只要这些类型，逗号分隔：web / news / videos / discussions / faq / infobox / query / locations"},"units":{"type":"string","description":"metric / imperial"},"goggles":{"type":"string","description":"自定义重排规则（Goggle 地址或定义），最多 3 个（可传数组）"},"extra_snippets":{"type":"boolean","description":"每条最多再附 5 段摘录"},"operators":{"type":"boolean","description":"是否启用 site: 等搜索语法，默认 true"},"include_fetch_metadata":{"type":"boolean","description":"附带抓取时间等元数据"}},"required":["q"]},"example":{"q":"solid-state battery mass production 2026","count":5,"country":"US"}}}}}},"/v1/brave/llm/context":{"post":{"operationId":"brave_llm/context","summary":"Brave 正文上下文（给 AI）","description":"与 Brave 官方 llm/context 参数同名、返回结构一致：搜索后直接给出每个网页里与问题相关的正文片段，适合 RAG / Agent 直接引用。默认最多 10 个网址。","tags":["原生兼容 · Brave"],"responses":{"200":{"description":"成功","content":{"application/json":{"example":{"grounding":{"generic":[{"url":"https://example.com/a","title":"…","snippets":["…","…"]}]},"sources":{"https://example.com/a":{"title":"…","hostname":"example.com"}},"billing":{"points":2,"balance":998,"summary":"本次：Brave -2 积分，剩余 998"}}}}},"400":{"description":"invalid_request：参数错误（网关拦截或引擎判定参数错）；operation_unavailable：该引擎的这个接口 / 档位暂未开放","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"unauthorized：缺少密钥或密钥无效","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"insufficient_points：积分不足","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited：超过套餐每秒请求数（排队超过上限）；engine_busy：引擎繁忙","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"engine_error：引擎暂时异常（已自动重试）","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"engine_unavailable：引擎暂不可用或暂未开放","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"q":{"type":"string","description":"问题或搜索词（≤ 600 字符、≤ 75 个词）"},"country":{"type":"string","description":"结果来源国家，两位代码如 US / JP / CN，或 ALL；默认 US"},"search_lang":{"type":"string","description":"结果语言，如 en / zh-hans；默认 en"},"count":{"type":"integer","description":"参与挑选正文的搜索结果数 1-50，默认 20"},"maximum_number_of_urls":{"type":"integer","description":"最多返回几个网址的正文 1-10（最多 10 条），默认 10"},"maximum_number_of_tokens":{"type":"integer","description":"正文总长度上限（约 token）1024-32768，默认 8192"},"maximum_number_of_tokens_per_url":{"type":"integer","description":"每个网址正文上限 512-8192，默认 4096"},"context_threshold_mode":{"type":"string","description":"相关度门槛：disabled / strict / lenient / balanced"},"safesearch":{"type":"string","description":"off / moderate / strict"},"spellcheck":{"type":"boolean","description":"是否拼写纠正，默认 true"},"operators":{"type":"boolean","description":"是否启用 site: 等搜索语法，默认 true"},"operators_fallback":{"type":"boolean","description":"搜索语法无结果时回退到原始结果，默认 true"},"freshness":{"type":"string","description":"pd / pw / pm / py，或 2026-01-01to2026-06-30"},"goggles":{"type":"string","description":"自定义重排规则，最多 3 个（可传数组）"},"enable_local":{"type":"boolean","description":"地点类问题返回地点信息（poi / map）"},"enable_source_metadata":{"type":"boolean","description":"sources 里附带站点名、图标、描述等"}},"required":["q"]},"example":{"q":"how deep is the mediterranean sea","maximum_number_of_urls":5}}}}}},"/v1/bocha/web-search":{"post":{"operationId":"bocha_web_search","summary":"博查 网页搜索","description":"与博查官方 web-search 一致（Bing 兼容结构）；log_id 换成我方 request_id。","tags":["原生兼容 · 博查"],"responses":{"200":{"description":"成功","content":{"application/json":{"example":{"code":200,"log_id":"js-20261031120000-a1b2c3d4e5f6","msg":null,"data":{"webPages":{"value":[{"name":"…","url":"https://example.cn/a","snippet":"…","summary":"…","siteName":"…","datePublished":"…"}]}},"billing":{"points":1,"balance":999,"summary":"本次：博查 -1 积分，剩余 999"}}}}},"400":{"description":"invalid_request：参数错误（网关拦截或引擎判定参数错）；operation_unavailable：该引擎的这个接口 / 档位暂未开放","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"unauthorized：缺少密钥或密钥无效","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"insufficient_points：积分不足","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited：超过套餐每秒请求数（排队超过上限）；engine_busy：引擎繁忙","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"engine_error：引擎暂时异常（已自动重试）","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"engine_unavailable：引擎暂不可用或暂未开放","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"query":{"type":"string","description":"搜索词"},"freshness":{"type":"string","description":"时间范围：noLimit / oneDay / oneWeek / oneMonth / oneYear，或 2025-01-01..2025-04-06"},"summary":{"type":"boolean","description":"是否返回长摘要，默认 false"},"include":{"type":"string","description":"只搜这些域名，多个用 | 或 , 分隔"},"exclude":{"type":"string","description":"排除这些域名，多个用 | 或 , 分隔"},"count":{"type":"integer","description":"返回条数，1-50"}},"required":["query"]},"example":{"query":"杭州 天气","summary":true,"count":5}}}}}},"/v1/baidu/web-search":{"post":{"operationId":"baidu_web_search","summary":"百度 网页搜索","description":"百度AI搜索的普通搜索口：返回网页结果（标题、链接、长摘要、发布时间）。与官方 web_search 等价，参数为我方简化面（query / count / freshness / include）。","tags":["原生兼容 · 百度"],"responses":{"200":{"description":"成功","content":{"application/json":{"example":{"request_id":"js-20261117120000-a1b2c3d4e5f6","references":[{"id":1,"title":"…","url":"https://example.cn/a","date":"2026-11-17 08:53:15","content":"…","snippet":"…","website":"…","type":"web"}],"billing":{"points":1,"balance":999,"summary":"本次：百度 -1 积分，剩余 999"}}}}},"400":{"description":"invalid_request：参数错误（网关拦截或引擎判定参数错）；operation_unavailable：该引擎的这个接口 / 档位暂未开放","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"unauthorized：缺少密钥或密钥无效","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"insufficient_points：积分不足","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited：超过套餐每秒请求数（排队超过上限）；engine_busy：引擎繁忙","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"engine_error：引擎暂时异常（已自动重试）","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"engine_unavailable：引擎暂不可用或暂未开放","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"query":{"type":"string","description":"搜索词"},"count":{"type":"integer","description":"返回条数，1-50，默认 10"},"freshness":{"type":"string","description":"时间范围：week（近 7 天）/ month（近 30 天）/ semiyear（近半年）/ year（近一年），不填 = 不限"},"include":{"type":"string","description":"只搜这些域名，多个用 | 或 , 分隔"}},"required":["query"]},"example":{"query":"杭州 天气","count":5}}}}}},"/v1/baidu/ai-search":{"post":{"operationId":"baidu_ai_search","summary":"百度 AI 搜索","description":"百度AI搜索的智能搜索生成口：先搜网页、再由大模型生成带引用的答案，返回答案 + 来源网页。暂只支持非流式（stream=false）。","tags":["原生兼容 · 百度"],"responses":{"200":{"description":"成功","content":{"application/json":{"example":{"request_id":"js-20261117120000-a1b2c3d4e5f6","choices":[{"index":0,"finish_reason":"stop","message":{"role":"assistant","content":"…"}}],"references":[{"id":1,"title":"…","url":"https://example.cn/a","date":"2026-11-17 08:53:15","content":"…","snippet":"…","website":"…","type":"web"}],"billing":{"points":3,"balance":997,"summary":"本次：百度 -3 积分，剩余 997"}}}}},"400":{"description":"invalid_request：参数错误（网关拦截或引擎判定参数错）；operation_unavailable：该引擎的这个接口 / 档位暂未开放","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"unauthorized：缺少密钥或密钥无效","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"insufficient_points：积分不足","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited：超过套餐每秒请求数（排队超过上限）；engine_busy：引擎繁忙","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"engine_error：引擎暂时异常（已自动重试）","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"engine_unavailable：引擎暂不可用或暂未开放","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"query":{"type":"string","description":"问题"},"count":{"type":"integer","description":"参考网页条数，1-50，默认 10"},"freshness":{"type":"string","description":"时间范围：week / month / semiyear / year，不填 = 不限"},"stream":{"type":"boolean","description":"只能为 false"}},"required":["query"]},"example":{"query":"今年诺贝尔物理学奖颁给了谁","count":5}}}}}},"/v1/redeem":{"post":{"operationId":"redeem","summary":"兑换卡密","description":"不带密钥时：兑换并开户，返回 api_key（登录控制台后可随时查看 / 复制，忘了或泄露可在控制台重置）。带密钥时：兑换到当前账户。","tags":["账户"],"responses":{"200":{"description":"成功","content":{"application/json":{"example":{"customer_id":1,"plan":"轻量卡","points":1000,"daily_points":null,"ends_at":"2026-11-30 12:00:00","api_key":"jsk_…","notice":"这是你的 API Key：登录控制台后可随时查看 / 复制。Key 也是控制台登录凭证，请妥善保存、不要外传；忘了或泄露可在控制台重置（旧 Key 立即失效）。"}}}},"400":{"description":"invalid_code：兑换码无效或已被使用","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited：超过套餐每秒请求数（排队超过上限）","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","description":"兑换码，形如 JS-LM-XXXX-XXXX（JS 后一段是代号：L 轻量 / S 标准 / F 旗舰，M 月 / Q 季 / Y 年；更早的老卡 JS-XXXX-XXXX-XXXX 同样可用）"}},"required":["code"]},"example":{"code":"JS-LM-ABCD-EFGH"}}}}}},"/v1/me":{"get":{"operationId":"me","summary":"余额与权益","description":"total = 可用积分合计；entitlements 列出每项权益及到期时间。","tags":["账户"],"responses":{"200":{"description":"成功","content":{"application/json":{"example":{"customer_id":1,"balance":{"total":93,"daily_left":0,"pack_left":93,"entitlements":[{"id":1,"kind":"trial","name":"轻量卡","left":93,"daily_points":null,"qps":2,"ends_at":"2026-11-30 12:00:00"}]},"qps":2}}}},"401":{"description":"unauthorized：缺少密钥或密钥无效","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]}]}},"/v1/engines":{"get":{"operationId":"engines","summary":"引擎目录","description":"当前开放（live）与即将上线（coming）的引擎、简介与接口路径；只有 live 的引擎可以调用。","tags":["账户"],"responses":{"200":{"description":"成功","content":{"application/json":{"example":{"engines":[{"name":"exa","label":"Exa","status":"live","category":"网页搜索","paths":["/v1/exa/search"]}]}}}}},"security":[]}},"/v1/usage":{"get":{"operationId":"usage","summary":"调用流水","description":"最近的调用，每条带引擎 / 操作 / 档位 / 本次扣分（points，未扣为 0）。可按引擎、时间筛选。","tags":["账户"],"responses":{"200":{"description":"成功","content":{"application/json":{"example":{"items":[{"request_id":"js-…","engine":"exa","operation":"search","tier":"standard","points":1,"outcome":"ok","result":"成功","created_at":"2026-10-31 12:00:00"}]}}}},"401":{"description":"unauthorized：缺少密钥或密钥无效","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]}],"parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer"},"description":"条数，1-500，默认 50（查询参数）"},{"name":"engine","in":"query","required":false,"schema":{"type":"string"},"description":"只看这个引擎（查询参数）"},{"name":"period","in":"query","required":false,"schema":{"type":"string"},"description":"today / 7d / 30d，不填为全部（查询参数）"}]}},"/v1/usage/summary":{"get":{"operationId":"usage_summary","summary":"按引擎扣分明细","description":"某段时间内各引擎的调用次数、扣分次数、扣分合计，以及按操作 · 档位的细分。","tags":["账户"],"responses":{"200":{"description":"成功","content":{"application/json":{"example":{"period":"7d","since":"2026-10-25 00:00:00","engines":[{"engine":"exa","label":"Exa","calls":12,"charged_calls":11,"points":11,"tiers":[{"operation":"search","tier":"standard","calls":12,"charged_calls":11,"points":11}]}],"total":{"calls":12,"charged_calls":11,"points":11}}}}},"401":{"description":"unauthorized：缺少密钥或密钥无效","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]}],"parameters":[{"name":"period","in":"query","required":false,"schema":{"type":"string"},"description":"today（默认）/ 7d / 30d（查询参数，北京时间按天算）"}]}},"/v1/pricing":{"get":{"operationId":"pricing","summary":"价目表","description":"每个引擎每个操作 · 档位每次调用的固定积分（含触发条件），以及在售套餐（calls_est = 约可调用基础搜索次数）。每张套餐的 terms 列出月付 / 季付 / 年付：price_fen 售价、per_month_fen 折合每月、save_pct 比按月买省的百分比、monthly_points 每月到账积分（季 / 年卡按月到账：每月一份，当月有效，下次到账时清零）。一份积分所有引擎通用。","tags":["账户"],"responses":{"200":{"description":"成功","content":{"application/json":{"example":{"engines":["exa","serpapi","tavily","serper","anysearch","brave","bocha","baidu"],"base_points":1,"rules":[{"engine":"exa","operation":"search","tier":"standard","points":1,"condition":"任意参数","is_default":1}],"groups":[{"engine":"exa","label":"Exa","operations":[{"operation":"search","label":"搜索","method":"POST","path":"/v1/exa/search","tiers":[{"tier":"standard","condition":"任意参数","points":1,"default":true}]}]}],"plans":[{"id":5,"kind":"trial","name":"轻量卡","price_fen":1900,"points":1000,"days":30,"qps":2,"buy_url":"https://wzyp.cn/item/sl23u6","calls_est":1000,"terms":[{"term":"month","label":"月付","id":5,"name":"轻量卡","months":1,"price_fen":1900,"per_month_fen":1900,"list_price_fen":1900,"save_pct":0,"monthly_points":1000,"days":30,"qps":2,"calls_est_monthly":1000},{"term":"quarter","label":"季付","id":8,"name":"轻量季卡","months":3,"price_fen":5100,"per_month_fen":1700,"list_price_fen":5700,"save_pct":11,"monthly_points":1000,"days":90,"qps":2,"calls_est_monthly":1000},{"term":"year","label":"年付","id":9,"name":"轻量年卡","months":12,"price_fen":19400,"per_month_fen":1617,"list_price_fen":22800,"save_pct":15,"monthly_points":1000,"days":365,"qps":2,"calls_est_monthly":1000}]}],"terms":[{"term":"month","label":"月付","months":1,"save_pct_max":0,"save_pct_min":0},{"term":"quarter","label":"季付","months":3,"save_pct_max":11,"save_pct_min":10},{"term":"year","label":"年付","months":12,"save_pct_max":15,"save_pct_min":15}]}}}}},"security":[]}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"jsk_ 开头的 API Key"}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"hint":{"type":"string","description":"怎么办（给人看的一句话）"}},"required":["code","message"]},"request_id":{"type":"string"}},"required":["error"]},"Billing":{"type":"object","description":"每次调用的返回里都有：本次扣分、剩余积分、一句话说明","properties":{"points":{"type":"integer"},"balance":{"type":"integer"},"summary":{"type":"string"},"by_engine":{"type":"object","description":"多引擎时每家扣分"}},"required":["points","balance","summary"]}}}}