FastAPI OCR Service

A REST API built with FastAPI that provides OCR (Optical Character Recognition) capabilities using EasyOCR and OpenCV. The service extracts text from images, secured with API Key Authentication and protected by rate limiting.

Features

• OCR Text Extraction - Extract text from uploaded images using EasyOCR
• API Key Authentication - Secure endpoints with API key-based
• Rate Limiting - Prevent API abuse using SlowAPI
• Auto-generated API Docs - Interactive Swagger UI and ReDoc
• Google Cloud Ready - Configured for Google Cloud deployment

Prerequisites

• Python 3.10 or higher
• pip (Python package manager)
• PyTorch (install manually from https://pytorch.org before running pip install)
• At least 5GB of free disk space (EasyOCR + PyTorch + language models)
• Google Cloud Account with a project set up
• Google Cloud SDK (gcloud CLI) installed and authenticated
• A valid API Key for authentication

Notes

• GPU is optional - EasyOCR will automatically fall back to CPU if no GPU is available
• OpenCV is required and will be installed via requirements.txt
• EasyOCR will automatically download language model files on first run (~500MB)

Google Cloud Setup (For Deployment Only)

1. Go to Google Cloud Console
2. Create a new project or select an existing one
3. Enable the required APIs (Cloud Run, Container Registry, etc.)
4. Install the Google Cloud SDK
5. Authenticate your account by running the commands below:

gcloud auth login
gcloud config set project YOUR_PROJECT_ID

Installation

1. Clone the repository

git clone <your-repo-url>
cd <your-project-folder>

2. Create and activate a virtual environment

python -m venv venv

# Activate on Linux/macOS
source venv/bin/activate

# Activate on Windows
venv\Scripts\activate

3. Install dependencies

pip install -r requirements.txt

Note: torch and easyocr are large packages (~2GB). Installation may take several minutes. EasyOCR will also download language model files on first run.

Configuration Guide

Environment Variables

Create a .env file in the project root:

cp .env.example .env

Fill in the required values in your .env file:

# API Key Authentication
API_KEY=your_api_key_here

# Rate Limiting
RATE_LIMIT=10/minute

# Google Cloud
GOOGLE_CLOUD_PROJECT=your_project_id
GOOGLE_APPLICATION_CREDENTIALS=path/to/service-account.json

Setting Up Google Cloud Credentials

1. In Google Cloud Console, go to IAM & Admin then Service Accounts
2. Create a new service account and download the JSON key file
3. Set the path in your key file in .env:

GOOGLE_APPLICATION_CREDENTIALS=/path/to/your/service-account.json

Or export it directly in your terminal:

export GOOGLE_APPLICATION_CREDENTIALS="/path/to/your/service-account.json"

Running the App

Start the development server with:

uvicorn main:app --reload

The server will start at: http://localhost:8000

To specify a custom host and port:

uvicorn main:app --reload --host 0.0.0.0 --port 8000

---

API Endpoints Documentation

Authentication

All endpoints require a valid API Key passed in the request header:

X-API-Key: your_api_key_here

Requests without a valid key will receive a 403 Forbidden response.

---

POST /ocr

Extract text from an uploaded image.

Request:

POST /ocr/detect-text
X-API-Key: your_api_key_here
Content-Type: multipart/form-data

Parameter	Type	Required	Description
file	File	Yes	Image file (jpg, png, etc.)
language	string	No	Language code (default: en)

**Example using curl:

curl -X POST "http://localhost:8000/ocr/detect-text"
-H "X-API-Key: your_api_key_here"
-F "file=@image.jpg"

Success Response 200 OK:

{
  "detected_text": ["Hello", "this is the text found in the image."]
}

Error Response 403 Forbidden:

{ "detail": "Invalid API Key." }

**Error Response `429 Too Many Requests`:**

{
  "detail": "Rate limit exceeded. Try again later."
}

---

GET /health

Check if the API is running. No authentication required.

Request:

GET /health

Response 200 OK:

{
  "status": "healthy",
  "version": "1.0.0"
}

Authentication & Rate Limiting Details

API Key Authentication

All protected endpoints require a valid API Key passed in the X-API-Key header:

X-API-Key: your_api_key_here

• Requests without a key will receive a 403 Forbidden response.
• The API Key is configured via the API_KEY environment variable in your .env file.

Rate Limiting

This API uses SlowAPI to enforce rate limits and prevent abuse.

Plan	Limit
Default	5 requests/minute (configurable)
Per IP	Enforced globally across endpoints

• Exceeding the limit returns 429 Too Many Requests.
• Rate limit resets automatically after the time window expires.
• Limits can be configured via the RATE_LIMIT environment variable (e.g., 10/minute, 100/hour).

Testing Instructions

Run with Swagger UI

1. Start the server: uvicorn main:app --reload
2. Open your browser: http://localhost:8000/docs
3. Click Authorize and enter your API Key
4. Test endpoints directly from the browser

Run with curl

# Health check
curl http://localhost:8000/health

# OCR endpoint
curl -X POST "http://localhost:8000/ocr/detect-text" \
  -H "X-API-Key: your_api_key_here" \
  -F "file=@test_image.jpg"

Run with Python requests

import requests

url = "http://localhost:8000/ocr/detect-text"
headers = {"X-API-Key": "your_api_key_here"}

with open("test_image.jpg", "rb") as f:
    response = requests.post(url, headers=headers, files={"file": f})

print(response.json())

Troubleshooting Guide

Problem	Cause	Solution
403 Forbidden	Missing or wrong API key	Check API_KEY in your .env file and use the X-API-Key header
429 Too Many Requests	Rate limit exceeded	Wait for the time window to reset
Slow first run	EasyOCR downloading models	This only happens once
CUDA errors	No GPU available	PyTorch falls back to CPU automatically
Port already in use	Another process on port 8000	Use --port 8001 or kill the process
GOOGLE_APPLICATION_CREDENTIALS error	Wrong path or missing file	Verify the path to your service account JSON
ModuleNotFoundError	Dependencies not installed	Run pip install -r requirements.txt in your venv

---

Team Members and Contributions

Name	Role / Contribution
Hans Casionan	Coding
Frenzel Tengay	README Documentation
Aprilyn Lumatac	README Documentation
Kaveen Poc-oran
Gerrund Carlos

---

Tech Stack

Component	Library
Web Framework	FastAPI + Uvicorn
OCR Engine	EasyOCR
Image Processing	OpenCV, Pillow, scikit-image
Deep Learning	PyTorch, TorchVision
Rate Limiting	SlowAPI
Config	python-dotenv
Cloud	Google Cloud Platform