Procesar - Firecrawl Docs

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

Inicio rápido#

from firecrawl import Firecrawlfirecrawl = Firecrawl(api_key="fc-YOUR-API-KEY")doc = firecrawl.parse("./report.pdf")print(doc.markdown)

Note

¿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"    }  }}

Note

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.

"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.

Note

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.

"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.

Salida JSON estructurada#

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

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.

Note

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

Tip

¿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.