OCR API
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.
POST /v1/ocrSend 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
curl -X POST "https://gateway.apinoa.com/v1/ocr" \
-H "x-api-key: $APINOA_API_KEY" \
-H "Content-Type: image/jpeg" \
--data-binary @product.jpgTo 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:
{
"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. Failed calls are not billed.
Pricing
$0.001 per image at the base rate: one unit, the same unit price as the Marketplace API. The rate steps down above 1,000 calls a day; the pricing page 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.