Procesar

Procesar convierte documentos en datos limpios y listos para LLM. Sube un archivo a /parse — o apunta /scrape a la URL de un documento público — y obtén markdown, contenido por página, bloques de diseño tipados o JSON estructurado.

Con reconocimiento del diseño: encabezados, párrafos, tablas y fórmulas organizados en orden de lectura
Incluye documentos escaneados: extracción de texto nativo con OCR como alternativa para páginas que solo contienen imágenes
Estructura basada en el documento: bloques de diseño tipados con cuadros delimitadores y enlaces a rangos de caracteres en el markdown (PDF)
Cualquier formato habitual: PDF, Word, Excel, PowerPoint, OpenDocument, EPUB, CSV, HTML
Compatible con retención de datos cero

¿No sabes si necesitas Procesar o Scrape? Aquí repasamos las diferencias:

Inicio rápido

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'

¿Tienes una URL pública de un documento en lugar de un archivo? /scrape detecta el tipo de archivo y lo procesa de forma idéntica — mismas opciones, misma salida: firecrawl.scrape("https://example.com/report.pdf").

Respuesta

Los SDK devuelven el objeto de documento directamente. cURL devuelve la carga útil en JSON.

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

numPages es el número de páginas realmente procesadas; totalPages es el número real de páginas del documento. Coinciden a menos que maxPages haya truncado el resultado; p. ej., procesar un PDF de 100 páginas con maxPages: 10 devuelve numPages: 10 y totalPages: 100, por lo que totalPages > numPages indica que la salida se truncó. totalPages se omite cuando no se puede determinar el número de páginas.

Además del markdown del documento, tres salidas cubren los casos en los que una sola cadena de markdown no es suficiente: Markdown físico por página y bloques de diseño para documentos PDF, y JSON estructurado para todos los formatos. Y cuando todo lo que necesitas es la atribución de páginas dentro del propio markdown, marcadores de página señalan los saltos de página directamente en el texto.

Markdown físico por página (PDF)

Establece pages: true en el parser de PDF y el documento también incluye un array pages con el markdown de cada página física, útil cuando necesitas saber de qué página proviene el contenido o procesar las páginas de forma independiente. Sin costo adicional.

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": "..." }
]

Marcadores de página (PDF)

Configura pageMarkers: true en el procesador de PDF y las páginas del propio documento markdown se separarán con un marcador de comentario HTML que indica la página física siguiente:

...fin de la página 1

---

<!-- page 2 -->

inicio de la página 2...

No hay ningún campo de respuesta nuevo: los marcadores se incluyen en el markdown, por lo que cualquier pipeline posterior que solo gestione una cadena de markdown conserva la atribución por página. Los comentarios son invisibles al renderizar el markdown y fáciles de separar (, con índice inicial 1). Sin costo adicional.

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)
# ...fin de la página 1
#
# ---
#
# <!-- página 2 -->
#
# inicio de la página 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);
// ...fin de la página 1
//
// ---
//
// <!-- página 2 -->
//
// inicio de la página 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'

Los marcadores aparecen solo entre páginas: no hay un marcador inicial para la página 1. La numeración puede omitir una página cuando el parser fusiona contenido a través de un salto de página (una tabla u oración que continúa en la página siguiente no deja ningún límite que marcar). Usa pages: true cuando necesites cada página física por separado; las dos opciones se pueden combinar.

Bloques de diseño (PDF)

Establece blocks: true en el parser de PDF y el documento también incluye un array blocks: para cada página, los bloques de diseño tipados que detectó el motor de procesamiento, con geometría y procedencia. Es la contraparte estructurada del markdown: úsala para la fundamentación de citas, superposiciones de resaltado o auditar el contenido de un documento. Sin costo adicional.

Una página de PDF procesada con cuadros delimitadores de colores superpuestos sobre cada bloque de diseño detectado: título, texto, encabezados de sección, tabla, figura, leyenda, pie de página y número de página — Todos los bloques que detecta el motor, tipados y posicionados: las mismas regiones que se convierten en 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 }
      }
    ]
  }
]

Campos de bloque

Campo	Descripción
`id`	Se mantiene estable dentro de una respuesta: `p<page>.b<index in reading order>`.
`type`	Tipo de bloque: `title`, `section_header`, `text`, `table`, `formula`, `figure`, `caption`, `page_number`, `page_header`, `page_footer`. Pueden aparecer nuevos tipos con el tiempo.
`label`	Etiqueta sin procesar del modelo de diseño, transmitida directamente para garantizar la compatibilidad futura.
`bbox`	`[x0, y0, x1, y1]` normalizado entre 0 y 1 con respecto a la página. Multiplíquelo por `width`/`height` para obtener coordenadas en píxeles. `null` cuando no se conocen las dimensiones de la página.
`content`	El fragmento de markdown aportado por este bloque.
`markdownSpan`	Desplazamientos de caracteres `[start, end)` en el `markdown` del documento que abarcan el fragmento de este bloque. `null` cuando el posprocesamiento reescribió el fragmento.
`readingOrder`	Posición en el orden de lectura detectado.
`source`	Ruta del pipeline que generó el bloque (p. ej., `native_text`, `layout_ocr`, `tsr`, `formula_model`).
`confidence`	Puntuación de detección de `layout` (0–1) y nivel de confianza del texto de `ocr` cuando la fuente lo proporciona; `null` en caso contrario; nunca un valor agregado inventado.

Fundamentación: de una respuesta a la página

markdownSpan vincula cada bloque con la subcadena exacta del markdown que generó. Esto hace que la fundamentación de las citas sea una búsqueda, no una inferencia: busca el texto citado en el markdown, encuentra el bloque cuyo intervalo cubre ese desplazamiento y tendrás el número de página y el cuadro delimitador, sin pedirle nunca coordenadas a un modelo de lenguaje.

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

Salida JSON estructurada

Proporciona un JSON schema o un prompt para extraer datos estructurados directamente del documento:

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'

Opciones de PDF

Todo el comportamiento relacionado con PDF se controla mediante la opción parsers, tanto en /parse como en /scrape:

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

Propiedad	Tipo	Predeterminado	Descripción
`type`	`"pdf"`	(obligatorio)	Tipo de parser.
`mode`	`"fast" \| "auto" \| "ocr"`	`"auto"`	Estrategia de procesamiento; consulta más abajo.
`maxPages`	`integer`	—	Limita el número de páginas que se procesarán.
`pages`	`boolean`	`false`	También devuelve Markdown físico por página. Sin costo adicional.
`blocks`	`boolean`	`false`	También devuelve bloques de diseño con cuadros delimitadores. Sin costo adicional.
`pageMarkers`	`boolean`	`false`	Anota los saltos de página en el Markdown del documento con marcadores `<!-- page N -->`. Sin costo adicional.

Al pasar parsers: [], se omite por completo el procesamiento y se devuelve el PDF en base64 (1 crédito fijo).

Modos de procesamiento

Modo	Descripción
`auto`	Primero intenta extraer el texto rápidamente y recurre al OCR cuando una página lo necesita. Es el modo predeterminado.
`fast`	Solo extracción basada en texto (texto incrustado). Es la opción más rápida, pero falla en páginas escaneadas o que solo contienen imágenes, en vez de devolver un resultado vacío sin avisar.
`ocr`	Fuerza el OCR en todas las páginas. Úsalo para documentos escaneados o cuando `auto` clasifique incorrectamente una página.

Formatos compatibles

Extensiones: .html, .htm, .xhtml, .pdf, .docx, .doc, .docm, .odt, .ods, .odp, .rtf, .xlsx, .xls, .xlsm, .xlsb, .pptx, .ppt, .pptm, .epub, .csv. Consulta Document Parsing para saber cómo se convierte cada formato.

Referencia de la solicitud

La solicitud es multipart/form-data con una parte file obligatoria y una parte JSON options opcional. options acepta un subconjunto de las opciones de scraping:

formats: array de formatos de salida. El valor predeterminado es ["markdown"]. Admitidos: markdown, html, rawHtml, links, images, resumen y json (con un schema o prompt).
onlyMainContent: Solo devuelve el contenido principal del documento. El valor predeterminado es true.
includeTags / excludeTags: Inclusión o exclusión por etiqueta (entradas HTML).
redactPII: Redacta la información de identificación personal del markdown devuelto.
timeout: Tiempo de espera de la solicitud en milisegundos. El valor predeterminado es 30000; el máximo, 300000.
parsers: Opciones del parser de archivos — consulta las opciones de PDF.

/parse no admite opciones exclusivas del navegador como actions, waitFor, location, mobile o seguimiento de cambios.

¿Usas Firecrawl a través de MCP? Usa firecrawl_parse para archivos locales. El MCP local puede leer el archivo directamente cuando está configurado con FIRECRAWL_API_URL. El MCP remoto alojado primero devuelve un comando de carga de corta duración y luego procesa el uploadRef devuelto. Las URL de documentos públicos deben seguir usando /scrape.

Consideraciones

El tamaño máximo de archivo es de 50 MB por solicitud.
El procesamiento de PDF se factura a 1 crédito por página; las opciones pages, blocks y pageMarkers no generan ningún costo adicional.
Procesar archivos PDF muy grandes o escaneados en modo ocr puede tardar más; aumenta timeout o usa maxPages para limitar el procesamiento.
Para lotes de archivos, llama a /parse por archivo en paralelo; no existe una variante de carga por lote.

¿Eres un agente de IA que necesita una API key de Firecrawl? Consulta firecrawl.dev/agent-onboarding/SKILL.md para ver las instrucciones de incorporación automatizada.

Primeros pasos

Endpoints principales

Más

Inicios rápidos

Guías para desarrolladores

Webhooks

Casos de uso

Otros

Contribuciones

Inicio rápido

Respuesta

Markdown físico por página (PDF)

Marcadores de página (PDF)

Bloques de diseño (PDF)

Campos de bloque

Fundamentación: de una respuesta a la página

Salida JSON estructurada

Opciones de PDF

Modos de procesamiento

Formatos compatibles

Referencia de la solicitud

Consideraciones

​Inicio rápido

​Respuesta

​Markdown físico por página (PDF)

​Marcadores de página (PDF)

​Bloques de diseño (PDF)

​Campos de bloque

​Fundamentación: de una respuesta a la página

​Salida JSON estructurada

​Opciones de PDF

​Modos de procesamiento

​Formatos compatibles

​Referencia de la solicitud

​Consideraciones

Inicio rápido

Respuesta

Markdown físico por página (PDF)

Marcadores de página (PDF)

Bloques de diseño (PDF)

Campos de bloque

Fundamentación: de una respuesta a la página

Salida JSON estructurada

Opciones de PDF

Modos de procesamiento

Formatos compatibles

Referencia de la solicitud

Consideraciones