Skip to main content
Firecrawl Docs

解析

将 PDF、Word、Excel、PowerPoint 等文档转换为整洁的 Markdown、逐页内容、布局块和结构化 JSON
3 min read

解析可将文档转换为整洁、可供 LLM 使用的数据。将文件上传至 /parse，或使用 /scrape 抓取公开文档 URL，即可获取 Markdown、逐页内容、逐页类型化布局块或结构化 JSON。

  • 感知布局：按阅读顺序组织标题、段落、表格和公式
  • 支持扫描件：原生文本提取，并为纯图像页面提供 OCR 回退方案
  • 结构可追溯：逐页类型化布局块，包含边界框以及指向 Markdown 中字符范围的链接 (PDF)
  • 支持常见格式：PDF、Word、Excel、PowerPoint、OpenDocument、EPUB、CSV、HTML
  • 支持 零数据保留

快速入门#

Note

如果您有公开文档 URL而非文件，/scrape 会自动检测文件类型并以相同方式解析——选项和输出均相同： firecrawl.scrape("https://example.com/report.pdf")。

响应#

SDK 直接返回文档对象。cURL 返回 JSON 数据。

Note

numPages 是实际解析的页数；totalPages 是文档的 实际总页数。除非 maxPages 截断了结果，否则两者会一致——例如，解析 一个 100 页的 PDF 并设置 maxPages: 10 时，会返回 numPages: 10 和 totalPages: 100，因此 totalPages > numPages 表示输出已被截断。无法确定页数时， 则会省略 totalPages。

除文档 markdown 外，还有三种输出可满足单个 markdown 字符串无法满足的需求：适用于 PDF 文档的按物理页划分的 Markdown和 布局块，以及适用于所有格式的 结构化 JSON。如果只需要 markdown 本身中的 页面归属信息，页面标记会直接标注分页位置。

按物理页划分的 Markdown (PDF)#

在 PDF 解析器中设置 pages: true 后，文档还会包含一个 pages 数组，其中包含按实际页面划分的 markdown——当您需要确认内容来自哪一页，或需要独立处理各页面时非常有用。 无需额外成本。

页面标记 (PDF)#

在 PDF 解析器 中设置 pageMarkers: true 后，文档 markdown 中的页面会通过 HTML 注释标记连接，该标记会注明后续物理页面的页码：

不会新增响应字段——标记嵌入在 Markdown 中，因此任何只处理 Markdown 字符串的下游流水线都能保留按页归属信息。渲染 Markdown 时，这些注释不可见，并且可轻松按 (<!-- page N -->，从 1 开始计数) 拆分。无需额外成本。

Note

标记仅出现在页面之间——第 1 页前不会有标记。 当解析器合并跨页内容时，编号可能会跳过某一页 (延续到下一页的表格或句子没有可标记的边界) 。如果需要将每个物理页面单独处理，请使用 pages: true；这两个选项可组合使用。

布局块 (PDF)#

在 PDF 解析器中设置 blocks: true 后，文档还会 包含一个 blocks 数组：其中按页提供解析引擎检测到的逐页类型化布局块， 以及其几何信息和来源信息。这是 markdown 的结构化对应形式——可用于引用溯源、 高亮叠加层，或审计文档内容。无需额外成本。

已解析的 PDF 页面，每个检测到的布局块上均叠加了彩色边界框：标题、文本、章节标题、表格、图形、说明文字、页脚和页码
引擎检测到的每个封禁均标注了类型和位置——与生成 markdown 的区域相同。

封禁字段#

字段描述
id在同一响应中保持稳定：p<page>.b<index in reading order>。
type封禁类型：title、section_header、text、table、formula、figure、caption、page_number、page_header、page_footer。未来可能会新增类型。
label原始布局模型标签，为实现前向兼容而直接透传。
bbox相对于页面归一化到 0–1 的 [x0, y0, x1, y1]。乘以 width/height 可得到像素坐标。页面尺寸未知时为 null。
content此封禁生成的 Markdown 片段。
markdownSpan文档 markdown 中对应此封禁片段的 [start, end) 字符偏移量。后处理重写该片段时为 null。
readingOrder在检测到的阅读顺序中的位置。
source生成该封禁的流水线路径 (例如 native_text、layout_ocr、tsr、formula_model) 。
confidencelayout 检测分数 (0–1) ，以及来源提供时的 ocr 文本置信度；否则为 null——绝不使用虚构的聚合值。

溯源：从答案回溯到页面#

markdownSpan 将每个封禁关联到其生成的 markdown 中对应的精确子字符串。这让引用溯源成为查找而非推断：在 markdown 中找到引用的文本，再找到 span 覆盖该偏移位置的封禁，即可获得页码和边界框——完全无需向语言模型查询坐标。

结构化 JSON 输出#

传入 JSON schema 或 prompt，即可直接从文档中提取结构化数据：

PDF 选项#

所有 PDF 相关行为均通过 parsers 选项控制，/parse 和 /scrape 均适用：

属性类型默认值描述
type"pdf"(必填)解析器类型。
mode"fast" | "auto" | "ocr""auto"解析策略——详见下文。
maxPagesinteger—限制解析的页数。
pagesbooleanfalse同时返回按页划分的 Markdown。无需额外成本。
blocksbooleanfalse同时返回带边界框的布局块。无需额外成本。
pageMarkersbooleanfalse使用 <!-- page N --> 标记在文档 Markdown 中标注分页。无需额外成本。

传入 parsers: [] 将完全跳过解析，并以 base64 格式返回 PDF (固定消耗 1 个额度) 。

解析模式#

模式描述
auto优先尝试快速的文本提取；当页面需要时回退到 OCR。这是默认值。
fast仅进行文本提取 (嵌入文本) 。这是最快的选项，但对于扫描页或纯图像页面会直接失败，而不会悄悄返回空结果。
ocr强制对每一页执行 OCR。适用于扫描文档，或 auto 错误分类页面时。

支持的格式#

扩展名： .html, .htm, .xhtml, .pdf, .docx, .doc, .docm, .odt, .ods, .odp, .rtf, .xlsx, .xls, .xlsm, .xlsb, .pptx, .ppt, .pptm, .epub, .csv.

请参见Document Parsing，了解各格式的 转换方式。

请求参考#

请求采用 multipart/form-data，其中包含必填的 file 部分和可选的 options JSON 部分。options 接受部分 scrape 选项：

  • formats：输出格式数组。默认值为 ["markdown"]。支持：markdown、html、rawHtml、links、images、summary 和 json (可搭配 schema 或 prompt) 。
  • onlyMainContent：仅返回文档的主体内容。默认值为 true。
  • includeTags / excludeTags：按标签包含或排除内容 (适用于 HTML 输入) 。
  • redactPII：对返回的 markdown 中的个人身份识别信息进行脱敏处理。
  • timeout：请求超时时间 (毫秒) 。默认值为 30000，最大为 300000。
  • parsers：文件解析器控制选项 — 请参见 PDF 选项。
Note

/parse 不支持仅适用于浏览器的选项，例如 actions、waitFor、location、mobile 或变更追踪。

Tip

通过 MCP 使用 Firecrawl？ 对于本地文件，请使用 firecrawl_parse。配置 FIRECRAWL_API_URL 后，本地 MCP 可以直接读取文件。远程托管 MCP 会先返回一个短期有效的上传命令，然后解析返回的 uploadRef。公开文档 URL 仍应使用 /scrape。

注意事项#

  • 每个请求的最大文件大小为 50 MB。
  • PDF 解析按每页 1 个额度计费；pages、blocks 和 pageMarkers 选项不产生额外成本。
  • 在 ocr 模式下解析超大 PDF 或扫描版 PDF 可能需要更长时间——请增大 timeout，或使用 maxPages 来限定处理范围。
  • 对于多份文件，请对每个文件并行调用 /parse；不支持批量上传。

你是需要 Firecrawl API 密钥的 AI 代理吗？请参见 firecrawl.dev/agent-onboarding/SKILL.md 获取自动化引导说明。

交互Map