---
title: "OCR API"
description: "Read the text in an image: every region with its polygon, bounding box, text, confidence and colours. Chinese, Japanese, English and other Latin-script text."
---

> Every apinoa docs page as markdown: https://apinoa.com/llms.txt (all in one file: https://apinoa.com/llms-full.txt; this API family in one file: https://apinoa.com/docs/ocr/llms.txt)

```http
POST /v1/ocr
```

Send an image and get back every piece of text in it: where it is, what it says, how sure the read is, and
the colours around it. Nothing in the image is changed. Send the image as **raw bytes** in the body (not
JSON, not base64).

It reads Chinese (Simplified and Traditional), Japanese, English and other Latin-script languages.

## Request

```bash tab="cURL"
curl -X POST "https://gateway.apinoa.com/v1/ocr" \
  -H "x-api-key: $APINOA_API_KEY" \
  -H "Content-Type: image/jpeg" \
  --data-binary @product.jpg
```

```js tab="JavaScript"
import { readFile } from "node:fs/promises";

const res = await fetch("https://gateway.apinoa.com/v1/ocr", {
  method: "POST",
  headers: { "x-api-key": process.env.APINOA_API_KEY, "Content-Type": "image/jpeg" },
  body: await readFile("product.jpg"),
});
const { success, data, error } = await res.json();
```

```python tab="Python"
import os

import requests

with open("product.jpg", "rb") as f:
    image = f.read()

res = requests.post(
    "https://gateway.apinoa.com/v1/ocr",
    headers={"x-api-key": os.environ["APINOA_API_KEY"], "Content-Type": "image/jpeg"},
    data=image,
    timeout=300,
)
body = res.json()
```

To keep only one language's text, add it to the query string: `/v1/ocr?language=zh-CN`.

## Parameters

**Headers**

| Header | Required | Notes |
|---|---|---|
| `x-api-key` | yes | Your API key. |
| `Content-Type` | yes | `image/jpeg`, `image/png`, `image/webp` or `application/octet-stream`. |

**Query string**

| Parameter | Type | Required | Notes |
|---|---|---|---|
| `language` | string | | Which text to return. Default `auto`: every region, numbers and symbols included. See the values below. |

| `language` | Returns |
|---|---|
| `auto` (default) | Every region in the image. |
| `zh-CN` | Regions with Simplified Chinese text. |
| `zh-TW` | Regions with Traditional Chinese text. |
| `ja` | Regions with Japanese text. |
| `en` | Regions with English or other Latin-script text. |

With any value other than `auto`, only the regions containing text in that language's script come back, and
a region that is only numbers or symbols (a bare price such as `99.00`, a year such as `2024`) is left out
too. On a Chinese product photo with English labels, `zh-CN` returns just the Chinese lines. Any other value
is a `400 BAD_REQUEST` whose message names the accepted values.

## Response

A real response, shortened to its first region:

```json
{
  "success": true,
  "requestId": "43d899616f8e468aa22368bffaae1953",
  "data": {
    "regions": [
      {
        "index": 0,
        "polygon": [[83, 68], [352, 68], [352, 145], [83, 145]],
        "bbox": { "x": 83, "y": 68, "w": 269, "h": 77 },
        "text": "限时特价",
        "confidence": 0.999354,
        "text_color": { "r": 255, "g": 253, "b": 252 },
        "bg_color": { "r": 211, "g": 40, "b": 43 },
        "bg_std": 0.363554,
        "font_weight": "Regular",
        "is_badge": false
      }
    ],
    "regions_found": 3,
    "src_w": 800,
    "src_h": 600
  }
}
```

| Field | Type | Meaning |
|---|---|---|
| `regions[].index` | integer | The region's number, starting at 0. |
| `regions[].polygon` | number[][] | Four corner points, in the original image's coordinates. |
| `regions[].bbox` | object | The bounding box `{x, y, w, h}`, in the original image's coordinates. |
| `regions[].text` | string | The text that was read. |
| `regions[].confidence` | number | Recognition confidence, 0–1. |
| `regions[].text_color`, `regions[].bg_color` | object | Estimated text and background colours, as RGB. |
| `regions[].bg_std` | number | How uneven the background is behind the text; near 0 is a flat colour. |
| `regions[].font_weight` | string | The detected weight. |
| `regions[].is_badge` | boolean | `true` for text on a filled label, such as a price tag or sale badge. |
| `regions_found` | integer | How many regions were found. |
| `src_w`, `src_h` | integer | The original image's width and height, in pixels. |

## Errors

| Status | Code | Meaning |
|---|---|---|
| 400 | `BAD_REQUEST` | The body is empty, or `language` is not one of the accepted values. |
| 401 | `UNAUTHORIZED` | The `x-api-key` header is missing, or the key is invalid. |
| 402 | `INSUFFICIENT_BALANCE` | The balance does not cover the call. Retrying does not clear it; top up. |
| 413 | `PAYLOAD_TOO_LARGE` | The body is over 20 MB. |
| 415 | `UNSUPPORTED_MEDIA_TYPE` | `Content-Type` is not an image type. |
| 422 | `INVALID_IMAGE` | The bytes are not a readable image. |
| 502 | `UPSTREAM_ERROR` | Reading is briefly unavailable. Retry. |

Every code is listed in [Errors](/docs/errors). Failed calls are not billed.

## Pricing

**$0.001 per image** at the base rate: one unit, the same unit price as the
[Marketplace API](/docs/api-reference/marketplaces). The rate steps down above 1,000 calls a day; the
[pricing page](/pricing) has the brackets.

### Long Images

An image whose long side is less than 2.5 times its short side costs one unit. From 2.5 times on, as with a
tall product description image, it is read in sections and billed one unit per section:

```
sections = ceil(long side ÷ (2 × short side))
```

| Image (px) | Long side ÷ short side | Units |
|---|---|---|
| 750 × 1,800 | 2.4 | 1 |
| 750 × 3,000 | 4 | 2 (3,000 ÷ 1,500) |
| 750 × 10,000 | 13.3 | 7 (10,000 ÷ 1,500 = 6.7, rounded up) |

The same holds for a wide image: the long side is whichever is longer. A call that fails is not billed.

## Notes

- **Languages.** Chinese (Simplified and Traditional), Japanese, English and other Latin-script languages.
  Korean is not read.
- **Limits.** Images up to 8192 × 8192 px and a 20 MB body, as JPEG, PNG or WebP.
- **Timeouts.** A typical call takes about a second. When many calls arrive at once, a call waits rather than
  failing, so set your HTTP client's timeout to at least 300 seconds.
- **Translating the text.** To replace the text in the image with a translation, keeping the design, use
  [Image Translate](/docs/api-reference/image-translate).
