Apinoa Docs

OCR API

识别图片中的文字:每个区域的多边形、边界框、文字、置信度和颜色。支持中文、日文、英文及其他拉丁字母文字。

查看原始 .mdx
POST /v1/ocr

发送一张图片,返回其中的所有文字:位置、内容、识别的把握有多大,以及周围的颜色。图片本身不做任何修改。 以原始字节在请求体中发送图片(不是 JSON,也不是 base64)。

可识别中文(简体和繁体)、日文、英文及其他拉丁字母语言。

请求

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

只需要某一种语言的文字时,在查询字符串中加上该语言:/v1/ocr?language=zh-CN。

参数

请求头

请求头必填说明
x-api-key是你的 API 密钥。
Content-Type是image/jpeg、image/png、image/webp 或 application/octet-stream。

查询字符串

参数类型必填说明
languagestring返回哪些文字。默认 auto:所有区域,包括数字和符号。取值见下表。
language返回
auto(默认)图片中的所有区域。
zh-CN含简体中文文字的区域。
zh-TW含繁体中文文字的区域。
ja含日文文字的区域。
en含英文或其他拉丁字母文字的区域。

取值不是 auto 时,只返回含有该语言文字的区域,只有数字或符号的区域(如单独的价格 99.00、年份 2024) 也会被去掉。对一张带英文标签的中文商品图传入 zh-CN,只会返回中文的行。其他取值返回 400 BAD_REQUEST, 错误信息中会列出可接受的值。

响应

真实响应,仅保留第一个区域:

{
  "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
  }
}
字段类型含义
regions[].indexinteger区域编号,从 0 开始。
regions[].polygonnumber[][]四个角点,使用原图坐标。
regions[].bboxobject边界框 {x, y, w, h},使用原图坐标。
regions[].textstring识别出的文字。
regions[].confidencenumber识别置信度,0–1。
regions[].text_color, regions[].bg_colorobject估算的文字颜色和背景颜色,RGB 格式。
regions[].bg_stdnumber文字背后背景的不均匀程度;接近 0 表示纯色。
regions[].font_weightstring检测到的字重。
regions[].is_badgeboolean对于填充标签上的文字(如价签或促销标签)为 true。
regions_foundinteger找到的区域数量。
src_w, src_hinteger原图的宽度和高度,单位为像素。

错误

状态码代码含义
400BAD_REQUEST请求体为空,或 language 不是可接受的值。
401UNAUTHORIZED缺少 x-api-key 请求头,或密钥无效。
402INSUFFICIENT_BALANCE余额不足以支付本次调用。重试无法解决;请充值。
413PAYLOAD_TOO_LARGE请求体超过 20 MB。
415UNSUPPORTED_MEDIA_TYPEContent-Type 不是图片类型。
422INVALID_IMAGE这些字节不是可读取的图片。
502UPSTREAM_ERROR识别暂时不可用。请重试。

所有代码都列在 Errors 中。失败的调用不计费。

价格

按基础费率每张图片 $0.001:计 1 个单位,与 Marketplace API 单价相同。 单日调用超过 1,000 次后单价下调,各档位见价格页面。

长图

长边小于短边 2.5 倍的图片计 1 个单位。达到或超过 2.5 倍的图片(如竖长的商品详情图)会分段识别,每段计 1 个单位:

段数 = ceil(长边 ÷ (2 × 短边))
图片(px)长边 ÷ 短边单位
750 × 1,8002.41
750 × 3,00042(3,000 ÷ 1,500)
750 × 10,00013.37(10,000 ÷ 1,500 = 6.7,向上取整)

横长的图片同样适用:长边指两边中较长的一边。失败的调用不计费。

说明

  • 语言。 中文(简体和繁体)、日文、英文及其他拉丁字母语言。不识别韩文。
  • 限制。 图片最大 8192 × 8192 px,请求体最大 20 MB,格式为 JPEG、PNG 或 WebP。
  • 超时。 一次调用通常约 1 秒。大量调用同时到达时,调用会等待而不是失败,因此请把 HTTP 客户端的超时设为至少 300 秒。
  • 翻译文字。 如需在保留设计的同时把图片中的文字替换为译文,请使用 Image Translate。

本页内容