> ## Documentation Index
> Fetch the complete documentation index at: https://student-213fb9fc.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# 抓取
> 将任意 URL 转换为干净的数据
Firecrawl 将网页转换为 Markdown，非常适合 LLM 应用。
* 处理复杂环节：代理、缓存、速率限制、被 JS 阻止的内容
* 支持动态内容：动态网站、JS 渲染站点、PDF、图片
* 输出干净的 Markdown、结构化数据、截图或 HTML
详情请参阅 [Scrape Endpoint API 参考](https://docs.firecrawl.dev/api-reference/endpoint/scrape)。
在交互式 Playground 中测试抓取——无需写代码。
## 使用 Firecrawl 抓取 URL
### /scrape 端点
用于抓取指定 URL 并获取其内容。
### 安装
```python Python theme={null}
# 使用 pip 安装 firecrawl-py
from firecrawl import Firecrawl
firecrawl = Firecrawl(api_key="fc-YOUR-API-KEY")
```
```js Node theme={null}
# 使用 npm 安装 @mendable/firecrawl-js
import Firecrawl from '@mendable/firecrawl-js';
const firecrawl = new Firecrawl({ apiKey: "fc-YOUR-API-KEY" });
```
```bash CLI theme={null}
# 使用 npm 全局安装
npm install -g firecrawl
# 身份验证(一次性设置)
firecrawl login
```
### 使用方式
```python Python theme={null}
from firecrawl import Firecrawl
firecrawl = Firecrawl(api_key="fc-YOUR-API-KEY")
# 抓取网站：
doc = firecrawl.scrape("https://firecrawl.dev", formats=["markdown", "html"])
print(doc)
```
```js Node theme={null}
import Firecrawl from '@mendable/firecrawl-js';
const firecrawl = new Firecrawl({ apiKey: "fc-YOUR-API-KEY" });
// 抓取网站：
const doc = await firecrawl.scrape('https://firecrawl.dev', { formats: ['markdown', 'html'] });
console.log(doc);
```
```bash cURL theme={null}
curl -s -X POST "https://api.firecrawl.dev/v2/scrape" \
-H "Authorization: Bearer $FIRECRAWL_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"url": "https://firecrawl.dev",
"formats": ["markdown", "html"]
}'
```
```bash CLI theme={null}
# Scrape a URL and get markdown
firecrawl https://firecrawl.dev
# 使用多种格式(返回 JSON)
firecrawl https://firecrawl.dev --format markdown,html,links --pretty
```
有关参数的更多信息，请参阅 [API 参考](https://docs.firecrawl.dev/api-reference/endpoint/scrape)。
每次抓取会消耗 1 个积分。某些选项会产生额外消耗：JSON 模式每页额外消耗 4 个积分，高级代理（enhanced proxy）每页额外消耗 4 个积分，PDF 解析每个 PDF 页面额外消耗 1 个积分。
### 响应
各 SDK 会直接返回数据对象。cURL 将按下方所示原样返回载荷。
```json theme={null}
{
"success": true,
"data" : {
"markdown": "Launch Week I 开始了！[查看我们第 2 天的发布 🚀](https://www.firecrawl.dev/blog/launch-week-i-day-2-doubled-rate-limits)[💥 获享 2 个月免费...",
"html": "
## 抓取 formats
现在你可以选择输出所需的 formats。你可以指定多个输出 formats。支持的 formats 包括：
* Markdown（`markdown`）
* 摘要（`summary`）
* HTML（`html`）- 页面 HTML 的清洗版本
* 原始 HTML（`rawHtml`，按页面返回的不经修改的 HTML）
* 截图（`screenshot`，可选项包括 `fullPage`、`quality`、`viewport`）
* 链接（`links`）
* JSON（`json`）- 结构化输出
* 图片（`images`）- 提取页面中的所有图片 URL
* 品牌（`branding`）- 提取品牌识别与设计系统
输出键将与你选择的 format 对应。
### /scrape（使用 JSON）端点
用于从抓取的页面中提取结构化数据。
```python Python theme={null}
from firecrawl import Firecrawl
from pydantic import BaseModel
app = Firecrawl(api_key="fc-YOUR-API-KEY")
class CompanyInfo(BaseModel):
company_mission: str
supports_sso: bool
is_open_source: bool
is_in_yc: bool
result = app.scrape(
'https://firecrawl.dev',
formats=[{
"type": "json",
"schema": CompanyInfo.model_json_schema()
}],
only_main_content=False,
timeout=120000
)
print(result)
```
```js Node theme={null}
import Firecrawl from "@mendable/firecrawl-js";
import { z } from "zod";
const app = new Firecrawl({
apiKey: "fc-YOUR_API_KEY"
});
// 定义用于提取内容的模式
const schema = z.object({
company_mission: z.string(),
supports_sso: z.boolean(),
is_open_source: z.boolean(),
is_in_yc: z.boolean()
});
const result = await app.scrape("https://firecrawl.dev", {
formats: [{
type: "json",
schema: schema
}],
});
console.log(result);
```
```bash cURL theme={null}
curl -X POST https://api.firecrawl.dev/v2/scrape \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-d '{
"url": "https://firecrawl.dev",
"formats": [ {
"type": "json",
"schema": {
"type": "object",
"properties": {
"company_mission": {
"type": "string"
},
"supports_sso": {
"type": "boolean"
},
"is_open_source": {
"type": "boolean"
},
"is_in_yc": {
"type": "boolean"
}
},
"required": [
"company_mission",
"supports_sso",
"is_open_source",
"is_in_yc"
]
}
} ]
}'
```
输出：
```json JSON theme={null}
{
"success": true,
"data": {
"json": {
"company_mission": "AI 赋能的网页抓取与数据抽取",
"supports_sso": true,
"is_open_source": true,
"is_in_yc": true
},
"metadata": {
"title": "Firecrawl",
"description": "AI 赋能的网页抓取与数据抽取",
"robots": "follow, index",
"ogTitle": "Firecrawl",
"ogDescription": "AI 赋能的网页抓取与数据抽取",
"ogUrl": "https://firecrawl.dev/",
"ogImage": "https://firecrawl.dev/og.png",
"ogLocaleAlternate": [],
"ogSiteName": "Firecrawl",
"sourceURL": "https://firecrawl.dev/"
},
}
}
```
现在，你只需向端点传入一个 `prompt`，即可在不提供 schema 的情况下进行提取。LLM 会自行决定数据结构。
```python Python theme={null}
from firecrawl import Firecrawl
app = Firecrawl(api_key="fc-YOUR-API-KEY")
result = app.scrape(
'https://firecrawl.dev',
formats=[{
"type": "json",
"prompt": "从页面中提取公司使命。"
}],
only_main_content=False,
timeout=120000
)
print(result)
```
```js Node theme={null}
import Firecrawl from "@mendable/firecrawl-js";
const app = new Firecrawl({
apiKey: "fc-YOUR_API_KEY"
});
const result = await app.scrape("https://firecrawl.dev", {
formats: [{
type: "json",
prompt: "从页面中提取公司使命。"
}]
});
console.log(result);
```
```bash cURL theme={null}
curl -X POST https://api.firecrawl.dev/v2/scrape \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-d '{
"url": "https://firecrawl.dev",
"formats": [{
"type": "json",
"prompt": "从页面中提取公司使命。"
}]
}'
```
输出：
```json JSON theme={null}
{
"success": true,
"data": {
"json": {
"company_mission": "AI 驱动的网页抓取与数据抽取",
},
"metadata": {
"title": "Firecrawl",
"description": "AI 驱动的网页抓取与数据抽取",
"robots": "follow, index",
"ogTitle": "Firecrawl",
"ogDescription": "AI 驱动的网页抓取与数据抽取",
"ogUrl": "https://firecrawl.dev/",
"ogImage": "https://firecrawl.dev/og.png",
"ogLocaleAlternate": [],
"ogSiteName": "Firecrawl",
"sourceURL": "https://firecrawl.dev/"
},
}
}
```
### JSON 格式选项
使用 `json` 格式时，在 `formats` 中传入一个对象，包含以下参数：
* `schema`：用于结构化输出的 JSON Schema。
* `prompt`：可选提示；在提供 schema 时或仅需轻量指引时用于辅助抽取。
## 提取品牌识别度
### /scrape（品牌信息）端点
branding 格式会从网页中提取完整的品牌识别信息，包括颜色、字体、排版、间距、UI 组件等。它适用于设计系统分析、品牌监测，或构建需要理解网站视觉风格的工具。
```python Python theme={null}
from firecrawl import Firecrawl
firecrawl = Firecrawl(api_key='fc-YOUR_API_KEY')
result = firecrawl.scrape(
url='https://firecrawl.dev',
formats=['branding']
)
print(result['branding'])
```
```js Node theme={null}
import Firecrawl from '@mendable/firecrawl-js';
const firecrawl = new Firecrawl({ apiKey: "fc-YOUR-API-KEY" });
const result = await firecrawl.scrape('https://firecrawl.dev', {
formats: ['branding']
});
console.log(result.branding);
```
```bash cURL theme={null}
curl -s -X POST "https://api.firecrawl.dev/v2/scrape" \
-H "Authorization: Bearer $FIRECRAWL_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"url": "https://firecrawl.dev",
"formats": ["branding"]
}'
```
### 响应
品牌配置会返回一个完整的 `BrandingProfile` 对象，其结构如下：
```json Output theme={null}
{
"success": true,
"data": {
"branding": {
"colorScheme": "dark",
"logo": "https://firecrawl.dev/logo.svg",
"colors": {
"primary": "#FF6B35",
"secondary": "#004E89",
"accent": "#F77F00",
"background": "#1A1A1A",
"textPrimary": "#FFFFFF",
"textSecondary": "#B0B0B0"
},
"fonts": [
{
"family": "Inter"
},
{
"family": "Roboto Mono"
}
],
"typography": {
"fontFamilies": {
"primary": "Inter",
"heading": "Inter",
"code": "Roboto Mono"
},
"fontSizes": {
"h1": "48px",
"h2": "36px",
"h3": "24px",
"body": "16px"
},
"fontWeights": {
"regular": 400,
"medium": 500,
"bold": 700
}
},
"spacing": {
"baseUnit": 8,
"borderRadius": "8px"
},
"components": {
"buttonPrimary": {
"background": "#FF6B35",
"textColor": "#FFFFFF",
"borderRadius": "8px"
},
"buttonSecondary": {
"background": "transparent",
"textColor": "#FF6B35",
"borderColor": "#FF6B35",
"borderRadius": "8px"
}
},
"images": {
"logo": "https://firecrawl.dev/logo.svg",
"favicon": "https://firecrawl.dev/favicon.ico",
"ogImage": "https://firecrawl.dev/og-image.png"
}
}
}
}
```
### 品牌档案结构
`branding` 对象包含以下属性：
* `colorScheme`: 检测到的配色方案（`"light"` 或 `"dark"`）
* `logo`: 主徽标的 URL
* `colors`: 包含品牌颜色的对象：
* `primary`、`secondary`、`accent`: 主要品牌色
* `background`、`textPrimary`、`textSecondary`: 界面颜色
* `link`、`success`、`warning`、`error`: 语义颜色
* `fonts`: 页面中使用的字体系列数组
* `typography`: 详细的排版信息：
* `fontFamilies`: 正文、标题与代码字体系列
* `fontSizes`: 标题与正文的尺寸定义
* `fontWeights`: 字重定义（细体、常规、中等、粗体）
* `lineHeights`: 不同文本类型的行高值
* `spacing`: 间距与布局信息：
* `baseUnit`: 基础间距单位（像素）
* `borderRadius`: 默认圆角
* `padding`、`margins`: 间距值
* `components`: UI 组件样式：
* `buttonPrimary`、`buttonSecondary`: 按钮样式
* `input`: 输入框样式
* `icons`: 图标样式信息
* `images`: 品牌图像（logo、favicon、og:image）
* `animations`: 动画与过渡设置
* `layout`: 布局配置（栅格、页眉/页脚高度）
* `personality`: 品牌个性特征（语气、调性、目标受众）
### 与其他 formats 结合使用
你可以将 branding 格式与其他 formats 组合，以获取更全面的页面数据：
```python Python theme={null}
from firecrawl import Firecrawl
firecrawl = Firecrawl(api_key='fc-YOUR_API_KEY')
result = firecrawl.scrape(
url='https://firecrawl.dev',
formats=['markdown', 'branding', 'screenshot']
)
print(result['markdown'])
print(result['branding'])
print(result['screenshot'])
```
```js Node theme={null}
import Firecrawl from '@mendable/firecrawl-js';
const firecrawl = new Firecrawl({ apiKey: "fc-YOUR-API-KEY" });
const result = await firecrawl.scrape('https://firecrawl.dev', {
formats: ['markdown', 'branding', 'screenshot']
});
console.log(result.markdown);
console.log(result.branding);
console.log(result.screenshot);
```
```bash cURL theme={null}
curl -s -X POST "https://api.firecrawl.dev/v2/scrape" \
-H "Authorization: Bearer $FIRECRAWL_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"url": "https://firecrawl.dev",
"formats": ["markdown", "branding", "screenshot"]
}'
```
## 使用 actions 与页面交互
Firecrawl 允许你在抓取页面内容之前对网页执行各种 actions。这对于与动态内容交互、在页面之间导航，或访问需要用户操作的内容特别有用。
下面是一个示例，演示如何使用 actions 访问 google.com，搜索 Firecrawl，点击第一个结果，并截取页面截图。
在执行其他 actions 之前或之后，几乎都应使用 `wait` action，为页面加载预留足够时间。
### 示例
```python Python theme={null}
from firecrawl import Firecrawl
firecrawl = Firecrawl(api_key="fc-YOUR-API-KEY")
doc = firecrawl.scrape(
url="https://example.com/login",
formats=["markdown"],
actions=[
{"type": "write", "text": "john@example.com"},
{"type": "press", "key": "Tab"},
{"type": "write", "text": "secret"},
{"type": "click", "selector": 'button[type="submit"]'},
{"type": "wait", "milliseconds": 1500},
{"type": "screenshot", "full_page": True},
],
)
print(doc.markdown, doc.screenshot)
```
```js Node（Node.js） theme={null}
import Firecrawl from '@mendable/firecrawl-js';
const firecrawl = new Firecrawl({ apiKey: "fc-YOUR-API-KEY" });
const doc = await firecrawl.scrape('https://example.com/login', {
formats: ['markdown'],
actions: [
{ type: 'write', text: 'john@example.com' },
{ type: 'press', key: 'Tab' },
{ type: 'write', text: 'secret' },
{ type: 'click', selector: 'button[type="submit"]' },
{ type: 'wait', milliseconds: 1500 },
{ type: 'screenshot', fullPage: true },
],
});
console.log(doc.markdown, doc.screenshot);
```
```bash cURL theme={null}
curl -X POST https://api.firecrawl.dev/v2/scrape \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-d '{
"url": "https://example.com/login",
"formats": ["markdown"],
"actions": [
{ "type": "write", "text": "john@example.com" },
{ "type": "press", "key": "Tab" },
{ "type": "write", "text": "secret" },
{ "type": "click", "selector": "button[type=\"submit\"]" },
{ "type": "wait", "milliseconds": 1500 },
{ "type": "screenshot", "fullPage": true },
],
}'
```
### 输出
```json JSON theme={null}
{
"success": true,
"data": {
"markdown": "我们的首次 Launch Week 已圆满结束！[查看回顾 🚀](blog/firecrawl-launch-week-1-recap)...",
"actions": {
"screenshots": [
"https://alttmdsdujxrfnakrkyi.supabase.co/storage/v1/object/public/media/screenshot-75ef2d87-31e0-4349-a478-fb432a29e241.png"
],
"scrapes": [
{
"url": "https://www.firecrawl.dev/",
"html": "Firecrawl
"
}
]
},
"metadata": {
"title": "首页 - Firecrawl",
"description": "Firecrawl 可抓取并将任意网站转换为干净的 Markdown。",
"language": "en",
"keywords": "Firecrawl,Markdown,数据,Mendable,LangChain",
"robots": "follow, index",
"ogTitle": "Firecrawl",
"ogDescription": "将任意网站转换为适配 LLM 的数据。",
"ogUrl": "https://www.firecrawl.dev/",
"ogImage": "https://www.firecrawl.dev/og.png?123",
"ogLocaleAlternate": [],
"ogSiteName": "Firecrawl"
"sourceURL": "http://google.com",
"statusCode": 200
}
}
}
```
有关 actions 参数的更多信息，请参见 [API 参考](https://docs.firecrawl.dev/api-reference/endpoint/scrape)。
## 位置与语言
指定国家/地区和首选语言，以根据你的目标位置和语言偏好获取相关内容。
### 工作原理
当你指定位置设置时，Firecrawl 会在可用时使用合适的代理，并仿真相应的语言和时区设置。默认情况下，若未指定位置，位置将设为“US”。
### 用法
要使用位置和语言设置，请在请求体中包含 `location` 对象，并提供以下属性：
* `country`：ISO 3166-1 alpha-2 国家/地区代码（例如“US”“AU”“DE”“JP”）。默认值为“US”。
* `languages`：按优先级排序的首选语言和区域设置数组。默认使用所设位置对应的语言。
```python Python theme={null}
from firecrawl import Firecrawl
firecrawl = Firecrawl(api_key="fc-YOUR-API-KEY")
doc = firecrawl.scrape('https://example.com',
formats=['markdown'],
location={
'country': 'US',
'languages': ['en']
}
)
print(doc)
```
```js Node theme={null}
import Firecrawl from '@mendable/firecrawl-js';
const firecrawl = new Firecrawl({ apiKey: "fc-YOUR-API-KEY" });
const doc = await firecrawl.scrape('https://example.com', {
formats: ['markdown'],
location: { country: 'US', languages: ['en'] },
});
console.log(doc.metadata);
```
```bash cURL theme={null}
curl -X POST "https://api.firecrawl.dev/v2/scrape" \
-H "Authorization: Bearer $FIRECRAWL_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"url": "https://example.com",
"formats": ["markdown"],
"location": { "country": "US", "languages": ["en"] }
}'
```
有关受支持位置的更多详情，请参阅[代理文档](/zh/features/proxies)。
## 缓存与 maxAge（缓存）
为加快请求速度，当有较新的副本可用时，Firecrawl 默认会直接从缓存返回结果。
* **默认新鲜度窗口**：`maxAge = 172800000` 毫秒（2 天）。如果缓存页面仍在该窗口内，将立即返回；否则会重新抓取页面并写入缓存。
* **性能**：在数据对时效性要求不高时，抓取速度可提升至最多 5 倍。
* **始终获取最新**：将 `maxAge` 设为 `0`。注意，这会完全绕过缓存，因此每次请求都会走完整的抓取流水线，这意味着请求完成所需时间更长，也更有可能失败。如果对每个请求的实时性不是绝对关键，建议使用非零的 `maxAge`。
* **避免存储**：如果不希望 Firecrawl 为本次请求缓存/存储结果，将 `storeInCache` 设为 `false`。
* **变更跟踪**：包含 `changeTracking` 的请求会绕过缓存，因此会忽略 `maxAge`。
示例（强制获取最新内容）：
```python Python theme={null}
from firecrawl import Firecrawl
firecrawl = Firecrawl(api_key='fc-YOUR_API_KEY')
doc = firecrawl.scrape(url='https://example.com', max_age=0, formats=['markdown'])
print(doc)
```
```js Node theme={null}
import Firecrawl from '@mendable/firecrawl-js';
const firecrawl = new Firecrawl({ apiKey: "fc-YOUR-API-KEY" });
const doc = await firecrawl.scrape('https://example.com', { maxAge: 0, formats: ['markdown'] });
console.log(doc);
```
```bash cURL theme={null}
curl -s -X POST "https://api.firecrawl.dev/v2/scrape" \
-H "Authorization: Bearer $FIRECRAWL_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"url": "https://example.com",
"maxAge": 0,
"formats": ["markdown"]
}'
```
示例（使用 10 分钟缓存窗口）：
```python Python theme={null}
from firecrawl import Firecrawl
firecrawl = Firecrawl(api_key='fc-YOUR_API_KEY')
doc = firecrawl.scrape(url='https://example.com', max_age=600000, formats=['markdown', 'html'])
print(doc)
```
```js Node theme={null}
const firecrawl = new Firecrawl({ apiKey: "fc-YOUR-API-KEY" });
const doc = await firecrawl.scrape('https://example.com', { maxAge: 600000, formats: ['markdown', 'html'] });
console.log(doc);
```
```bash cURL theme={null}
curl -s -X POST "https://api.firecrawl.dev/v2/scrape" \
-H "Authorization: Bearer $FIRECRAWL_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"url": "https://example.com",
"maxAge": 600000,
"formats": ["markdown", "html"]
}'
```
## 批量抓取多个 URL
你现在可以同时批量抓取多个 URL。它以起始 URL 和可选参数作为输入。params 参数允许你为批量抓取任务指定其他选项，例如输出 formats。
### 工作原理
它与 `/crawl` 端点的运行方式非常相似。它会提交一个批量抓取作业，并返回一个作业 ID，用于检查该批量抓取的状态。
SDK 提供两种方式：同步与异步。同步方式会直接返回批量抓取作业的结果，异步方式则会返回一个作业 ID，供您用于查询批量抓取的状态。
### 使用方法
```python Python theme={null}
from firecrawl import Firecrawl
firecrawl = Firecrawl(api_key="fc-你的 API 密钥")
job = firecrawl.batch_scrape([
"https://firecrawl.dev",
"https://docs.firecrawl.dev",
], formats=["markdown"], poll_interval=2, wait_timeout=120)
print(job)
```
```js Node theme={null}
import Firecrawl from '@mendable/firecrawl-js';
const firecrawl = new Firecrawl({ apiKey: "fc-YOUR-API-KEY" });
const job = await firecrawl.batchScrape([
'https://firecrawl.dev',
'https://docs.firecrawl.dev',
], { options: { formats: ['markdown'] }, pollInterval: 2, timeout: 120 });
console.log(job);
```
```bash cURL theme={null}
curl -s -X POST "https://api.firecrawl.dev/v2/batch/scrape" \
-H "Authorization: Bearer $FIRECRAWL_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"urls": ["https://firecrawl.dev", "https://docs.firecrawl.dev"],
"formats": ["markdown"]
}'
```
### Response
如果你使用 SDK 的同步方法，将直接返回批量抓取任务的结果；否则会返回一个作业 ID，你可以用它来查询批量抓取的状态。
#### 同步执行
```json 已完成 theme={null}
{
"status": "completed",
"total": 36,
"completed": 36,
"creditsUsed": 36,
"expiresAt": "2024-00-00T00:00:00.000Z",
"next": "https://api.firecrawl.dev/v2/batch/scrape/123-456-789?skip=26",
"data": [
{
"markdown": "[Firecrawl 文档首页！[浅色标志](https://mintlify.s3-us-west-1.amazonaws.com/firecrawl/logo/light.svg)!...",
"html": "...",
"metadata": {
"title": "使用 Groq Llama 3 构建“网站对话”功能 | Firecrawl",
"language": "en",
"sourceURL": "https://docs.firecrawl.dev/learn/rag-llama3",
"description": "了解如何使用 Firecrawl、Groq Llama 3 和 LangChain 构建“与你的网站对话”的机器人。",
"ogLocaleAlternate": [],
"statusCode": 200
}
},
...
]
}
```
#### 异步
你可以使用作业 ID 调用 `/batch/scrape/{id}` 端点来查看批量抓取的状态。该端点应在作业仍在运行期间或刚完成后使用，**因为批量抓取作业会在 24 小时后过期**。
```json theme={null}
{
"success": true,
"id": "123-456-789",
"url": "https://api.firecrawl.dev/v2/batch/scrape/123-456-789"
}
```
## 增强模式
对于复杂网站，Firecrawl 提供了增强模式，在提高成功率的同时保护隐私。
了解更多关于[增强模式](/zh/features/enhanced-mode)的信息。