# 兼容 API

> 保留为 SearXNG、Tavily、Exa、Firecrawl、Jina、Bing Web Search、Brave Search 或 Google CSE 编写的代码，只需更换基础 URL 和密钥即可改用 Search1API。

Canonical URL: https://s1.dev/zh/docs/compatibility/overview

Search1API 兼容另外八种搜索 API 的请求和响应格式，其中包括 Google Custom Search JSON API（CSE）的基础网页搜索。如果你的项目已经在调用其中之一，只需更改基础 URL 和 API 密钥，其余代码保持不变：受支持的 SDK 调用、请求参数和结果解析都无需改动。请先确认对应协议的限制：Google CSE 仅支持第一页网页搜索，且不会导入原有的 `cx` 设置。

| API | 基础 URL 或端点 | 支持的操作 |
| --- | --- | --- |
| [SearXNG](https://s1.dev/zh/docs/compatibility/searxng) | `https://api.search1api.com/compat/searxng/YOUR_API_KEY` | 搜索、新闻、图片 |
| [Tavily](https://s1.dev/zh/docs/compatibility/tavily) | `https://api.search1api.com/compat/tavily` | 搜索、内容提取 |
| [Exa](https://s1.dev/zh/docs/compatibility/exa) | `https://api.search1api.com/compat/exa` | 搜索、内容获取 |
| [Firecrawl](https://s1.dev/zh/docs/compatibility/firecrawl) | `https://api.search1api.com/compat/firecrawl` | 单页抓取、搜索（v1 和 v2） |
| [Jina](https://s1.dev/zh/docs/compatibility/jina) | `https://api.search1api.com/compat/jina/r` 和 `/compat/jina/s` | Reader、搜索 |
| [Bing Web Search v7](https://s1.dev/zh/docs/compatibility/bing) | `https://api.search1api.com/compat/bing/v7.0/search` | 网页、新闻、图片搜索 |
| [Google Custom Search JSON API](https://s1.dev/zh/docs/compatibility/google) | `https://api.search1api.com/compat/google/customsearch/v1` | 第一页网页搜索，最多 10 条结果 |
| [Brave Search](https://s1.dev/zh/docs/compatibility/brave) | `https://api.search1api.com/compat/brave/res/v1/web/search` | 网页、新闻、图片搜索 |

在客户端要求填写其他服务密钥的地方，填入你的 Search1API API 密钥。每个页面都列出了需要修改的设置或 SDK 参数。

## 迁移指南

根据你当前使用的客户端选择迁移概览：[SearXNG](https://s1.dev/compatible-apis/searxng)、[Google CSE](https://s1.dev/compatible-apis/google-cse) 或 [Bing v7](https://s1.dev/compatible-apis/bing)。这些概览说明如何切换；下方的参考页面记录参数和响应差异。

## 请求如何处理

兼容请求会被转换为对应的 Search1API 请求（`/search`、`/news` 或 `/crawl`），并以原 API 的响应格式返回。因此：

- **积分和限制与原生 API 相同。** 一次兼容搜索的费用与等价的 `/search` 或 `/news` 请求相同。参见[积分与限制](https://s1.dev/zh/docs/essentials/credits-and-limits)。
- **读取页面内容按页计费。** 当请求要求获取搜索结果的全文时（Tavily `include_raw_content`、Exa `contents.text`、Firecrawl `scrapeOptions.formats`，以及默认情况下的 Jina 搜索），每成功读取一个页面增加 1 积分，与 `crawl_results` 相同。读取明确指定的 URL（Tavily 内容提取、Exa 内容获取、Firecrawl 单页抓取、Jina Reader）时，每读取一页消耗 1 积分。
- **一个请求可能多次计入速率限制。** 搜索多个引擎或来源的请求，会针对每种搜索类型（网页或新闻）各发起一次原生请求，每次都计入每分钟限制。
- **未知或不支持的选项会被忽略。** 请求通常仍会成功，只是该选项不起作用。Google CSE 在分页、图片搜索、SafeSearch 和非 JSON 输出上是例外：这些情况返回 `400`，而不是给出误导性的响应。被忽略的 CSE 选项会列在 `X-Search1API-Ignored` 中。每个页面都列出了哪些选项会被转换。
- **没有 Search1API 对应项的字段返回为空。** 例如，Tavily 的 `answer` 为 `null`，Brave 的 `extra_snippets` 会被省略。不会为了填充这些字段而编造值。
- **错误沿用原 API 的错误格式**，状态码则使用 Search1API 的，例如密钥无效时返回 `401`，积分耗尽时返回 `402`，达到速率限制时返回 `429`。

> **info:** Google CSE 仅支持第一页（最多 10 条结果）；`start` 不为 `1` 时返回 `400`，且不收取搜索费用。对于其他兼容协议，每个引擎都能返回一次查询的前 50 条结果，因此分页参数在前几页有效。超过第 50 条结果后，只有 Bing、百度、中文 Bing 和 Grokipedia 可以继续翻页，且起始位置须为 10 的倍数。无法到达的页面返回空结果列表，且不计费。

## 不支持的功能

兼容 API 涵盖搜索、新闻、图片搜索和单页读取。生成式回答与摘要、结构化提取、截图、浏览器操作、站点地图和异步抓取任务都无法通过它们使用。如需全站抓取和结构化提取，请使用 Search1API 自有的 [`/deepcrawl`](https://s1.dev/zh/docs/advanced/deepcrawl)、[`/sitemap`](https://s1.dev/zh/docs/advanced/sitemap) 和 [`/extract`](https://s1.dev/zh/docs/advanced/extract)。

## 已测试的客户端

以下客户端在未做任何修改的情况下，针对兼容端点运行过：

| API | 客户端 |
| --- | --- |
| SearXNG | LangChain `SearxSearchWrapper`（Python）和 `SearxngSearch`（JS）；Open WebUI、Perplexica 和 gpt-researcher 的请求格式 |
| Tavily | `tavily-python` 0.8.5、`@tavily/core` 0.7.14 |
| Exa | `exa-py` 2.26.0、`exa-js` 2.26.0 |
| Firecrawl | `@mendable/firecrawl-js` 4.51.0；`firecrawl-py` 4.54.0 的 `V1FirecrawlApp` 和 `AsyncFirecrawl` |
| Jina | Open WebUI 的 Jina 搜索请求格式 |
| Bing Web Search v7 | LangChain `BingSearchAPIWrapper`；Open WebUI 的 Bing 请求格式 |
| Google Custom Search JSON API | `google-api-python-client` 2.201.0 `cse().list()`，需覆盖 API 端点 |
| Brave Search | LangChain `BraveSearchWrapper` |

其他版本和客户端只要发送相同的请求，很可能也能正常工作，但尚未经过测试。

- [SearXNG](https://s1.dev/zh/docs/compatibility/searxng)

- [Tavily](https://s1.dev/zh/docs/compatibility/tavily)

- [Exa](https://s1.dev/zh/docs/compatibility/exa)

- [Firecrawl](https://s1.dev/zh/docs/compatibility/firecrawl)

- [Jina](https://s1.dev/zh/docs/compatibility/jina)

- [Bing Web Search v7](https://s1.dev/zh/docs/compatibility/bing)

- [Google CSE 迁移](https://s1.dev/zh/docs/compatibility/google)

- [Brave Search](https://s1.dev/zh/docs/compatibility/brave)