API Documentation

Learn how to integrate OCR and MRZ scanning capabilities into your applications.

For detailed API specifications, please refer to our OpenAPI Documentation .

System Architecture

						flowchart TB
						subgraph Client
							UI[API]
							OCR_UI[OCR]
							MRZ_UI[MRZ Scanner]
							ADMIN[Admin Dashboard]
						end
						subgraph API[FastAPI Backend]
							AUTH[Authentication]
							OCR_API[OCR API]
							MRZ_API[MRZ API]
							ADMIN_API[Admin API]
							
							subgraph Processing
								TESS[OCR Engine]
								TIKA[PDF Processor]
								MRZ_PROC[MRZ Processor]
								IMG_PROC[Image Processor]
							end
						end
						subgraph Database
							USERS[(Users)]
							API_KEYS[(API Keys)]
							RATE_LIMITS[(Rate Limits)]
							MODEL_PRICES[(Model Prices)]
						end
						UI --> OCR_UI & MRZ_UI
						OCR_UI --> |Upload Image/PDF| OCR_API
						MRZ_UI --> |Upload Passport/ID| MRZ_API
						
						OCR_API --> |Validate| AUTH
						MRZ_API --> |Validate| AUTH
						AUTH --> |Check| API_KEYS
						API_KEYS --> |Track| RATE_LIMITS
						
						OCR_API --> |PDF| TIKA
						TIKA --> |Extracted Images| TESS
						OCR_API --> |Image| TESS
						MRZ_API --> IMG_PROC
						IMG_PROC --> MRZ_PROC
						MRZ_PROC --> TESS
						
						ADMIN --> ADMIN_API
						ADMIN_API --> MODEL_PRICES
						ADMIN_API --> USERS
						
						classDef frontend fill:#f0f9ff,stroke:#0ea5e9,stroke-width:2px
						classDef api fill:#e0f2fe,stroke:#0ea5e9,stroke-width:2px
						classDef process fill:#f0fdf4,stroke:#22c55e,stroke-width:2px
						classDef db fill:#fee2e2,stroke:#ef4444,stroke-width:2px
						
						class UI,OCR_UI,MRZ_UI,ADMIN frontend
						class AUTH,OCR_API,MRZ_API,ADMIN_API api
						class TESS,TIKA,MRZ_PROC,IMG_PROC process
						class USERS,API_KEYS,RATE_LIMITS,MODEL_PRICES db

Authentication

All API requests require an API key to be included in the X-API-Key header.

X-API-Key: your_api_key_here

OCR API

Extract text from images and PDF documents.

POST /api/v1/ocr

Parameters:

include_boxes (optional): boolean - Include text bounding boxes
model (optional): string - OCR model(s) to use (e.g., 'eng', 'eng+khm')

Python Example

import requests

api_key = 'your_api_key_here'
file_path = 'document.jpg'

with open(file_path, 'rb') as f:
    files = {'file': f}
    headers = {'X-API-Key': api_key}
    params = {
        'include_boxes': True,
        'model': 'eng'
    }
    
    response = requests.post(
        '/api/v1/ocr',
        files=files,
        headers=headers,
        params=params
    )
    
    if response.status_code == 200:
        result = response.json()
        print(f"Extracted text: {result['text']}")
        print(f"Processing time: {result['processing_time']}s")

Node.js Example

const FormData = require('form-data');
const fs = require('fs');
const axios = require('axios');

async function extractText() {
    const apiKey = 'your_api_key_here';
    const filePath = 'document.jpg';
    
    const form = new FormData();
    form.append('file', fs.createReadStream(filePath));
    
    try {
        const response = await axios.post(
            '/api/v1/ocr',
            form,
            {
                headers: {
                    'X-API-Key': apiKey,
                    ...form.getHeaders()
                },
                params: {
                    include_boxes: true,
                    model: 'eng'
                }
            }
        );
        
        console.log('Extracted text:', response.data.text);
        console.log('Processing time:', response.data.processing_time, 's');
    } catch (error) {
        console.error('Error:', error.response?.data || error.message);
    }
}

extractText();

cURL Example

curl -X POST \
  '/api/v1/ocr?include_boxes=true&model=eng' \
  -H 'X-API-Key: your_api_key_here' \
  -F 'file=@document.jpg'

MRZ API

Extract Machine Readable Zone (MRZ) data from passport and ID card images.

POST /api/v1/mrz

Supports both TD1 (ID cards) and TD3 (Passports) formats.

Python Example

import requests

api_key = 'your_api_key_here'
file_path = 'passport.jpg'

with open(file_path, 'rb') as f:
    files = {'file': f}
    headers = {'X-API-Key': api_key}
    
    response = requests.post(
        '/api/v1/mrz',
        files=files,
        headers=headers
    )
    
    if response.status_code == 200:
        result = response.json()
        mrz_data = result['mrz_data']
        print(f"Document Type: {mrz_data['document_type']}")
        print(f"Country: {mrz_data['country']}")
        print(f"Document Number: {mrz_data['document_number']}")
        print(f"Name: {mrz_data['name']}")
        print(f"Surname: {mrz_data['surname']}")
        print(f"Nationality: {mrz_data['nationality']}")
        print(f"Birth Date: {mrz_data['birth_date']}")
        print(f"Sex: {mrz_data['sex']}")
        print(f"Expiry Date: {mrz_data['expiry_date']}")
        print(f"Processing time: {result['processing_time']}s")

Node.js Example

const FormData = require('form-data');
const fs = require('fs');
const axios = require('axios');

async function extractMRZ() {
    const apiKey = 'your_api_key_here';
    const filePath = 'passport.jpg';
    
    const form = new FormData();
    form.append('file', fs.createReadStream(filePath));
    
    try {
        const response = await axios.post(
            '/api/v1/mrz',
            form,
            {
                headers: {
                    'X-API-Key': apiKey,
                    ...form.getHeaders()
                }
            }
        );
        
        const { mrz_data } = response.data;
        console.log('Document Type:', mrz_data.document_type);
        console.log('Country:', mrz_data.country);
        console.log('Document Number:', mrz_data.document_number);
        console.log('Name:', mrz_data.name);
        console.log('Surname:', mrz_data.surname);
        console.log('Nationality:', mrz_data.nationality);
        console.log('Birth Date:', mrz_data.birth_date);
        console.log('Sex:', mrz_data.sex);
        console.log('Expiry Date:', mrz_data.expiry_date);
        console.log('Processing time:', response.data.processing_time, 's');
    } catch (error) {
        console.error('Error:', error.response?.data || error.message);
    }
}

extractMRZ();

cURL Example

curl -X POST \
  '/api/v1/mrz' \
  -H 'X-API-Key: your_api_key_here' \
  -F 'file=@passport.jpg'