# 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)](https://stack.foldbun.com/docs/use-cases/text-recognition/).

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

![A two-column paper page with numbered boxes over 25 layout blocks, next to the block list showing type and text.](../../../../assets/docs/paddleocr-vl-layout.webp)

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

![An invoice page with two teal boxes around tables, next to the rendered HTML of the large line-item table, block order 7.](../../../../assets/docs/paddleocr-vl-tables.webp)

*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 `$`.

![A page of Chinese physics text with a boxed displacement formula, and below it the recognised LaTeX and an inline formula from the preceding text block.](../../../../assets/docs/paddleocr-vl-formulas.webp)

*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`](https://stack.foldbun.com/docs/models/paddleocr-vl/#document-parsing) 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`](https://stack.foldbun.com/docs/models/ppocr-v6/#document-parsing) 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)](https://stack.foldbun.com/docs/use-cases/text-recognition/#supported-models).

## Example call

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

```bash
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.

```json
{
  "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](https://stack.foldbun.com/docs/api/operations/parsedocument/).

**Cost of this call.** 2 (`page`) credits per call, whatever the number of blocks, as charged in this response. Unit prices: [Billing](https://stack.foldbun.com/docs/billing/#price-list).

## 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](https://stack.foldbun.com/docs/api/operations/parsedocument/) |
| `POST /v1/ocr` | Plain lines and word boxes instead of structure | [API reference](https://stack.foldbun.com/docs/api/operations/ocr/) |

- [`paddleocr-vl`](https://stack.foldbun.com/docs/models/paddleocr-vl/): how the model works, its limits and measured latency.
- [Billing](https://stack.foldbun.com/docs/billing/#price-list): `paddleocr-vl` bills one `page` per call.
- [Text recognition (OCR)](https://stack.foldbun.com/docs/use-cases/text-recognition/): plain lines and word boxes with `ppocr-v6`, and the comparison of both models.