upstage-ocr

name	upstage-ocr
description	Extract plain text with word-level bounding box coordinates from images and scanned documents using Upstage OCR API. Use when user asks to OCR a document, extract raw text from an image/scan, or get text coordinates — '이미지에서 텍스트만 뽑아줘', 'OCR 돌려줘', 'extract text with coordinates'. DO NOT use for layout-aware extraction (tables, figures, markdown/HTML conversion) — use upstage-document-parse instead. DO NOT use for schema-driven field extraction (invoice number, total amount) — use upstage-information-extraction instead.
homepage	https://console.upstage.ai/api/document-digitization/ocr

Upstage OCR

Extract word-level text with bounding box coordinates from images and scanned documents.

Quick Start

import os
import requests

response = requests.post(
    "https://api.upstage.ai/v1/document-digitization",
    headers={"Authorization": f"Bearer {os.environ['UPSTAGE_API_KEY']}"},
    files={"document": open("scan.pdf", "rb")},
    data={"model": "ocr"}
)
result = response.json()
print(result["pages"][0]["text"])

API Key: Always use os.environ["UPSTAGE_API_KEY"]. Get your key at console.upstage.ai.

---

Endpoints

Mode	Endpoint	Max pages	Max file size
Sync	POST /v1/document-digitization	100	50 MB
Async	POST /v1/document-digitization/async	1000	50 MB

• Request format: multipart/form-data
• Sync: returns the result in the response body (timeout 5 min).
• Async: returns a request_id; poll status and download per-batch results (batches of 10 pages).

Parameters

Parameter	Type	Required	Description
model	string	Yes	ocr (alias: ocr-250904)
document	file	Yes	Document file to process
schema	string	No	clova or google (for migration)

Limits

Item	Sync	Async
Max pages	100	1000
Max file size	50 MB	50 MB
Max pixels/page	200,000,000	200,000,000

Pick sync for ≤ 100 pages and quick (≤ 5 min) processing. Pick async for documents up to 1000 pages, when you can poll, or when the sync timeout would be hit.

Supported Formats

JPEG, PNG, BMP, PDF, TIFF, HEIC, DOCX, PPTX, XLSX, HWP, HWPX

Supported Languages

• Full support: Alphabets, Korean, Chinese characters
• Partial support: Katakana, Hiragana
• Beta: Simplified Chinese

Response Structure

{
  "api": "2.0",
  "model": "ocr-250904",
  "pages": [
    {
      "id": 0,
      "text": "Full extracted text",
      "words": [
        {
          "id": 0,
          "text": "word",
          "bounding_box": {
            "vertices": [
              {"x": 0.12, "y": 0.05},
              {"x": 0.25, "y": 0.05},
              {"x": 0.25, "y": 0.08},
              {"x": 0.12, "y": 0.08}
            ]
          },
          "confidence": 0.98
        }
      ]
    }
  ],
  "usage": {"pages": 1}
}

Usage Examples

Sync — Basic OCR

curl -X POST "https://api.upstage.ai/v1/document-digitization" \
  -H "Authorization: Bearer $UPSTAGE_API_KEY" \
  -F "document=@/path/to/image.jpg" \
  -F "model=ocr"

Sync — Python (Extract Text with Coordinates)

import os
import requests

def ocr_document(file_path):
    with open(file_path, "rb") as f:
        response = requests.post(
            "https://api.upstage.ai/v1/document-digitization",
            headers={"Authorization": f"Bearer {os.environ['UPSTAGE_API_KEY']}"},
            files={"document": f},
            data={"model": "ocr"}
        )
    result = response.json()

    for page in result["pages"]:
        print(f"=== Page {page['id']} ===")
        print(page["text"])
        for word in page["words"]:
            print(f"  [{word['confidence']:.2f}] {word['text']} @ {word['bounding_box']}")

    return result

Async — Submit, Poll, Download

Use the async endpoint for documents up to 1000 pages. Documents are processed in batches of 10 pages; results are stored for 30 days, individual download URLs expire after 15 minutes.

# 1. Submit
curl -X POST "https://api.upstage.ai/v1/document-digitization/async" \
  -H "Authorization: Bearer $UPSTAGE_API_KEY" \
  -F "document=@large.pdf" \
  -F "model=ocr"
# → {"request_id": "uuid-here"}

# 2. Poll status
curl "https://api.upstage.ai/v1/document-digitization/requests/{request_id}" \
  -H "Authorization: Bearer $UPSTAGE_API_KEY"

Status values: submitted, started, completed, failed (check failure_message). The completed response includes a download_url per batch — fetch each and concatenate pages to reconstruct the full document.

import os
import time
import requests

api_key = os.environ["UPSTAGE_API_KEY"]
base = "https://api.upstage.ai/v1/document-digitization"

with open("large.pdf", "rb") as f:
    r = requests.post(
        f"{base}/async",
        headers={"Authorization": f"Bearer {api_key}"},
        files={"document": f},
        data={"model": "ocr"},
    )
request_id = r.json()["request_id"]

while True:
    status = requests.get(
        f"{base}/requests/{request_id}",
        headers={"Authorization": f"Bearer {api_key}"},
    ).json()
    if status["status"] == "completed":
        break
    if status["status"] == "failed":
        raise RuntimeError(status.get("failure_message", "unknown failure"))
    time.sleep(5)

# status["batches"] contains per-batch download_url entries
pages = []
for batch in status.get("batches", []):
    data = requests.get(batch["download_url"]).json()
    pages.extend(data["pages"])

Output Files

• Default: write to <system-temp>/<input-stem>.ocr.json (e.g., /tmp/receipt.ocr.json). Use tempfile.gettempdir() for cross-platform code.
• Override: if the user specifies an output path, use it.
• Always print the resolved absolute path in your response so the user can locate the file.

Tips

• For documents > 100 pages, switch to the async endpoint (up to 1000 pages). Sync rejects oversized documents.
• Sync server timeout is 5 minutes — if a sync request times out, retry on /async.
• Async results live for 30 days; per-batch download_urls expire after 15 minutes (re-fetch status to refresh).
• Low scan quality will result in lower confidence values. Pre-processing images can help.
• Coordinates are returned as normalized ratios (0–1).
• OCR extracts text only. If you need structured HTML/Markdown output, use Document Parse instead.