# Firecrawl

> 只需更换 API URL 和密钥，即可通过 Search1API 使用 Firecrawl 的单页抓取和搜索端点，并了解哪些 Python 客户端会保留 URL 路径。

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

Search1API 兼容 Firecrawl 两个 API 版本中的单页抓取和搜索：`POST /v1/scrape`、`/v2/scrape`、`/v1/search` 和 `/v2/search`。将 Firecrawl API URL 设置为：

```text
https://api.search1api.com/compat/firecrawl
```

与 Firecrawl SDK 的做法一样，使用 `Authorization: Bearer YOUR_API_KEY` 携带你的 Search1API 密钥进行认证。

## 配置客户端

<Tabs items={['JavaScript', 'Python', 'Open WebUI']}>

<Tab value="JavaScript">

```ts
import Firecrawl from '@mendable/firecrawl-js';

const firecrawl = new Firecrawl({
  apiKey: process.env.SEARCH1API_KEY,
  apiUrl: 'https://api.search1api.com/compat/firecrawl',
});
const page = await firecrawl.scrape('https://hono.dev/docs/', { formats: ['markdown'] });
const results = await firecrawl.search('hono cloudflare workers', { limit: 5 });
```

</Tab>

<Tab value="Python">

```python
from firecrawl import AsyncFirecrawl

firecrawl = AsyncFirecrawl(
    api_key="YOUR_API_KEY",
    api_url="https://api.search1api.com/compat/firecrawl",
)
page = await firecrawl.scrape("https://hono.dev/docs/", formats=["markdown"])
results = await firecrawl.search("hono cloudflare workers", limit=5)
```

同步代码请使用 v1 客户端：

```python
from firecrawl import V1FirecrawlApp

firecrawl = V1FirecrawlApp(
    api_key="YOUR_API_KEY",
    api_url="https://api.search1api.com/compat/firecrawl",
)
page = firecrawl.scrape_url("https://hono.dev/docs/", formats=["markdown"])
```

</Tab>

<Tab value="Open WebUI">

选择 **firecrawl** 作为网页搜索引擎或网页加载器，将你的 Search1API 密钥填为 Firecrawl API 密钥，并设置：

```bash
FIRECRAWL_API_BASE_URL="https://api.search1api.com/compat/firecrawl"
```

</Tab>

</Tabs>

> **warn:** 在 `firecrawl-py` 4.x 中，默认的同步客户端（`Firecrawl`，也以 `FirecrawlApp` 导出）只用 `api_url` 的主机名构建请求 URL，并丢弃其路径，因此 `https://api.search1api.com/compat/firecrawl` 会变成 `https://api.search1api.com/v2/scrape`，请求以 `404` 失败。请按上文所示使用 `AsyncFirecrawl` 或 `V1FirecrawlApp`，两者都会保留路径。基于默认客户端构建的库，包括 LangChain 的 `FireCrawlLoader` 和 LlamaIndex 的 Firecrawl reader，也会受到同样的影响。

## 单页抓取

`url` 为必填项。页面以 Markdown 形式返回在 `data.markdown` 中，同时包含 `data.metadata.title`、`sourceURL`、`url` 和 `statusCode`。

只生成 Markdown。`formats` 中的其他条目，如 `html`、`links` 或 `screenshot`，会被忽略，对应字段也不会出现。`onlyMainContent`、`waitFor`、`timeout`、`actions` 等页面选项会被忽略。

## 搜索

| 字段 | 行为 |
| --- | --- |
| `query` | 必填。 |
| `limit` | v2 默认 `10`，v1 默认 `5`，每个来源最多 `50`。 |
| `sources` (v2) | `web`、`news` 和 `images`，可以是字符串或 `{ "type": … }` 对象。默认 `["web"]`。 |
| `tbs` | `qdr:h` 和 `qdr:d`（天）、`qdr:w`、`qdr:m` 和 `qdr:y`。 |
| `lang` | 结果的主语言。 |
| `includeDomains`, `excludeDomains` | 限定或排除站点。 |
| `scrapeOptions.formats` | 只要是非空列表，就会读取每条网页和新闻结果的页面，并在结果中加入 `markdown` 和 `metadata`。 |

与 Firecrawl 一样，除非设置了 `scrapeOptions.formats`，否则结果不包含页面内容。

v2 会针对所请求的来源返回 `data.web`（`url`、`title`、`description`、`position`）、`data.news`（`title`、`url`、`snippet`、`date`、`position`）和 `data.images`（`imageUrl`、`url`、`position`）。当某个来源失败而其他来源成功时，响应会包含 `warning`。v1 以 `{ url, title, description }` 列表的形式返回 `data`。

## 积分

| 请求 | 积分 |
| --- | --- |
| 单页抓取 | 1 |
| 搜索 | 每个来源 1 |
| 带 `scrapeOptions.formats` 的搜索 | 每个来源 1，每读取一个页面再加 1 |

## 不支持的功能

Crawl、batch scrape、map、extract 等任务类端点返回 `404`。如需处理整个站点，请使用 Search1API 的 [`/deepcrawl`](https://s1.dev/zh/docs/advanced/deepcrawl) 和 [`/sitemap`](https://s1.dev/zh/docs/advanced/sitemap)。

## 错误

错误返回 `{ "success": false, "error": "message" }` 及相应状态码。无法读取的页面返回 `502`，Firecrawl JavaScript SDK 会先重试，然后才抛出错误。