# Text recognition (OCR)

Text recognition returns the lines of text found in an image, each with its text, a confidence, a bounding box, a four-corner quadrilateral and, by default, word-level boxes. One call handles one image, whatever the number of lines. Typical uses are screenshots, UI captures, receipts, code windows, cropped regions and any case where the text is to be copied out as it is. To get the layout of a document page (reading order, tables, formulas), see [Document parsing](https://stack.foldbun.com/docs/use-cases/document-parsing/).

## Line recognition

Every text line found in the image is returned as an entry of `lines`, with the recognised `text`, a `confidence`, an axis-aligned `bbox` and a four-corner `quad` that fits tilted text more closely than the box does. Lines below `options.minConfidence` (default 0.5) are dropped.

![A photographed receipt with blue boxes around 44 text lines, next to the list of recognised lines with their confidences.](../../../../assets/docs/ppocr-v6-lines.webp)

*`ppocr-v6`: recorded Playground result for a photographed, slightly rotated receipt. Each box is one entry of `lines`; the list on the right shows `text` and `confidence`, with the first 22 of 44 lines.*

## Word boxes

With `options.words` (default `true`), every line carries `words`: the pieces of the line with their own `text`, `confidence`, `bbox` and `quad`. Word boxes locate a single token inside a line, for example to highlight a search hit or to place a click target. Whitespace can appear as a word of its own. With `options.words` set to `false`, `words` is omitted and the response is smaller.

![A dark code editor screenshot with alternating blue and orange boxes around individual words and symbols.](../../../../assets/docs/ppocr-v6-words.webp)

*`ppocr-v6`: recorded Playground result for an editor screenshot. Each box is one entry of `lines[].words`; the two colours alternate only to tell neighbouring words apart.*

## Supported models

`ppocr-v6` is the default and only model of `POST /v1/ocr`.

Plain lines come from `ppocr-v6`. [`paddleocr-vl`](https://stack.foldbun.com/docs/models/paddleocr-vl/#text-recognition-ocr) also reads any page image, but it is a document parser billed per page and is called through `POST /v1/documents/parse`; the table compares the two for reading text.

| | [`ppocr-v6`](https://stack.foldbun.com/docs/models/ppocr-v6/#text-recognition-ocr) | [`paddleocr-vl`](https://stack.foldbun.com/docs/models/paddleocr-vl/#text-recognition-ocr) |
|---|---|---|
| Model | PP-OCRv6 small | PaddleOCR-VL 1.6 (0.9B) with PP-DocLayoutV3 layout analysis |
| Endpoint | `POST /v1/ocr` | `POST /v1/documents/parse` |
| Accepts | One image: screenshot, crop, photo | One page image |
| Returns | Lines of text with confidence, boxes, quadrilaterals and word boxes | Layout blocks in reading order, tables as HTML, formulas as LaTeX, the page as Markdown |
| List price (credits) | 0.25 per image | 2 per page |
| Pool | Public: available to every registered account, 100 calls per UTC day included | Paid: billed from the balance |
| Recorded processing time | 753 ms (one recorded call) | 1294 ms (one recorded call) |
| Pick when | The text is to be copied out as it is | Layout, reading order, tables or formulas are needed |

- Pick `ppocr-v6` for screenshots, UI captures, receipts, code windows and cropped regions, and whenever the lowest cost matters. Grouping lines into paragraphs or columns is left to the caller.
- Pick `paddleocr-vl` for invoices, papers, reports and book pages, where blocks, reading order, tables and formulas are needed. See [Document parsing](https://stack.foldbun.com/docs/use-cases/document-parsing/).

## Example call

One screenshot of an account settings page, sent to `POST /v1/ocr` with the default options:

```bash
curl https://api.stack.foldbun.com/v1/ocr \
  -H "Authorization: Bearer $FOLDBUN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "ppocr-v6",
    "image": { "id": "img_2dedd0716bfd46ec29b286a279d18b6fc80631e5d90fedb5c63eb36f231622e6" },
    "options": { "minConfidence": 0.5 }
  }'
```

The response is abridged: one of the recognised lines is shown.

```json
{
  "id": "call_01a1913d-55cd-7bee-ba86-bbbef2aa9bae",
  "model": "ppocr-v6",
  "image": {
    "id": "img_2dedd0716bfd46ec29b286a279d18b6fc80631e5d90fedb5c63eb36f231622e6",
    "width": 1100,
    "height": 760,
    "bytes": 83478,
    "contentType": "image/jpeg"
  },
  "lines": [
    {
      "text": "Sign out",
      "confidence": 0.9786,
      "bbox": [982, 32, 1053, 56],
      "quad": [[982, 32], [1053, 32], [1053, 56], [982, 56]],
      "words": [
        { "text": "Sign", "confidence": 0.9786, "bbox": [990, 32, 1018, 56], "quad": [[990, 32], [1018, 32], [1018, 56], [990, 56]] },
        { "text": " ", "confidence": 0.9786, "bbox": [1018, 32, 1022, 56], "quad": [[1018, 32], [1022, 32], [1022, 56], [1018, 56]] },
        { "text": "out", "confidence": 0.9786, "bbox": [1026, 32, 1050, 56], "quad": [[1026, 32], [1050, 32], [1050, 56], [1026, 56]] }
      ]
    }
  ],
  "cost": 0.25,
  "balance": 12.5,
  "timing": { "queueMs": 0, "processingMs": 753 },
  "billing": {
    "lines": [
      { "unit": "image", "quantity": 1, "unitPrice": 0.25, "amount": 0.25, "waived": false }
    ],
    "total": 0.25,
    "charged": true,
    "pool": null
  }
}
```

### Reading the response

- `lines` holds the recognised lines, sorted top to bottom and then left to right. The model does no layout analysis: reading order and paragraphs are left to the caller. Each line has `text`, `confidence` (0.9786 here), `bbox` and `quad`.
- `bbox` is `[x1, y1, x2, y2]` and `quad` holds the four corners of the line, both in pixels of the oriented original, 1100 × 760 here (`image.width`, `image.height`). The order of the corners is described in the API reference.
- `words` splits the line into pieces with their own `text`, `confidence`, `bbox` and `quad`: here `Sign`, a space and `out`, because whitespace can appear as a word of its own. With `options.words` set to `false`, `words` is omitted.
- `billing.charged` is `true` and `pool` is `null`: the call was debited from the balance, so `cost` is 0.25.

All fields: [API reference](https://stack.foldbun.com/docs/api/operations/ocr/).

**Cost of this call.** 0.25 (`image`) credits per call, whatever the number of lines or words, as charged in this response. Calls inside the public pool's daily allowance are not charged. Unit prices: [Billing](https://stack.foldbun.com/docs/billing/#price-list).

## Endpoints and reference

| Endpoint | In this use case | Reference |
|---|---|---|
| `POST /v1/ocr` | Lines of text with confidence, boxes and quadrilaterals, and by default word boxes, from one image | [API reference](https://stack.foldbun.com/docs/api/operations/ocr/) |
| `POST /v1/documents/parse` | Structure (blocks, tables, formulas) instead of plain lines | [API reference](https://stack.foldbun.com/docs/api/operations/parsedocument/) |

- [`ppocr-v6`](https://stack.foldbun.com/docs/models/ppocr-v6/) and [`paddleocr-vl`](https://stack.foldbun.com/docs/models/paddleocr-vl/): how each model works, its limits and measured latency.
- [Billing](https://stack.foldbun.com/docs/billing/#price-list): the unit of each model; `ppocr-v6` bills one `image` per call.
- [Document parsing](https://stack.foldbun.com/docs/use-cases/document-parsing/): blocks, reading order, tables and formulas of a page.
- [Images](https://stack.foldbun.com/docs/images/#coordinates): the pixel space of boxes and quadrilaterals.