从 v1 迁移到 v2

概述

关键改进

默认更快：请求会使用 maxAge（默认 2 天）进行缓存，并启用合理的默认设置，如 blockAds、skipTlsVerification 和 removeBase64Images。
新的摘要格式：现在可以将 "summary" 指定为格式，直接获取页面内容的精炼摘要。
更新的 JSON 提取：JSON 提取和变更追踪现在使用对象格式：{ type: "json", prompt, schema }。旧的 "extract" 格式已重命名为 "json"。
更强大的截图选项：使用对象形式：{ type: "screenshot", fullPage, quality, viewport }。
新的搜索来源：通过设置 sources 参数，除网页结果外，还可在 "news" 和 "images" 中进行搜索。
基于提示的智能爬取：传入自然语言 prompt 进行爬取，系统会自动推导路径/限制。开始任务前，可使用新的 /crawl/params-preview 端点检查推导出的选项。

快速迁移清单

将 v1 客户端用法替换为 v2 客户端：
- JS：const firecrawl = new Firecrawl({ apiKey: 'fc-YOUR-API-KEY' })
- Python：firecrawl = Firecrawl(api_key='fc-YOUR-API-KEY')
- API：改用新的 https://api.firecrawl.dev/v2/ 端点。
更新格式：
- 需要时使用 “summary”
- JSON 模式：进行 JSON 抽取时使用 { type: "json", prompt, schema }
- Screenshot 和 Screenshot@fullPage：指定选项时使用 screenshot 对象格式
在 SDK 中采用标准化的异步流程：
- Crawls：startCrawl + getCrawlStatus（或 crawl 等待器）
- Batch：startBatchScrape + getBatchScrapeStatus（或 batchScrape 等待器）
- Extract：startExtract + getExtractStatus（或 extract 等待器）
爬取选项映射（见下文）
使用 /crawl/params-preview 检查爬取的 prompt

SDK 外观（v2）

JS/TS

方法名变更 (v1 → v2)

Scrape、Search 和 Map

v1 (Firecrawl)	v2 (Firecrawl)
`scrapeUrl(url, ...)`	`scrape(url, options?)`
`search(query, ...)`	`search(query, options?)`
`mapUrl(url, ...)`	`map(url, options?)`

爬取

v1	v2
`crawlUrl(url, ...)`	`crawl(url, options?)` (等待器)
`asyncCrawlUrl(url, ...)`	`startCrawl(url, options?)`
`checkCrawlStatus(id, ...)`	`getCrawlStatus(id)`
`cancelCrawl(id)`	`cancelCrawl(id)`
`checkCrawlErrors(id)`	`getCrawlErrors(id)`

批量抓取

v1	v2
`batchScrapeUrls(urls, ...)`	`batchScrape(urls, opts?)` (等待器)
`asyncBatchScrapeUrls(urls, ...)`	`startBatchScrape(urls, opts?)`
`checkBatchScrapeStatus(id, ...)`	`getBatchScrapeStatus(id)`
`checkBatchScrapeErrors(id)`	`getBatchScrapeErrors(id)`

提取

v1	v2
`extract(urls?, params?)`	`extract(args)`
`asyncExtract(urls, params?)`	`startExtract(args)`
`getExtractStatus(id)`	`getExtractStatus(id)`

其他 / 已移除

v1	v2
`generateLLMsText(...)`	(v2 SDK 中无)
`checkGenerateLLMsTextStatus(id)`	(v2 SDK 中无)
`crawlUrlAndWatch(...)`	`watcher(jobId, options?)`
`batchScrapeUrlsAndWatch(...)`	`watcher(jobId, options?)`

Python（同步）

方法名变更（v1 → v2）

Scrape、Search 和 Map

v1	v2
`scrape_url(...)`	`scrape(...)`
`search(...)`	`search(...)`
`map_url(...)`	`map(...)`

Crawling

v1	v2
`crawl_url(...)`	`crawl(...)`（waiter）
`async_crawl_url(...)`	`start_crawl(...)`
`check_crawl_status(...)`	`get_crawl_status(...)`
`cancel_crawl(...)`	`cancel_crawl(...)`

Batch Scraping

v1	v2
`batch_scrape_urls(...)`	`batch_scrape(...)`（waiter）
`async_batch_scrape_urls(...)`	`start_batch_scrape(...)`
`get_batch_scrape_status(...)`	`get_batch_scrape_status(...)`
`get_batch_scrape_errors(...)`	`get_batch_scrape_errors(...)`

Extraction

v1	v2
`extract(...)`	`extract(...)`
`start_extract(...)`	`start_extract(...)`
`get_extract_status(...)`	`get_extract_status(...)`

其他 / 已移除

v1	v2
`generate_llms_text(...)`	（v2 SDK 中无）
`get_generate_llms_text_status(...)`	（v2 SDK 中无）
`watch_crawl(...)`	`watcher(job_id, ...)`

Python（异步）

AsyncFirecrawl 提供相同的方法（均可 await）。

formats 与抓取选项

基础场景请使用字符串 formats：“markdown”、“html”、“rawHtml”、“links”、“summary”、“images”。
请使用 parsers: [ { "type": "pdf" } | "pdf" ]，而非 parsePDF。
对于 JSON、变更跟踪和截图，请使用对象 formats：

JSON 格式

const formats = [ {
  "type": "json",
  "prompt": "从页面中提取公司使命。"
}];

doc = firecrawl.scrape(url, { formats });

formats = [ { "type": "json", "prompt": "从页面中提取公司使命。" } ];

doc = firecrawl.scrape(url, formats=formats);

curl -X POST https://api.firecrawl.dev/v2/scrape \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer YOUR_API_KEY' \
    -d '{
      "url": "https://docs.firecrawl.dev/",
      "formats": [{
        "type": "json",
        "prompt": "从页面中提取公司使命。"
      }]
    }'

截图格式

// 截图格式（JS）
const formats = [ { "type": "screenshot", "fullPage": true, "quality": 80, "viewport": { "width": 1280, "height": 800 } } ];

doc = firecrawl.scrape(url, { formats });

# 截图格式（Python）
formats = [ { "type": "screenshot", "fullPage": true, "quality": 80, "viewport": { "width": 1280, "height": 800 } } ];
doc = firecrawl.scrape(url, formats=formats);

# 截图格式（cURL）
curl -X POST https://api.firecrawl.dev/v2/scrape \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer YOUR_API_KEY' \
    -d '{
      "url": "https://docs.firecrawl.dev/",
      "formats": [{
        "type": "screenshot",
        "fullPage": true,
        "quality": 80,
        "viewport": { "width": 1280, "height": 800 }
      }]
    }'

爬取选项映射（v1 → v2）

v1	v2
`allowBackwardCrawling`	（已移除）请使用 `crawlEntireDomain`
`maxDepth`	（已移除）请使用 `maxDiscoveryDepth`
`ignoreSitemap` (bool)	`sitemap`（例如：“only”、“skip”或“include”）
(none)	`prompt`

爬取 prompt + 参数预览

查看爬取参数预览示例：

import { Firecrawl } from 'firecrawl';

const firecrawl = new Firecrawl({ apiKey: "fc-YOUR-API-KEY" });

const params = await firecrawl.crawlParamsPreview('https://docs.firecrawl.dev', 'Extract docs and blog');
console.log(params);

from firecrawl import Firecrawl

firecrawl = Firecrawl(api_key='fc-YOUR-API-KEY')
preview = firecrawl.crawl_params_preview(url='https://docs.firecrawl.dev', prompt='Extract docs and blog')
print(preview)

curl -X POST https://api.firecrawl.dev/v2/crawl/params-preview \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer YOUR_API_KEY' \
    -d '{
      "url": "https://docs.firecrawl.dev",
      "prompt": "Extract docs and blog"
    }'

快速开始

Standard 功能

Webhooks

Dashboard

从 v1 迁移到 v2

概述

关键改进

快速迁移清单

SDK 外观（v2）

JS/TS

方法名变更 (v1 → v2)

Python（同步）

方法名变更（v1 → v2）

Python（异步）

formats 与抓取选项

JSON 格式

截图格式

爬取选项映射（v1 → v2）

爬取 prompt + 参数预览

​概述

​关键改进

​快速迁移清单

​SDK 外观（v2）

​JS/TS

​方法名变更 (v1 → v2)

​Python（同步）

​方法名变更（v1 → v2）

​Python（异步）

​formats 与抓取选项

​JSON 格式

​截图格式

​爬取选项映射（v1 → v2）

​爬取 prompt + 参数预览

概述

关键改进

快速迁移清单

SDK 外观（v2）

JS/TS

方法名变更 (v1 → v2)

Python（同步）

方法名变更（v1 → v2）

Python（异步）

formats 与抓取选项

JSON 格式

截图格式

爬取选项映射（v1 → v2）

爬取 prompt + 参数预览