# PaddleOCR-VL (paddleocr-vl)

`paddleocr-vl` parses one document page. It finds the layout blocks (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.

| | |
|---|---|
| Model ID | `paddleocr-vl` (default model of the endpoint) |
| Model | PaddleOCR-VL 1.6 (0.9B) with PP-DocLayoutV3 layout analysis (PaddlePaddle) |
| Weights | Official PaddleOCR-VL 1.6 (0.9B) and PP-DocLayoutV3 releases (PaddleOCR) |
| Use cases | [Document parsing](https://stack.foldbun.com/docs/use-cases/document-parsing/), [Text recognition (OCR)](https://stack.foldbun.com/docs/use-cases/text-recognition/) |
| Endpoints | `POST /v1/documents/parse` |
| Pool | Paid: billed from the balance |
| Billing units | `page`. Units and prices: [Billing](https://stack.foldbun.com/docs/billing/#price-list) |
| Licence | Apache-2.0 |

## How it works

A call is a two-step pipeline on one page image: layout analysis first, then recognition of each block. The model therefore reads one region at a time instead of the whole page. Billing follows the page.

**Layout analysis.** PP-DocLayoutV3 cuts the page into blocks and gives each a type (`text`, `title`, `table`, `formula`, `figure`, `caption`, `header`, `footer`, `list` or `other`) and a box. The same step orders the blocks in reading order: a two-column page is read column by column.

**Block recognition.** Each block is passed to PaddleOCR-VL 1.6 (0.9B), a vision-language model that reads the block image and writes out its content: plain text, an HTML table, or the LaTeX of a formula. A block without text, such as a figure, has no `text`.

**Assembly.** The blocks are joined in reading order into the Markdown of the page. Figures are not returned as image files.

Recognition runs once per block, but a call is billed as one `page`, however many blocks the page has.

## In each use case

### Document parsing

`paddleocr-vl` is the default model of `POST /v1/documents/parse`, for invoices, papers, reports and book pages.

- Every region of the page is returned as a block with a `type`, an `order` (reading order, from 0, as the model determines it), a `bbox`, and the recognised `text` and `markdown`.
- Tables are HTML `<table>` elements, in both `text` and `markdown`. Display formulas are LaTeX delimited by `$$`; formulas inside a line of running text stay in the `text` and `markdown` of that block, delimited by `$`.
- The response also carries the whole page as `markdown`. With `options.blocks` set to `false`, `blocks` is omitted and only `markdown` is returned.
- One request is one page image, and `pages` is always 1. Multi-page PDF input is not available yet.

Use case guide and example call: [Document parsing](https://stack.foldbun.com/docs/use-cases/document-parsing/).

### Text recognition (OCR)

`paddleocr-vl` reads text from any page image, but it returns blocks instead of plain lines. For screenshots, crops and copy-text OCR, [`ppocr-v6`](https://stack.foldbun.com/docs/models/ppocr-v6/#text-recognition-ocr) is the low-cost choice.

Comparison with [`ppocr-v6`](https://stack.foldbun.com/docs/models/ppocr-v6/): [Text recognition (OCR)](https://stack.foldbun.com/docs/use-cases/text-recognition/#supported-models).

## Limits and notes

- One page image per call. Multi-page PDFs are not accepted yet.
- Image limits: see [Images](https://stack.foldbun.com/docs/images/). Stack resizes the page for the model before recognition. All coordinates are pixels of the oriented original, whose size is returned as `image.width` and `image.height`.
- Latency: the recorded call (the example call of the use case page) had `timing.processingMs` of 1294 ms. The figure depends on the page, on queueing and on node load, and it is not a guarantee.