Upstage OCR#

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

Quick Start#

python

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#

ModeEndpointMax pagesMax file sizeSyncPOST /v1/document-digitization10050 MBAsyncPOST /v1/document-digitization/async100050 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#

ParameterTypeRequiredDescriptionmodelstringYesocr (alias: ocr-250904)documentfileYesDocument file to processschemastringNoclova or google (for migration)

Limits#

ItemSyncAsyncMax pages1001000Max file size50 MB50 MBMax pixels/page200,000,000200,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#

json

{
  "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#

bash

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)#

python

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.

bash

# 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.

python

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_url s 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.