Apinoa Docs

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.

View raw .mdx
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

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

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

Parameters

Headers

HeaderRequiredNotes
x-api-keyyesYour API key.
Content-Typeyesimage/jpeg, image/png, image/webp or application/octet-stream.

Query string

ParameterTypeRequiredNotes
languagestringWhich text to return. Default auto: every region, numbers and symbols included. See the values below.
languageReturns
auto (default)Every region in the image.
zh-CNRegions with Simplified Chinese text.
zh-TWRegions with Traditional Chinese text.
jaRegions with Japanese text.
enRegions 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
  }
}
FieldTypeMeaning
regions[].indexintegerThe region's number, starting at 0.
regions[].polygonnumber[][]Four corner points, in the original image's coordinates.
regions[].bboxobjectThe bounding box {x, y, w, h}, in the original image's coordinates.
regions[].textstringThe text that was read.
regions[].confidencenumberRecognition confidence, 0–1.
regions[].text_color, regions[].bg_colorobjectEstimated text and background colours, as RGB.
regions[].bg_stdnumberHow uneven the background is behind the text; near 0 is a flat colour.
regions[].font_weightstringThe detected weight.
regions[].is_badgebooleantrue for text on a filled label, such as a price tag or sale badge.
regions_foundintegerHow many regions were found.
src_w, src_hintegerThe original image's width and height, in pixels.

Errors

StatusCodeMeaning
400BAD_REQUESTThe body is empty, or language is not one of the accepted values.
401UNAUTHORIZEDThe x-api-key header is missing, or the key is invalid.
402INSUFFICIENT_BALANCEThe balance does not cover the call. Retrying does not clear it; top up.
413PAYLOAD_TOO_LARGEThe body is over 20 MB.
415UNSUPPORTED_MEDIA_TYPEContent-Type is not an image type.
422INVALID_IMAGEThe bytes are not a readable image.
502UPSTREAM_ERRORReading 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 sideUnits
750 × 1,8002.41
750 × 3,00042 (3,000 ÷ 1,500)
750 × 10,00013.37 (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.

On this page