v2 API 变更： v2 已完全支持 JSON schema 抽取，但 API 格式有所调整。在 v2 中，schema 直接嵌入到 formats 对象中，写法为 formats: [{type: "json", schema: {...}}]。v1 的 jsonOptions 参数在 v2 中已被移除。
-
设置 Schema（可选）：
定义一个 JSON Schema（采用 OpenAI 的格式）来明确所需数据；如果不需要严格的 Schema，也可仅提供一个
prompt，并附上网页 URL。
-
发起请求：
使用 JSON 模式将你的 URL 和 Schema 发送到我们的 /scrape 端点。查看方法：
Scrape Endpoint Documentation
-
获取数据：
返回与你的 Schema 匹配的干净、结构化数据，可直接使用。
这使你能快速、轻松地按所需 formats 获取网页数据。
用于从抓取的页面中提取结构化数据。
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)
{
"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 会自行确定数据结构。
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)
{
"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/"
},
}
}
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()
}]
)
print(result)
{
"success": true,
"data": {
"json": {
"company_mission": "将网站转换为 LLM 可用数据",
"supports_sso": true,
"is_open_source": true,
"is_in_yc": true
}
}
}
formats 中直接包含一个内嵌 schema 的对象：
formats: [{ type: 'json', schema: { ... }, prompt: '...' }]
参数：
schema: 描述所需结构化输出的 JSON Schema（基于 schema 的提取为必填）。prompt: 可选提示，用于引导提取（也用于无 schema 的提取）。
重要说明： 与 v1 不同，v2 中没有单独的 jsonOptions 参数。schema 必须直接包含在 formats 数组中的 format 对象内。
JSON 提取中不支持 HTML 属性。 JSON 提取是基于页面的 Markdown 转换结果工作的，该转换只保留可见文本内容。HTML 属性（例如 data-id、元素上的自定义属性）会在转换过程中被去除，大语言模型无法看到这些属性。如果你需要提取 HTML 属性值，请使用 rawHtml format 并在客户端解析属性，或者使用 executeJavascript 动作为在提取前将属性值注入到可见文本中。
- 让提示词简短且聚焦。 带有大量规则的长提示会增加结果的不确定性。将具体约束（如允许值）移入 schema 本身。
- 使用简洁的属性名。 避免在属性名中嵌入说明或枚举列表。用类似
"installation_type" 这样的简短键名，并把允许值放在 enum 数组中。
- 为受限字段添加
enum 数组。 当某个字段只有固定取值时，将它们列在 enum 中，并确保与页面上显示的文本完全匹配。
- 在字段描述中包含 null 处理逻辑。 在每个字段的
description 中添加 "Return null if not found on the page."，以避免模型猜测缺失值。
- 添加位置信息提示。 告诉模型在页面上哪里查找数据，例如
"Flow rate in GPM from the Specifications table."。
- 将大型 schema 拆分成多个请求。 字段很多（例如 30+）的 schema 通常会产生更不稳定的结果。将其拆成 2–3 个请求，每个请求包含 10–15 个字段。
结构良好的 schema 示例：
{
"type": "object",
"properties": {
"product_name": {
"type": ["string", "null"],
"description": "Full descriptive product name as shown on the page. Return null if not found."
},
"installation_type": {
"type": ["string", "null"],
"description": "Installation type from the Specifications section. Return null if not found.",
"enum": ["Deck-mount", "Wall-mount", "Countertop", "Drop-in", "Undermount"]
},
"flow_rate_gpm": {
"type": ["string", "null"],
"description": "Flow rate in GPM from the Specifications section. Return null if not found."
}
}
}
