Parse - Firecrawl Docs

O Parse converte documentos em dados limpos e prontos para LLMs. Envie um arquivo para /parse — ou use /scrape em uma URL pública de documento — e receba markdown, conteúdo por página, blocos de layout tipados ou JSON estruturado.

Preserva o layout: títulos, parágrafos, tabelas e fórmulas organizados na ordem de leitura
Inclui documentos digitalizados: extração de texto nativo com OCR como alternativa para páginas que contêm apenas imagens
Estrutura fundamentada: blocos de layout tipados com caixas delimitadoras e links para intervalos de caracteres no markdown (PDFs)
Compatível com formatos comuns: PDF, Word, Excel, PowerPoint, OpenDocument, EPUB, CSV, HTML
Suporte a Zero Data Retention

Guia de início rápido#

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

Note

Tem uma URL pública de documento em vez de um arquivo? /scrape detecta o tipo de arquivo e faz o parsing da mesma forma — com as mesmas opções e o mesmo resultado: firecrawl.scrape("https://example.com/report.pdf").

Resposta#

Os SDKs retornam diretamente o objeto de documento. O cURL retorna o payload JSON.

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

Note

numPages é o número de páginas efetivamente analisadas; totalPages é a contagem real de páginas do documento. Os valores coincidem, a menos que maxPages tenha truncado o resultado — por exemplo, analisar um PDF de 100 páginas com maxPages: 10 retorna numPages: 10 e totalPages: 100, então totalPages > numPages indica que o resultado foi truncado. totalPages é omitido quando não é possível determinar a contagem de páginas.

Além do markdown do documento, três resultados abrangem os casos em que uma única string de markdown não é suficiente: markdown por página e blocos de layout para documentos PDF, e JSON estruturado para todos os formatos. E quando tudo o que você precisa é da atribuição de página dentro do próprio markdown, marcadores de página anotam as quebras de página no local.

Markdown por página (PDF)#

Defina pages: true no parser de PDF, e o documento também inclui um array pages com o markdown físico de cada página — útil quando você precisa saber de qual página veio o conteúdo ou processar as páginas de forma independente. Sem custo adicional.

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

Marcadores de página (PDF)#

Defina pageMarkers: true no parser de PDF, e as páginas no markdown do documento serão separadas por um marcador de comentário HTML que identifica a página física seguinte:

...fim da página 1---<!-- page 2 -->início da página 2...

Não há um novo campo de resposta — os marcadores são inseridos no markdown, portanto qualquer pipeline subsequente que processa apenas uma string de markdown mantém a atribuição por página. Os comentários são invisíveis quando o markdown é renderizado e fáceis de separar (, com numeração iniciando em 1). Sem custo adicional.

Note

Os marcadores aparecem apenas entre as páginas — não há marcador inicial para a página 1. A numeração pode pular uma página quando o parser mescla conteúdo em uma quebra de página (uma tabela ou frase que continua na página seguinte não deixa um limite para marcar). Use pages: true quando precisar de cada página física separadamente; as duas options podem ser combinadas.

Blocos de layout (PDF)#

Defina blocks: true no parser de PDF, e o documento também passará a incluir um array blocks: para cada página, os blocos de layout tipados que o mecanismo de análise detectou, com geometria e origem. Este é o equivalente estruturado do markdown — use-o para fundamentação de citações, criar sobreposições de destaque ou auditar o conteúdo de um documento. Sem custo adicional.

Uma página de PDF analisada com caixas delimitadoras coloridas sobrepostas a cada bloco de layout detectado: título, texto, cabeçalhos de seção, tabela, figura, legenda, rodapé e número da página — Todos os blocos que o mecanismo detecta, tipados e posicionados — as mesmas regiões que se tornam o 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 do bloco#

Campo	Descrição
`id`	Estável dentro de uma resposta: `p<page>.b<index in reading order>`.
`type`	Tipo de bloco: `title`, `section_header`, `text`, `table`, `formula`, `figure`, `caption`, `page_number`, `page_header`, `page_footer`. Novos tipos podem surgir ao longo do tempo.
`label`	Rótulo bruto do modelo de layout, repassado para compatibilidade futura.
`bbox`	`[x0, y0, x1, y1]` normalizado de 0 a 1 em relação à página. Multiplique por `width`/`height` para obter coordenadas em pixels. `null` quando a página não tiver dimensões conhecidas.
`content`	O fragmento Markdown para o qual este bloco contribuiu.
`markdownSpan`	Deslocamentos de caracteres `[start, end)` no `markdown` do documento que abrangem o fragmento deste bloco. `null` quando o pós-processamento reescreveu o fragmento.
`readingOrder`	Posição na ordem de leitura detectada.
`source`	Caminho do pipeline que produziu o bloco (por exemplo, `native_text`, `layout_ocr`, `tsr`, `formula_model`).
`confidence`	Pontuação de detecção de `layout` (0–1) e confiança do texto de `ocr` quando a fonte fornecer uma; `null` caso contrário — nunca um agregado inventado.

Fundamentação: de uma resposta à página#

markdownSpan vincula cada bloco ao trecho exato do markdown que ele produziu. Isso torna a fundamentação de citações uma consulta, não uma inferência: encontre o texto citado no markdown, localize o bloco cujo intervalo abrange esse deslocamento e você terá o número da página e a caixa delimitadora — sem jamais precisar pedir coordenadas a um modelo de linguagem.

Resultado JSON estruturado#

Passe um schema JSON ou um prompt para extrair dados estruturados diretamente do documento:

Opções de PDF#

Todo o comportamento relacionado a PDFs é controlado pela opção parsers, tanto em /parse quanto em /scrape:

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

Propriedade	Tipo	Padrão	Descrição
`type`	`"pdf"`	(obrigatório)	Tipo de parser.
`mode`	`"fast" \| "auto" \| "ocr"`	`"auto"`	Estratégia de análise — veja abaixo.
`maxPages`	`integer`	—	Limita o número de páginas a analisar.
`pages`	`boolean`	`false`	Também retorna Markdown por página. Sem custo adicional.
`blocks`	`boolean`	`false`	Também retorna blocos de layout com caixas delimitadoras. Sem custo adicional.
`pageMarkers`	`boolean`	`false`	Anota as quebras de página no Markdown do documento com marcadores `<!-- page N -->`. Sem custo adicional.

Passar parsers: [] ignora completamente a análise e retorna o PDF em base64 (1 crédito fixo).

Modos de análise#

Modo	Descrição
`auto`	Primeiro tenta a extração rápida baseada em texto e recorre ao OCR quando necessário. Este é o padrão.
`fast`	Somente extração baseada em texto (texto incorporado). É a opção mais rápida, mas falha em páginas digitalizadas ou que contêm apenas imagens, em vez de retornar silenciosamente um resultado vazio.
`ocr`	Força o OCR em todas as páginas. Use para documentos digitalizados ou quando `auto` classificar uma página incorretamente.

Formatos compatíveis#

Extensões compatíveis: .html, .htm, .xhtml, .pdf, .docx, .doc, .docm, .odt, .ods, .odp, .rtf, .xlsx, .xls, .xlsm, .xlsb, .pptx, .ppt, .pptm, .epub, .csv.

Consulte análise de documentos para saber como cada formato é convertido.

Referência da requisição#

A requisição é multipart/form-data, com uma parte file obrigatória e uma parte JSON options opcional. options aceita um subconjunto das opções de scraping:

formats: Array de formatos de resultado. O padrão é ["markdown"]. Compatíveis: markdown, html, rawHtml, links, images, summary e json (com um schema ou prompt).
onlyMainContent: Retorna apenas o conteúdo principal do documento. O padrão é true.
includeTags / excludeTags: Inclusão ou exclusão em nível de tag (entradas HTML).
redactPII: Redige informações de identificação pessoal do markdown retornado.
timeout: Tempo limite da requisição em milissegundos. O padrão é 30000, máximo de 300000.
parsers: Controles do parser de arquivos — consulte as opções de PDF.

Note

/parse não oferece suporte a opções exclusivas do navegador, como actions, waitFor, location, mobile ou rastreamento de alterações.

Tip

Usando o Firecrawl via MCP? Use firecrawl_parse para arquivos locais. O MCP local pode ler o arquivo diretamente quando configurado com FIRECRAWL_API_URL. O MCP remoto hospedado primeiro retorna um comando de upload temporário e, em seguida, processa o uploadRef retornado. URLs públicas de documentos ainda devem usar /scrape.

Considerações#

O tamanho máximo do arquivo é de 50 MB por requisição.
A análise de PDFs é cobrada a 1 crédito por página; as opções pages, blocks e pageMarkers não geram custo adicional.
A análise de PDFs muito grandes ou digitalizados no modo ocr pode demorar mais — aumente o valor de timeout ou use maxPages para limitar o processamento.
Para lotes de arquivos, chame /parse para cada arquivo em paralelo; não há opção de upload em lote.

É um agente de IA que precisa de uma chave de API do Firecrawl? Consulte firecrawl.dev/agent-onboarding/SKILL.md para ver instruções de onboarding automatizado.