README.md

---
title: Handwritten OCR API
emoji: ✍️
colorFrom: blue
colorTo: indigo
sdk: docker
pinned: false
app_port: 7860
---

# Handwritten OCR API

English handwritten text recognition using **Microsoft TrOCR** (large-handwritten variant), served as a pure FastAPI REST endpoint.

## Endpoints

| Method | Path | Description |
|--------|------|-------------|
| `GET` | `/` | Service info & endpoint list |
| `GET` | `/health` | Health check |
| `POST` | `/ocr/file` | Upload **PDF or image** → text |
| `POST` | `/ocr/base64` | Send base64 **PDF or image** → text |
| `GET` | `/docs` | Swagger UI |

## Supported Formats
PDF · JPG · PNG · WEBP · BMP · TIFF — auto-detected from file content (not filename).

## Usage Examples

### cURL — image upload
```bash
curl -X POST "https://<your-space>.hf.space/ocr/file" \
     -F "file=@handwritten_note.jpg"
```

### cURL — PDF upload
```bash
curl -X POST "https://<your-space>.hf.space/ocr/file" \
     -F "file=@document.pdf"
```

### cURL — base64
```bash
BASE64=$(base64 -w 0 document.pdf)
curl -X POST "https://<your-space>.hf.space/ocr/base64" \
     -H "Content-Type: application/json" \
     -d "{\"file\": \"$BASE64\", \"filename\": \"document.pdf\"}"
```

### Python
```python
import requests, base64

# --- image upload ---
with open("note.jpg", "rb") as f:
    r = requests.post("https://<your-space>.hf.space/ocr/file", files={"file": f})
print(r.json()["text"])

# --- PDF upload ---
with open("doc.pdf", "rb") as f:
    r = requests.post("https://<your-space>.hf.space/ocr/file", files={"file": f})
data = r.json()
print(data["full_text"])          # all pages joined
for page in data["pages"]:        # or page-by-page
    print(f"Page {page['page']}: {page['text']}")

# --- base64 (PDF or image) ---
with open("doc.pdf", "rb") as f:
    b64 = base64.b64encode(f.read()).decode()
r = requests.post("https://<your-space>.hf.space/ocr/base64",
                  json={"file": b64, "filename": "doc.pdf"})
print(r.json()["full_text"])
```

## Response — Image
```json
{
  "success": true,
  "file_type": "image",
  "text": "Hello World",
  "inference_seconds": 0.84,
  "filename": "note.jpg"
}
```

## Response — PDF
```json
{
  "success": true,
  "file_type": "pdf",
  "page_count": 3,
  "pages": [
    { "page": 1, "text": "Dear John ...", "inference_seconds": 0.91 },
    { "page": 2, "text": "Continued ...", "inference_seconds": 0.88 },
    { "page": 3, "text": "Regards",       "inference_seconds": 0.85 }
  ],
  "full_text": "Dear John ...\n\nContinued ...\n\nRegards",
  "total_seconds": 2.74,
  "filename": "letter.pdf"
}
```