AI-Assisted Postcard Cataloguing with Gemini Batch API

Python workflow for high-volume postcard image analysis and metadata tagging using the Gemini Batch API.

The script processes postcard image pairs in a fixed order:

• Image 1: postcard back
• Image 2: postcard front

It uses text and visual clues from both images to generate one cleaned, comma-separated tag line for each postcard record.

Project Purpose

This project was created to support a high-volume digital cataloguing workflow.

It automates repetitive stages of postcard processing:

• Uploading image pairs
• Submitting batch requests to Gemini
• Generating consistent tags and metadata
• Monitoring asynchronous batch jobs
• Downloading and saving results
• Separating successful results from errors
• Preparing outputs for manual visual verification and catalogue publication

Features

• Processes JPG, JPEG, PNG, WEBP, TIF and TIFF files
• Pairs images sequentially: back first, front second
• Uses the Gemini Batch API for asynchronous large-scale processing
• Builds a JSONL request file with one request per postcard
• Uses detailed prompt rules for OCR clues, location identification and image analysis
• Generates English uppercase tags in a consistent order
• Normalises generic non-English location descriptors
• Removes duplicate, generic and redundant tags
• Identifies black-and-white or sepia images using the front image only
• Saves a batch-job manifest for later monitoring
• Supports separate submit, watch, download and run modes
• Saves raw JSONL results, individual cleaned TXT outputs and error records
• Retries result downloads if an empty response is returned

Technologies

• Python
• Google Gen AI SDK
• Gemini API
• Gemini Batch API
• Prompt engineering
• JSONL
• Batch image processing

Requirements

• Python 3.10 or newer
• A Gemini API key
• Google Gen AI Python SDK

Install the required package:

pip install google-genai

API Key Setup

Set one of these environment variables before running the script.

PowerShell:

$env:GEMINI_API_KEY="your_api_key"

Or:

$env:GOOGLE_API_KEY="your_api_key"

Do not place API keys directly in the Python file or upload them to GitHub.

Folder Structure

project-folder/
│
├── assets_gemini_API_batch.py
├── README.md
├── requirements.txt
├── .gitignore
├── input/     # Local input images, not included in the repository
└── output/    # Generated results, not included in the repository

Input Rules

Place image files inside the input folder.

Images are sorted alphabetically and processed in pairs:

001_back.jpg
001_front.jpg
002_back.jpg
002_front.jpg

The first image in each pair is treated as the postcard back, and the second as the postcard front.

If the folder contains an odd number of images, the final unpaired image is skipped and a warning is displayed.

Usage

Run the complete workflow: submit the batch job, monitor it and download results.

python assets_gemini_API_batch.py run

Use custom input and output folders:

python assets_gemini_API_batch.py run `
  --folder "C:\path\to\input" `
  --output "C:\path\to\output"

Submit a job only:

python assets_gemini_API_batch.py submit

Monitor an existing job using the saved manifest:

python assets_gemini_API_batch.py watch

Download a completed job:

python assets_gemini_API_batch.py download

Change the model or polling interval:

python assets_gemini_API_batch.py run `
  --model "gemini-2.5-flash" `
  --poll-seconds 30

Output Files

The output directory can contain:

batch_job.json
postcards_batch_requests.jsonl
batch_results.jsonl
batch_errors.jsonl
POSTCARD_001_example.txt
POSTCARD_002_example.txt

• batch_job.json stores batch job information for monitoring and download.
• postcards_batch_requests.jsonl contains the generated batch requests.
• batch_results.jsonl contains raw API results.
• batch_errors.jsonl contains records that returned an error instead of a response.
• POSTCARD_*.txt files contain cleaned tag output for each processed postcard.

Example Output

ILLUSTRATION, EXAMPLE LOCATION, CHURCH, B/W, POSTCARD, EXAMPLE COUNTRY

Prompt Design

The workflow contains a detailed system prompt designed for reliable metadata output.

It instructs the model to:

• Use the postcard back for OCR, postmarks, stamps, postal codes and printed captions
• Use the front for place identification, landmarks, objects and artistic medium
• Cross-check visual and textual evidence
• Prefer specific tags over generic tags
• Remove duplicates and redundant geographic terms
• Translate generic non-English descriptors into English where appropriate
• Return only a single comma-separated tag line

The complete prompt configuration is included in the Python script.

Privacy and Data Handling

This repository does not include source images, production metadata, API keys, real batch-job files or API outputs.

The script sends input images to the Gemini API. Review applicable API terms, data-handling settings and privacy requirements before processing sensitive or personal material.

Portfolio Context

This project demonstrates a practical AI-assisted workflow for high-volume image cataloguing: batch processing, multimodal analysis, prompt design, metadata generation, job monitoring, result cleaning and manual-validation support.