解析 | Firecrawl

解析はドキュメントをクリーンで LLM 対応のデータに変換します。ファイルを /parse にアップロードするか、公開ドキュメントの URL を /scrape に指定すると、Markdown、ページ単位のコンテンツ、型付きレイアウトブロック、または構造化 JSON が返されます。

レイアウトを考慮: 見出し、段落、表、数式を読み取り順序に配置
スキャンにも対応: ネイティブテキストを抽出し、画像のみのページでは OCR にフォールバック
根拠に基づく構造: バウンディングボックスと Markdown 内の文字範囲へのリンクを持つ型付きレイアウトブロック (PDF)
主要な形式に対応: PDF、Word、Excel、PowerPoint、OpenDocument、EPUB、CSV、HTML
ゼロデータ保持をサポート

クイックスタート

from firecrawl import Firecrawl

firecrawl = Firecrawl(api_key="fc-YOUR-API-KEY")

doc = firecrawl.parse("./report.pdf")

print(doc.markdown)

import { Firecrawl } from "firecrawl";
import fs from "node:fs";

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

const doc = await firecrawl.parse({
  data: fs.readFileSync("./report.pdf"),
  filename: "report.pdf",
});

console.log(doc.markdown);

curl -X POST https://api.firecrawl.dev/v2/parse \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -F 'file=@./report.pdf' \
  -F 'options={"formats":["markdown"]};type=application/json'

ファイルの代わりに公開ドキュメントURLをお持ちですか？/scrape はファイル形式を検出し、同じオプションと出力で同様に解析します： firecrawl.scrape("https://example.com/report.pdf")。

レスポンス

SDK ではドキュメントオブジェクトが直接返されます。cURL では JSON ペイロードが返されます。

{
  "success": true,
  "data": {
    "markdown": "# Annual Report\n\n...",
    "metadata": {
      "title": "Annual Report",
      "numPages": 42,
      "totalPages": 42,
      "sourceFile": "report.pdf"
    }
  }
}

numPages は実際に解析されたページ数で、totalPages はドキュメントの実際の総ページ数です。maxPages によって結果が切り詰められた場合を除き、両者は一致します。たとえば、 100 ページの PDF を maxPages: 10 で解析すると、numPages: 10 と totalPages: 100 が返されるため、 totalPages > numPages で出力が切り詰められたことがわかります。ページ数を判定できない場合、 totalPages は省略されます。

ドキュメントの Markdown に加え、単一の Markdown string では不十分なケースに対応する 3 つの出力があります。PDF ドキュメント向けのページごとの Markdown とレイアウトブロック、およびすべての形式向けの構造化 JSON です。Markdown 自体の内部でページの帰属情報だけが必要な場合は、ページマーカーがページ区切りをその場で注釈付けします。

ページごとのMarkdown (PDF)

PDFパーサーでpages: trueを設定すると、ドキュメントには各物理ページのMarkdownを含むpages配列も含まれます。コンテンツの出所ページを確認したり、ページを個別に処理したりする場合に便利です。追加コストはかかりません。

from firecrawl import Firecrawl
from firecrawl.v2.types import ScrapeOptions

firecrawl = Firecrawl(api_key="fc-YOUR-API-KEY")

doc = firecrawl.parse(
    "./report.pdf",
    options=ScrapeOptions(parsers=[{"type": "pdf", "pages": True}]),
)

for page in doc.pages:
    print(page.page_number, page.markdown[:80])

import { Firecrawl } from "firecrawl";
import fs from "node:fs";

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

const doc = await firecrawl.parse(
  { data: fs.readFileSync("./report.pdf"), filename: "report.pdf" },
  { parsers: [{ type: "pdf", pages: true }] },
);

for (const page of doc.pages) {
  console.log(page.pageNumber, page.markdown.slice(0, 80));
}

curl -X POST https://api.firecrawl.dev/v2/parse \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -F 'file=@./report.pdf' \
  -F 'options={"parsers":[{"type":"pdf","pages":true}]};type=application/json'

"pages": [
  { "pageNumber": 1, "markdown": "# Annual Report\n\n..." },
  { "pageNumber": 2, "markdown": "..." }
]

ページマーカー (PDF)

PDF パーサーで pageMarkers: true を設定すると、ドキュメントの markdown 内の各ページが、後続する物理ページを示す HTML コメントマーカーで連結されます。

...1ページ目の終わり

---

<!-- page 2 -->

2ページ目の始まり...

新しいレスポンスフィールドはありません。マーカーは markdown 内に含まれるため、 markdown の string のみを処理する下流のパイプラインでも、ページごとの帰属情報を保持できます。markdown をレンダリングするとコメントは非表示になり、 (、1始まり) で簡単に分割できます。追加コストはかかりません。

from firecrawl import Firecrawl
from firecrawl.v2.types import ScrapeOptions

firecrawl = Firecrawl(api_key="fc-YOUR-API-KEY")

doc = firecrawl.parse(
    "./report.pdf",
    options=ScrapeOptions(parsers=[{"type": "pdf", "page_markers": True}]),
)

print(doc.markdown)
# ...1ページ目の終わり
#
# ---
#
# <!-- 2ページ目 -->
#
# 2ページ目の始まり...

import { Firecrawl } from "firecrawl";
import fs from "node:fs";

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

const doc = await firecrawl.parse(
  { data: fs.readFileSync("./report.pdf"), filename: "report.pdf" },
  { parsers: [{ type: "pdf", pageMarkers: true }] },
);

console.log(doc.markdown);
// ...1ページ目の終わり
//
// ---
//
// <!-- page 2 -->
//
// 2ページ目の始まり...

curl -X POST https://api.firecrawl.dev/v2/parse \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -F 'file=@./report.pdf' \
  -F 'options={"parsers":[{"type":"pdf","pageMarkers":true}]};type=application/json'

マーカーはページの間にのみ表示され、ページ 1 の先頭にはありません。パーサーが改ページをまたぐ content を結合すると、ページ番号が飛ぶことがあります (次のページにまたがる表や文には、マークする境界がありません) 。物理ページごとに分ける必要がある場合は、pages: true を使用してください。 2 つのオプションは併用できます。

レイアウトブロック (PDF)

PDF パーサーで blocks: true を設定すると、ドキュメントには blocks 配列も含まれます。各ページで解析エンジンが検出した、型付きレイアウトブロックのジオメトリ情報と出所情報を格納しています。これは markdown に対応する構造化データであり、引用の根拠付け、ハイライトのオーバーレイ、ドキュメントの内容の監査に使用できます。追加コストはかかりません。

解析済み PDF ページ。検出された各レイアウトブロック（タイトル、テキスト、セクションヘッダー、表、図、キャプション、ページフッター、ページ番号）に色付きのバウンディングボックスが重ねて表示されています — エンジンが検出したすべてのブロックを、型と位置情報付きで表示します。markdown になる領域と同じです。

from firecrawl import Firecrawl
from firecrawl.v2.types import ScrapeOptions

firecrawl = Firecrawl(api_key="fc-YOUR-API-KEY")

doc = firecrawl.parse(
    "./report.pdf",
    options=ScrapeOptions(parsers=[{"type": "pdf", "blocks": True}]),
)

for page in doc.blocks:
    for block in page.items:
        print(page.page_number, block.type, block.bbox)

import { Firecrawl } from "firecrawl";
import fs from "node:fs";

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

const doc = await firecrawl.parse(
  { data: fs.readFileSync("./report.pdf"), filename: "report.pdf" },
  { parsers: [{ type: "pdf", blocks: true }] },
);

for (const page of doc.blocks) {
  for (const block of page.items) {
    console.log(page.pageNumber, block.type, block.bbox);
  }
}

curl -X POST https://api.firecrawl.dev/v2/parse \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -F 'file=@./report.pdf' \
  -F 'options={"parsers":[{"type":"pdf","blocks":true}]};type=application/json'

"blocks": [
  {
    "pageNumber": 1,
    "width": 1700,
    "height": 2200,
    "status": "ok",
    "items": [
      {
        "id": "p1.b0",
        "type": "title",
        "label": "doc_title",
        "bbox": [0.118, 0.054, 0.882, 0.092],
        "content": "# Annual Report",
        "markdownSpan": [0, 15],
        "readingOrder": 0,
        "source": "native_text",
        "confidence": { "layout": 0.97, "ocr": null }
      }
    ]
  }
]

ブロックフィールド

フィールド	説明
`id`	レスポンス内で一意かつ安定した 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`) 。
`confidence`	`layout` の検出スコア (0～1) と、ソースで提供される場合の `ocr` テキスト信頼度。その他の場合は `null`。独自に算出した集約値は使用しません。

根拠付け: 回答からページへ

markdownSpan は、各ブロックを、そのブロックが生成した markdown 内の正確な部分文字列に紐付けます。これにより、引用の根拠付けは推論ではなく検索で行えます。markdown 内で引用テキストを探し、そのオフセットをカバーする span を持つブロックを見つければ、言語モデルに座標を問い合わせることなく、ページ番号とバウンディングボックスを取得できます。

def ground(doc, quote: str):
    start = doc["markdown"].find(quote)
    for page in doc["blocks"]:
        for block in page["items"]:
            span = block["markdownSpan"]
            if span and span[0] <= start < span[1]:
                return page["pageNumber"], block["bbox"]

function ground(doc, quote) {
  const start = doc.markdown.indexOf(quote);
  for (const page of doc.blocks) {
    for (const block of page.items) {
      const span = block.markdownSpan;
      if (span && span[0] <= start && start < span[1]) {
        return { pageNumber: page.pageNumber, bbox: block.bbox };
      }
    }
  }
}

構造化JSON出力

ドキュメントから構造化データを直接抽出するには、JSONスキーマまたはプロンプトを指定します。

from firecrawl import Firecrawl
from firecrawl.v2.types import ScrapeOptions
from pydantic import BaseModel

firecrawl = Firecrawl(api_key="fc-YOUR-API-KEY")

class Invoice(BaseModel):
    vendor: str
    total: float

doc = firecrawl.parse(
    "./invoice.pdf",
    options=ScrapeOptions(formats=[{
        "type": "json",
        "schema": Invoice.model_json_schema(),
    }]),
)

print(doc.json)

import { Firecrawl } from "firecrawl";
import fs from "node:fs";
import { z } from "zod";

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

const schema = z.object({
  vendor: z.string(),
  total: z.number(),
});

const doc = await firecrawl.parse(
  { data: fs.readFileSync("./invoice.pdf"), filename: "invoice.pdf" },
  { formats: [{ type: "json", schema }] },
);

console.log(doc.json);

curl -X POST https://api.firecrawl.dev/v2/parse \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -F 'file=@./invoice.pdf' \
  -F 'options={"formats":[{"type":"json","schema":{"type":"object","properties":{"total":{"type":"number"},"vendor":{"type":"string"}}}}]};type=application/json'

PDF オプション

PDF のすべての動作は、/parse と /scrape の両方で parsers オプションにより制御されます。

{
  "parsers": [
    {
      "type": "pdf",
      "mode": "auto",
      "maxPages": 100,
      "pages": true,
      "blocks": true,
      "pageMarkers": true
    }
  ]
}

プロパティ	型	デフォルト	説明
`type`	`"pdf"`	(必須)	パーサーの種類。
`mode`	`"fast" \| "auto" \| "ocr"`	`"auto"`	解析方法。詳細は以下を参照。
`maxPages`	`integer`	—	解析するページ数の上限。
`pages`	`boolean`	`false`	ページごとのMarkdownも返します。追加コストはかかりません。
`blocks`	`boolean`	`false`	バウンディングボックス付きのレイアウトブロックも返します。追加コストはかかりません。
`pageMarkers`	`boolean`	`false`	ドキュメントのMarkdown内の改ページに、`<!-- page N -->` マーカーを付加します。追加コストはかかりません。

parsers: [] を渡すと解析を完全にスキップし、PDFをbase64形式で返します (固定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 はスクレイピングのオプションの一部を受け付けます。

formats: 出力フォーマットの配列。デフォルトは ["markdown"]。対応フォーマット: markdown、html、rawHtml、links、images、summary、json (スキーマまたはプロンプト付き) 。
onlyMainContent: ドキュメントのメインコンテンツのみを返します。デフォルトは true。
includeTags / excludeTags: タグ単位での含める/除外の指定 (HTML 入力) 。
redactPII: 返される markdown から個人を特定できる情報をマスキングします。
timeout: リクエストのタイムアウト (ミリ秒) 。デフォルトは 30000、最大 300000。
parsers: ファイルパーサーの制御 — PDF オプションを参照してください。

/parse は、actions、waitFor、location、mobile、change tracking などのブラウザ専用オプションには対応していません。

MCP 経由で Firecrawl を使用していますか？ ローカルファイルには firecrawl_parse を使用してください。FIRECRAWL_API_URL を設定すると、ローカル MCP はファイルを直接読み取れます。リモートホスト型 MCP は、最初に短期間有効なアップロードコマンドを返し、その後、返された uploadRef を解析します。公開ドキュメントの URL には引き続き /scrape を使用してください。

考慮事項

1 リクエストあたりの最大ファイルサイズは 50 MB です。
PDF の解析は 1 ページあたり 1 クレジット です。pages、blocks、pageMarkers のオプションに追加コストはかかりません。
ocr モードで非常に大きい PDF やスキャンされた PDF を解析する場合、時間がかかることがあります。timeout を長めに設定するか、maxPages を使って処理範囲を制限してください。
複数ファイルを扱う場合は、各ファイルに対して /parse を並列に呼び出してください。バッチアップロード用のバリアントはありません。

Firecrawl APIキーが必要な AIエージェントですか？自動オンボーディング手順については、firecrawl.dev/agent-onboarding/SKILL.md を参照してください。

はじめに

主要エンドポイント

その他

クイックスタート

開発者ガイド

webhook

ユースケース

その他

貢献

解析

クイックスタート

レスポンス

ページごとのMarkdown (PDF)

ページマーカー (PDF)

レイアウトブロック (PDF)

ブロックフィールド

根拠付け: 回答からページへ

構造化JSON出力

PDF オプション

解析モード

対応フォーマット

リクエストリファレンス

考慮事項

​クイックスタート

​レスポンス

​ページごとのMarkdown (PDF)

​ページマーカー (PDF)

​レイアウトブロック (PDF)

​ブロックフィールド

​根拠付け: 回答からページへ

​構造化JSON出力

​PDF オプション

​解析モード

​対応フォーマット

​リクエストリファレンス

​考慮事項

クイックスタート

レスポンス

ページごとのMarkdown (PDF)

ページマーカー (PDF)

レイアウトブロック (PDF)

ブロックフィールド

根拠付け: 回答からページへ

構造化JSON出力

PDF オプション

解析モード

対応フォーマット

リクエストリファレンス

考慮事項