Document parsing

Document parsing finds the layout blocks of a page (text, title, table, formula, figure and more), recognises each block, and returns the blocks in reading order together with the whole page as Markdown. Tables are written as HTML tables and formulas as LaTeX. Typical uses are invoices, papers, reports and book pages that are converted to structured text. One request is one page image. Multi-page PDF input is not available yet. To read plain lines from a screenshot or a crop, see Text recognition (OCR).

Layout blocks and reading order

Every region of the page is returned as an entry of blocks with a type, an order, a bbox, and the recognised text and markdown. The type is one of text, title, table, formula, figure, caption, header, footer, list and other. order is the reading order, from 0, as the model determines it; the page below is read column by column. The markdown field of the response joins the blocks in that order.

Recorded Playground result for a two-column paper page. The numbers are order; the list on the right shows type and the start of text, with a title, text, a formula, a table and a footer among the 25 blocks.

With options.blocks set to false, blocks is omitted and only markdown is returned.

Tables as HTML

A block of type table holds the table as an HTML <table>, in both text and markdown, so that rows, columns and header cells survive and the table can be rendered or parsed directly.

Recorded Playground result for an invoice. The teal boxes are blocks of type table; the right side is the HTML of the block with order 7, rendered.

Formulas as LaTeX

A block of type formula holds a display formula as LaTeX, delimited by $$. Formulas that sit inside a line of running text stay in the text and markdown of that block, delimited by $.

Recorded Playground result for a textbook page. The boxed display formula is a block of type formula; the recognised LaTeX is shown below the page, with an inline formula from an adjacent text block.

Supported models

paddleocr-vl is the default and only model of POST /v1/documents/parse.

• paddleocr-vl is the model for documents: typed blocks with boxes, reading order, tables as HTML, formulas as LaTeX and a Markdown version of the page. It is billed per page and available from the paid pool only.
• ppocr-v6 returns plain lines and word boxes without layout, reading order, tables or formulas. It is the low-cost choice for screenshots, crops and copy-text OCR. The table that compares the two is on Text recognition (OCR).

Example call

One invoice page sent to POST /v1/documents/parse with layout blocks:

curl https://api.stack.foldbun.com/v1/documents/parse \
  -H "Authorization: Bearer $FOLDBUN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "paddleocr-vl",
    "image": { "id": "img_e0100380a624332f4161c651ea355c84914159eaa064df2db226519dadb944e7" },
    "options": { "blocks": true }
  }'

The response is abridged: the page has more blocks and a longer Markdown string.

{
  "id": "call_01a1913d-e9ef-767e-8ca1-f490b0af5533",
  "model": "paddleocr-vl",
  "image": {
    "id": "img_e0100380a624332f4161c651ea355c84914159eaa064df2db226519dadb944e7",
    "width": 1008,
    "height": 1426,
    "bytes": 143151,
    "contentType": "image/jpeg"
  },
  "pages": 1,
  "markdown": "INVOICE\n\n<table>...</table>\n\n## BILL TO\n\nAlder & Finch Trading Ltd.\n...",
  "blocks": [
    { "type": "header", "order": 1, "bbox": [710, 76, 933, 124], "text": "INVOICE", "markdown": "INVOICE" },
    {
      "type": "table",
      "order": 2,
      "bbox": [81, 164, 928, 223],
      "text": "<table><tr><td>INVOICE NO.</td><td>ISSUE DATE</td></tr><tr><td>INV-2026-04817</td><td>14 Oct 2026</td></tr></table>",
      "markdown": "<table><tr><td>INVOICE NO.</td><td>ISSUE DATE</td></tr><tr><td>INV-2026-04817</td><td>14 Oct 2026</td></tr></table>"
    }
  ],
  "cost": 2,
  "balance": 996,
  "timing": { "queueMs": 0, "processingMs": 1294 },
  "billing": {
    "lines": [
      { "unit": "page", "quantity": 1, "unitPrice": 2, "amount": 2, "waived": false }
    ],
    "total": 2,
    "charged": true,
    "pool": null
  }
}

Reading the response

• pages is 1: a request is one page image.
• markdown is the whole page in reading order, with tables as HTML.
• blocks holds one entry per layout region; the JSON shows two of them. type is header and table here, order is the reading order, bbox is [x1, y1, x2, y2] in pixels of the oriented original, 1008 × 1426 here (image.width, image.height).
• text is the recognised text of the block. The table block holds an HTML <table> in both text and markdown.
• billing.charged is true and pool is null: the call was debited from the balance, so cost is 2.

All fields: API reference.

Cost of this call. 2 (page) credits per call, whatever the number of blocks, as charged in this response. Unit prices: Billing.

Endpoints and reference

Endpoint	In this use case	Reference
POST /v1/documents/parse	One page image to ordered blocks, HTML tables, LaTeX formulas and the page as Markdown	API reference
POST /v1/ocr	Plain lines and word boxes instead of structure	API reference

• paddleocr-vl: how the model works, its limits and measured latency.
• Billing: paddleocr-vl bills one page per call.
• Text recognition (OCR): plain lines and word boxes with ppocr-v6, and the comparison of both models.