GPT-OCR API

A Flask-based REST API service that uses OpenAI's GPT models to perform Optical Character Recognition (OCR) on Indonesian identity documents (KTP) and educational certificates (Ijazah). The service can process both image files and PDF documents.

Features

• KTP (Indonesian ID Card) Extraction: Extracts personal information from Indonesian identity cards
• Ijazah (Educational Certificate) Extraction: Extracts educational information from Indonesian certificates
• Multi-format Support: Handles both image files (JPEG, PNG) and PDF documents
• AI-Powered OCR: Uses OpenAI's GPT models for intelligent text extraction and data structuring
• RESTful API: Clean REST endpoints for easy integration
• Docker Support: Containerized application for easy deployment

Extracted Data

KTP (Indonesian ID Card)

• KTP ID number
• Full name
• Birth date and place
• Gender
• Blood type
• Address details (street, RT/RW, village, district)
• Religion
• Marital status
• Occupation
• Validity period
• Province and city
• Photo background color
• Photo resolution quality

Ijazah (Educational Certificate)

• Certificate number
• Education level (SD, SMP, SMA, SMK, MA, S1, S2, S3)
• School name
• School province and city
• Study program/major
• Graduation year
• Certificate date

API Documentation

For complete API documentation including detailed endpoint specifications, request/response schemas, and examples, please refer to the OpenAPI specification:

📋 View API Documentation

The API provides the following main endpoints:

• GET / - Home endpoint
• POST /ocr-ktp - Extract data from Indonesian ID cards (KTP)
• POST /ocr-ijazah - Extract data from educational certificates (Ijazah)

Base URL

http://localhost:5000

Installation

Prerequisites

• Python 3.11+
• OpenAI API key
• Docker (optional)

Local Installation

1. Clone the repository

git clone <repository-url>
cd gpt-ocr

2. Create virtual environment

python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

3. Install dependencies

pip install -r requirements.txt

4. Set up environment variables Create a .env file in the root directory:

OPENAI_API_KEY=your_openai_api_key_here
DEFAULT_LLM_MODEL=gpt-4-vision-preview
DATABASE_URL=sqlite:///instance/app.db
SECRET_KEY=your_secret_key_here
FLASK_ENV=development

5. Run the application

python run.py

The API will be available at http://localhost:5000

Docker Installation

1. Build the Docker image

docker build -t gpt-ocr .

2. Run the container

docker run -p 5000:5000 \
  -e OPENAI_API_KEY=your_openai_api_key_here \
  -e DEFAULT_LLM_MODEL=gpt-4-vision-preview \
  gpt-ocr

Configuration

Environment Variables

Variable	Description	Default
OPENAI_API_KEY	OpenAI API key for GPT models	Required
DEFAULT_LLM_MODEL	Default LLM model to use	gpt-4-vision-preview
DATABASE_URL	Database connection string	sqlite:///instance/app.db
SECRET_KEY	Flask secret key	Required
FLASK_ENV	Flask environment	development

Supported Models

• gpt-4-vision-preview (recommended for image analysis)
• gpt-4-turbo
• gpt-3.5-turbo

Quick Start

Using cURL

Extract KTP data:

curl -X POST http://localhost:5000/ocr-ktp \
  -H "Content-Type: application/json" \
  -d '{"image_url": "https://example.com/ktp.jpg"}'

Extract Ijazah data:

curl -X POST http://localhost:5000/ocr-ijazah \
  -H "Content-Type: application/json" \
  -d '{"image_url": "https://example.com/ijazah.pdf"}'

Using Python

import requests

# KTP extraction
response = requests.post('http://localhost:5000/ocr-ktp', 
                        json={'image_url': 'https://example.com/ktp.jpg'})
ktp_data = response.json()

# Ijazah extraction
response = requests.post('http://localhost:5000/ocr-ijazah', 
                        json={'image_url': 'https://example.com/ijazah.pdf'})
ijazah_data = response.json()

📖 For detailed API documentation, request/response schemas, and more examples, see docs/api_specs.yaml

Project Structure

gpt-ocr/
├── app/
│   ├── __init__.py              # Flask app initialization
│   ├── constant.py              # Application constants
│   ├── routes.py                # API route definitions
│   ├── utils.py                 # Utility functions
│   ├── handler/
│   │   └── llm_handler.py       # OpenAI LLM integration
│   ├── models/                  # Database models
│   ├── services/                # Business logic services
│   │   ├── home_service.py
│   │   └── ocr_service.py
│   ├── usecases/                # Use case implementations
│   │   └── ocr_use_case.py
│   └── templates/               # HTML templates
├── docs/
│   └── api_specs.yaml          # API documentation
├── instance/                   # Database files
├── requirements.txt            # Python dependencies
├── Dockerfile                  # Docker configuration
└── run.py                     # Application entry point

Error Handling

The API returns appropriate HTTP status codes and error messages:

• 200: Success
• 400: Bad Request (validation errors, invalid image URL)
• 500: Internal Server Error

For detailed error response schemas and examples, refer to the API documentation.

Limitations

• Requires valid OpenAI API key with sufficient credits
• Image quality affects extraction accuracy
• Currently optimized for Indonesian documents
• PDF processing converts to images (may lose some quality)
• Rate limits apply based on OpenAI API limits

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

License

This project is licensed under the MIT License.

Support

For issues and questions, please create an issue in the repository or contact the development team.