Parse

Parse convertit les documents en données propres, prêtes pour les LLM. Importez un fichier via /parse — ou utilisez /scrape avec l’URL d’un document public — et obtenez du markdown, du contenu par page, des blocs de mise en page typés ou du JSON structuré.

Respect de la mise en page : titres, paragraphes, tableaux et formules assemblés dans l’ordre de lecture
Documents numérisés pris en charge : extraction de texte natif avec OCR comme solution de repli pour les pages ne contenant que des images
Structure ancrée dans le document : blocs de mise en page typés avec boîtes englobantes et liens vers des plages de caractères du markdown (PDF)
Tous les formats courants : PDF, Word, Excel, PowerPoint, OpenDocument, EPUB, CSV, HTML
Prise en charge de Zero Data Retention

Démarrage rapide

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'

Vous avez une URL publique vers un document plutôt qu’un fichier ? /scrape détecte le type de fichier et l’analyse de la même façon — mêmes options, même résultat : firecrawl.scrape("https://example.com/report.pdf").

Réponse

Les SDK renvoient directement l’objet document. cURL renvoie le payload JSON.

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

numPages est le nombre de pages réellement analysées ; totalPages correspond au nombre réel de pages du document. Ils correspondent sauf si maxPages a tronqué le résultat — p. ex. l’analyse d’un PDF de 100 pages avec maxPages: 10 renvoie numPages: 10 et totalPages: 100, donc totalPages > numPages indique que la sortie a été tronquée. totalPages est omis lorsque le nombre de pages ne peut pas être déterminé.

Au-delà du markdown du document, trois sorties couvrent les cas où une seule chaîne markdown ne suffit pas : le markdown par page et les blocs de mise en page pour les documents PDF, et le JSON structuré pour tous les formats.

Markdown par page (PDF)

Activez pages: true dans l’analyseur PDF pour que le document contienne également un tableau pages avec le markdown de chaque page — utile pour savoir de quelle page provient le contenu ou pour traiter les pages indépendamment. Sans coût supplémentaire.

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

firecrawl = Firecrawl(api_key="fc-VOTRE-CLÉ-API")

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-VOTRE-CLÉ-API" });

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 VOTRE_CLÉ_API' \
  -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": "..." }
]

Blocs de mise en page (PDF)

Définissez blocks: true dans l’analyseur PDF ; le document contient alors également un tableau blocks : pour chaque page, les blocs de mise en page typés détectés par le moteur d’analyse, avec leur géométrie et leur provenance. Il s’agit du pendant structuré du markdown : utilisez-le pour l’ancrage des citations, superposer des surlignages ou auditer le contenu d’un document. Sans coût supplémentaire.

Une page PDF analysée avec des boîtes englobantes colorées superposées sur chaque bloc de mise en page détecté : titre, texte, en-têtes de section, tableau, figure, légende, pied de page et numéro de page — Chaque bloc détecté par le moteur, typé et positionné — les mêmes régions qui deviennent du markdown.

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

firecrawl = Firecrawl(api_key="fc-VOTRE-CLÉ-API")

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 VOTRE_CLÉ_API' \
  -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 }
      }
    ]
  }
]

Champs de bloc

Champ	Description
`id`	Stable au sein d’une réponse : `p<page>.b<index in reading order>`.
`type`	Type de bloc : `title`, `section_header`, `text`, `table`, `formula`, `figure`, `caption`, `page_number`, `page_header`, `page_footer`. De nouveaux types peuvent apparaître au fil du temps.
`label`	Étiquette brute du modèle de mise en page, transmise telle quelle pour assurer la compatibilité ascendante.
`bbox`	`[x0, y0, x1, y1]` normalisé entre 0 et 1 par rapport à la page. Multipliez par `width`/`height` pour obtenir les coordonnées en pixels. `null` lorsque les dimensions de la page sont inconnues.
`content`	Fragment Markdown apporté par ce bloc.
`markdownSpan`	Décalages de caractères `[start, end)` dans le `markdown` du document correspondant au fragment de ce bloc. `null` lorsque le post-traitement a réécrit le fragment.
`readingOrder`	Position dans l’ordre de lecture détecté.
`source`	Chemin du pipeline ayant produit le bloc (p. ex. `native_text`, `layout_ocr`, `tsr`, `formula_model`).
`confidence`	Score de détection `layout` (0–1) et niveau de confiance du texte `ocr` lorsque la source en fournit un ; `null` sinon — jamais une agrégation inventée.

Ancrage : d’une réponse à la page

markdownSpan lie chaque bloc à la sous-chaîne exacte du markdown qu’il a produit. L’ancrage des citations relève donc d’une recherche, et non d’une inférence : trouvez le texte cité dans le markdown, puis le bloc dont la plage couvre ce décalage, et vous obtenez le numéro de page et la boîte englobante — sans jamais demander de coordonnées à un modèle de langage.

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 };
      }
    }
  }
}

Sortie JSON structurée

Fournissez un schéma JSON ou un prompt pour extraire des données structurées directement du document :

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-VOTRE-CLÉ-API" });

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 VOTRE_CLÉ_API' \
  -F 'file=@./invoice.pdf' \
  -F 'options={"formats":[{"type":"json","schema":{"type":"object","properties":{"total":{"type":"number"},"vendor":{"type":"string"}}}}]};type=application/json'

Options pour les PDF

Le comportement des PDF est entièrement contrôlé par l’option parsers, aussi bien pour /parse que pour /scrape :

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

Propriété	Type	Par défaut	Description
`type`	`"pdf"`	(obligatoire)	Type d’analyseur.
`mode`	`"fast" \| "auto" \| "ocr"`	`"auto"`	Stratégie d’analyse — voir ci-dessous.
`maxPages`	`integer`	—	Limite le nombre de pages à analyser.
`pages`	`boolean`	`false`	Renvoie également le Markdown par page. Aucun coût supplémentaire.
`blocks`	`boolean`	`false`	Renvoie également les blocs de mise en page avec leurs boîtes englobantes. Aucun coût supplémentaire.

Passer parsers: [] désactive entièrement l’analyse et renvoie le PDF en base64 (1 crédit forfaitaire).

Modes d’analyse

Mode	Description
`auto`	Tente d’abord une extraction rapide basée sur le texte, puis bascule vers l’OCR lorsqu’une page le nécessite. C’est le mode par défaut.
`fast`	Extraction basée uniquement sur le texte (texte intégré). Option la plus rapide, mais échoue sur les pages numérisées ou ne contenant que des images, plutôt que de ne rien renvoyer silencieusement.
`ocr`	Force l’OCR sur chaque page. À utiliser pour les documents numérisés ou lorsque `auto` classe mal une page.

Formats pris en charge

Extensions : .html, .htm, .xhtml, .pdf, .docx, .doc, .docm, .odt, .ods, .odp, .rtf, .xlsx, .xls, .xlsm, .xlsb, .pptx, .ppt, .pptm, .epub, .csv. Voir Document Parsing pour savoir comment chaque format est converti.

Référence de la requête

La requête est au format multipart/form-data avec une partie file obligatoire et une partie JSON options facultative. options accepte un sous-ensemble des options de scrape :

formats : tableau de formats de sortie. Valeur par défaut : ["markdown"]. Pris en charge : markdown, html, rawHtml, links, images, summary et json (avec un schéma ou un prompt).
onlyMainContent : renvoie uniquement le contenu principal du document. Valeur par défaut : true.
includeTags / excludeTags : inclusion ou exclusion au niveau des balises (éléments HTML).
redactPII : masque les informations personnelles identifiables dans le markdown renvoyé.
timeout : délai d’expiration de la requête en millisecondes. Valeur par défaut : 30000, maximum 300000.
parsers : paramètres du parseur de fichiers — consultez les options PDF.

/parse ne prend pas en charge les options réservées au navigateur comme actions, waitFor, location, mobile ou le suivi des modifications.

Vous utilisez Firecrawl via MCP ? Utilisez firecrawl_parse pour les fichiers locaux. Le MCP local peut lire directement le fichier lorsqu’il est configuré avec FIRECRAWL_API_URL. Le MCP hébergé à distance renvoie d’abord une commande de téléversement à durée de vie limitée, puis analyse l’uploadRef renvoyé. Les URL de documents publics doivent toujours utiliser /scrape.

Considérations

La taille maximale de fichier est de 50 MB par requête.
L’analyse de PDF est facturée à 1 crédit par page ; les options pages et blocks n’entraînent aucun coût supplémentaire.
L’analyse de PDF très volumineux ou numérisés en mode ocr peut prendre plus de temps — augmentez timeout ou utilisez maxPages pour limiter le traitement.
Pour des lots de fichiers, appelez /parse pour chaque fichier en parallèle ; il n’existe pas d’option de téléversement par lot.

Êtes-vous un agent IA qui a besoin d’une clé API Firecrawl ? Consultez firecrawl.dev/agent-onboarding/SKILL.md pour obtenir des instructions d’intégration automatisée.

Prise en main

Points de terminaison de base

Plus

Démarrages rapides

Guides développeur

Webhooks

Cas d'utilisation

Autres

Contribuer

Démarrage rapide

Réponse

Markdown par page (PDF)

Blocs de mise en page (PDF)

Champs de bloc

Ancrage : d’une réponse à la page

Sortie JSON structurée

Options pour les PDF

Modes d’analyse

Formats pris en charge

Référence de la requête

Considérations

​Démarrage rapide

​Réponse

​Markdown par page (PDF)

​Blocs de mise en page (PDF)

​Champs de bloc

​Ancrage : d’une réponse à la page

​Sortie JSON structurée

​Options pour les PDF

​Modes d’analyse

​Formats pris en charge

​Référence de la requête

​Considérations

Démarrage rapide

Réponse

Markdown par page (PDF)

Blocs de mise en page (PDF)

Champs de bloc

Ancrage : d’une réponse à la page

Sortie JSON structurée

Options pour les PDF

Modes d’analyse

Formats pris en charge

Référence de la requête

Considérations