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

> 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
```

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

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

## 请求

```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()
```

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

## 参数

**请求头**

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

**查询字符串**

| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `language` | string | | 返回哪些文字。默认 `auto`：所有区域，包括数字和符号。取值见下表。 |

| `language` | 返回 |
|---|---|
| `auto`（默认） | 图片中的所有区域。 |
| `zh-CN` | 含简体中文文字的区域。 |
| `zh-TW` | 含繁体中文文字的区域。 |
| `ja` | 含日文文字的区域。 |
| `en` | 含英文或其他拉丁字母文字的区域。 |

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

## 响应

真实响应，仅保留第一个区域：

```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
  }
}
```

| 字段 | 类型 | 含义 |
|---|---|---|
| `regions[].index` | integer | 区域编号，从 0 开始。 |
| `regions[].polygon` | number[][] | 四个角点，使用原图坐标。 |
| `regions[].bbox` | object | 边界框 `{x, y, w, h}`，使用原图坐标。 |
| `regions[].text` | string | 识别出的文字。 |
| `regions[].confidence` | number | 识别置信度，0–1。 |
| `regions[].text_color`, `regions[].bg_color` | object | 估算的文字颜色和背景颜色，RGB 格式。 |
| `regions[].bg_std` | number | 文字背后背景的不均匀程度；接近 0 表示纯色。 |
| `regions[].font_weight` | string | 检测到的字重。 |
| `regions[].is_badge` | boolean | 对于填充标签上的文字（如价签或促销标签）为 `true`。 |
| `regions_found` | integer | 找到的区域数量。 |
| `src_w`, `src_h` | integer | 原图的宽度和高度，单位为像素。 |

## 错误

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

所有代码都列在 [Errors](/docs/errors) 中。失败的调用不计费。

## 价格

按基础费率**每张图片 $0.001**：计 1 个单位，与 [Marketplace API](/docs/api-reference/marketplaces) 单价相同。
单日调用超过 1,000 次后单价下调，各档位见[价格页面](/pricing)。

### 长图

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

```
段数 = ceil(长边 ÷ (2 × 短边))
```

| 图片（px） | 长边 ÷ 短边 | 单位 |
|---|---|---|
| 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，向上取整） |

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

## 说明

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