---
title: "OCR"
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/image-translate/llms.txt)

```http
POST /v1/image-translate/ocr
```

[Translate](/docs/api-reference/image-translate/translate)의 읽기 단계만 실행합니다. 텍스트 영역을 돌려주고
아무것도 바꾸지 않습니다. 이미지를 미리 걸러 내거나 자체 워크플로를 구동하는 데 쓰세요. 이미지는 본문에 **원시 바이트**로, `source_language`는 쿼리 문자열로 보냅니다.

## 요청

```bash tab="cURL"
curl -X POST "https://gateway.apinoa.com/v1/image-translate/ocr?source_language=zh-CN" \
  -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/image-translate/ocr?source_language=zh-CN", {
  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/image-translate/ocr",
    params={"source_language": "zh-CN"},
    headers={"x-api-key": os.environ["APINOA_API_KEY"], "Content-Type": "image/jpeg"},
    data=image,
    timeout=60,
)
body = res.json()
```

## 파라미터

**헤더**

| 헤더 | 필수 | 비고 |
|---|---|---|
| `x-api-key` | 예 | API 키. |
| `Content-Type` | 예 | `image/jpeg`, `image/png`, `image/webp`, `application/octet-stream` 중 하나. |

**쿼리 문자열**

| 파라미터 | 타입 | 필수 | 비고 |
|---|---|---|---|
| `source_language` | string | 예 | `ch`, `zh`, `zh-CN`, `zh-TW`, `chinese_cht`, `ja`, `japan`, `en`, 또는 `auto`. |

## 응답

실제 응답을 첫 번째 영역만 남기고 줄인 것입니다.

```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` | 본문이 비었거나, 쿼리 파라미터가 유효하지 않습니다. |
| 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)에 있습니다. 실패한 호출은 과금되지 않습니다.

## 가격

각 호출은 Translate와 같이 [가격 페이지](/pricing)의 이미지 번역 요율로 과금됩니다.

## 참고

- **한도.** JPEG, PNG, WebP 이미지, 최대 8192 × 8192 px, 본문 20 MB까지입니다.