---
title: "OCR 전용"
description: "상품 이미지의 텍스트만 감지·인식해 폴리곤 · 바운딩 박스 · 텍스트 · 신뢰도를 반환합니다. 이미지 수정/번역/렌더링 없음."
---

## 엔드포인트

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

[전체 파이프라인](./translate)에서 OCR 단계만 실행합니다. 이미지는 변경되지 않고, 번역도 수행되지 않으며, 결과 이미지도 생성되지 않습니다. 텍스트 좌표와 내용만 필요할 때 사용하세요 — 이미지 사전 분류, 커스텀 후처리 워크플로우 구성 등에 적합합니다.

`/translate` 보다 호출당 비용이 저렴합니다.

## 요청 형식

엔드포인트는 HTTP body 에 **원시 이미지 바이트** 만 받습니다. JSON + base64 는 허용되지 않습니다.

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

이외의 모든 파라미터는 **쿼리 스트링** 으로 전달합니다.

| 파라미터 | 타입 | 필수 | 기본값 | 설명 |
|-----------|------|------|--------|-----|
| `source_language` | string | 예 | — | `ch`, `zh`, `zh-CN`, `zh-TW`, `chinese_cht`, `ja`, `japan`, `en`, `auto` 중 하나. |

## 응답

```json
{
  "success": true,
  "requestId": "550e8400e29b41d4a716446655440000",
  "data": {
    "regions": [
      {
        "polygon": [[10, 20], [210, 20], [210, 60], [10, 60]],
        "bbox": { "x": 10, "y": 20, "w": 200, "h": 40 },
        "text": "免费送货",
        "confidence": 0.98
      }
    ],
    "src_w": 790,
    "src_h": 1158,
    "regions_found": 1
  }
}
```

| 필드 | 타입 | 설명 |
|-------|------|-----|
| `regions[].polygon` | number[][] | 원본 좌표계의 4점 폴리곤 |
| `regions[].bbox` | object | 원본 좌표계의 축정렬 경계 박스 `{x, y, w, h}` |
| `regions[].text` | string | 인식된 텍스트 |
| `regions[].confidence` | number | 인식 신뢰도, 0–1 |
| `src_w`, `src_h` | integer | 원본 이미지의 너비 · 높이 (px) |
| `regions_found` | integer | 반환된 영역 수 |

## 예제

### cURL

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

### Python

```python
import requests

with open("product.jpg", "rb") as f:
    img_bytes = f.read()

r = requests.post(
    "https://gateway.apinoa.com/v1/image-translate/ocr",
    headers={
        "x-api-key": "YOUR_API_KEY",
        "Content-Type": "image/jpeg",
    },
    params={"source_language": "zh-CN"},
    data=img_bytes,
    timeout=60,
)
r.raise_for_status()
for region in r.json()["data"]["regions"]:
    print(region["text"], region["confidence"])
```

## 제한

| 항목 | 값 |
|-------|-------|
| 최대 이미지 크기 | 8192 × 8192 px |
| 최대 요청 본문 | 20 MB |
| 이미지 포맷 | JPEG, PNG, WebP |

## 오류

| 코드 | HTTP | 발생 조건 |
|------|------|------|
| `BAD_REQUEST` | 400 | 빈 body 또는 잘못된 쿼리 파라미터 |
| `UNAUTHORIZED` | 401 | API 키 누락 또는 무효 |
| `UNSUPPORTED_MEDIA_TYPE` | 415 | `Content-Type` 이 바이너리 이미지 형식이 아님 |
| `PAYLOAD_TOO_LARGE` | 413 | body > 20 MB |
| `INSUFFICIENT_BALANCE` | 402 | 잔액이 호출 비용에 부족함 |
| `UPSTREAM_ERROR` | 502 | 인식이 일시적으로 불가 |

## 가격

각 호출은 [요금 페이지](/pricing)에 안내된 image-translate 요율로 잔액에서 차감됩니다.

<ApiTester endpoint="/v1/image-translate/ocr" method="POST" description="API 키로 이 엔드포인트를 테스트하세요" />