OpenAI API Image Token Counter

A comprehensive Python package for calculating token costs when using images with OpenAI's Vision API. Supports all OpenAI vision models including GPT-4.1, GPT-4o, o-series, and GPT Image 1.

🚀 Features

• Complete Model Support: All OpenAI vision models (GPT-4.1, GPT-4o, o-series, GPT Image 1)
• Accurate Calculations: Implements official OpenAI token calculation algorithms
• Flexible Input: Calculate from file paths, image dimensions, or raw image data
• Batch Processing: Process multiple images or entire directories
• CLI Interface: Easy-to-use command-line tool
• Cost Estimation: Estimate USD costs based on token pricing
• Configurable: Easy-to-update configuration via MDX file
• Comprehensive Testing: Full test suite covering all documented examples

📦 Installation

pip install openai-image-token-counter

Development Installation

git clone https://github.com/edujbarrios/openai-image-token-counter.git
cd openai-image-token-counter
pip install -e .

🏃 Quick Start

Python API

from openai_image_token_counter import OpenAIImageTokenCalculator, ModelType, DetailLevel

# Initialize calculator
calculator = OpenAIImageTokenCalculator()

# Calculate tokens from image file
tokens = calculator.calculate_tokens_from_file(
    "my_image.jpg", 
    model=ModelType.GPT_4O,
    detail=DetailLevel.HIGH
)
print(f"Tokens required: {tokens}")

# Calculate from dimensions
tokens = calculator.calculate_tokens(
    width=1024, 
    height=1024, 
    model="gpt-4o"
)
print(f"Tokens for 1024x1024 image: {tokens}")

# Batch processing for different images
image_files = ["img1.jpg", "img2.png", "img3.gif"]
token_counts = calculator.calculate_batch_tokens(
    image_files, 
    model=ModelType.GPT_4O
)

# OPTIMIZED: Batch processing for same-resolution images (much faster!)
batch_result = calculator.calculate_batch_same_resolution(
    count=1000,          # Number of images
    width=1024,          # All images are 1024px wide
    height=1024,         # All images are 1024px tall
    model="gpt-4o"
)
print(f"1000 images at 1024x1024: {batch_result['total_tokens']:,} tokens")
print(f"Per image: {batch_result['tokens_per_image']} tokens")

# Batch processing with cost estimation
cost_result = calculator.calculate_batch_same_resolution_with_cost(
    count=500,
    width=512, 
    height=512,
    model="gpt-4o",
    input_token_price_per_million=5.0  # $5 per million tokens
)
print(f"Total cost for 500 images: ${cost_result['total_cost_usd']:.2f}")

Command Line Interface

# Calculate tokens for a single image
openai-image-tokens image.jpg --model gpt-4o

# Process multiple images
openai-image-tokens *.jpg --model gpt-4.1-mini --detail low

# Process entire directory
openai-image-tokens --directory ./images --model gpt-4o --recursive

# Calculate from dimensions
openai-image-tokens --dimensions 1920 1080 --model o4-mini

# Estimate costs
openai-image-tokens image.jpg --model gpt-4o --price-per-million 5.0

# List supported models
openai-image-tokens --list-models

🧮 Supported Models

32px Patch Models (GPT-4.1/o4-mini family)

• gpt-5-mini (multiplier: 1.62)
• gpt-5-nano (multiplier: 2.46)
• gpt-4.1-mini (multiplier: 1.62)
• gpt-4.1-nano (multiplier: 2.46)
• o4-mini (multiplier: 1.72)

512px Tile Models (GPT-4o/o-series family)

• gpt-5 (base: 70, tile: 140)
• gpt-5-chat-latest (base: 70, tile: 140)
• gpt-4o (base: 85, tile: 170)
• gpt-4.1 (base: 85, tile: 170)
• gpt-4.5 (base: 85, tile: 170)
• gpt-4o-mini (base: 2833, tile: 5667)
• o1 (base: 75, tile: 150)
• o1-pro (base: 75, tile: 150)
• o3 (base: 75, tile: 150)
• computer-use-preview (base: 65, tile: 129)

Special Models

• gpt-image-1 (with fidelity bonuses)

🧪 Calculation Examples

Example 1: 1024x1024 Image (GPT-4o)

calculator = OpenAIImageTokenCalculator()
tokens = calculator.calculate_tokens(1024, 1024, "gpt-4o", DetailLevel.HIGH)
# Result: 765 tokens
# Calculation: 4 tiles of 512px → 85 + (4 × 170) = 765

Example 2: 1800x2400 Image (GPT-4.1-mini)

tokens = calculator.calculate_tokens(1800, 2400, "gpt-4.1-mini")
# Result: 2352 tokens  
# Calculation: Scaled to 1452 base tokens × 1.62 multiplier = 2352

Example 3: Batch Processing for Dataset

# Perfect for ML datasets where all images are preprocessed to same size
from openai_image_token_counter import calculate_batch_same_resolution, quick_batch_cost_estimate

# Calculate for 10,000 training images at 224x224
result = calculate_batch_same_resolution(10000, 224, 224, "gpt-4o")
print(f"Training set: {result['total_tokens']:,} tokens")

# Estimate cost for inference on 50,000 images at 512x512
cost_info = quick_batch_cost_estimate(50000, 512, 512, "gpt-4o", 5.0)
print(f"Inference cost: ${cost_info['total_cost_usd']:.2f}")

Example 4: GPT Image 1 with High Fidelity

from openai_image_token_counter import FidelityLevel

tokens = calculator.calculate_tokens(
    1024, 2048, 
    "gpt-image-1", 
    fidelity=FidelityLevel.HIGH
)
# Includes fidelity bonus for rectangular image

Example 5: Comparing Costs Across Models

# Compare costs for the same batch across different models
models = ["gpt-4o", "gpt-4.1-mini", "o4-mini"]
image_count = 1000
width, height = 1024, 1024

for model in models:
    result = calculate_batch_same_resolution(image_count, width, height, model)
    print(f"{model}: {result['total_tokens']:,} tokens ({result['tokens_per_image']} per image)")

📊 CLI Usage Examples

Basic Usage

# Single image
openai-image-tokens photo.jpg --model gpt-4o

Batch Processing

# Multiple specific files
openai-image-tokens img1.jpg img2.png img3.gif --model gpt-4o

# Entire directory
openai-image-tokens --directory ./photos --model gpt-4o --recursive

# Specific file types
openai-image-tokens --directory ./photos --extensions .jpg .png --model gpt-4o

# OPTIMIZED: Same resolution batch (much faster!)
openai-image-tokens --batch-same-resolution 1000 1024 1024 --model gpt-4o

# Large batch with different models
openai-image-tokens --batch-same-resolution 5000 512 512 --model gpt-4.1-mini
openai-image-tokens --batch-same-resolution 10000 256 256 --model o4-mini

Output Formats

# JSON output
openai-image-tokens image.jpg --model gpt-4o --format json

# CSV output  
openai-image-tokens --directory ./images --format csv --output results.csv

# Detailed table
openai-image-tokens image.jpg --model gpt-4o --verbose

Cost Estimation

# Estimate costs (price per million tokens)
openai-image-tokens image.jpg --model gpt-4o --price-per-million 5.0

# Batch cost estimation
openai-image-tokens --directory ./images --model gpt-4o --price-per-million 5.0

🔄 Model Algorithm Overview

32px Patch Models

1. Calculate patches: ceil(width/32) × ceil(height/32)
2. If > 1536 patches, scale down maintaining aspect ratio
3. Apply model-specific multiplier

512px Tile Models

1. Low detail: Return base tokens only
2. High detail:
   • Scale to fit 2048×2048 if needed
   • Scale shortest side to 768px
   • Count 512px tiles
   • Calculate: base_tokens + (tiles × tile_tokens)

GPT Image 1

• Similar to 512px tile models but shortest side scaled to 512px
• High fidelity adds bonus: 4160 (square) or 6240 (rectangular)

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• Based on official OpenAI Vision API documentation
• Calculation algorithms verified against OpenAI's examples
• Inspired by the need for accurate cost estimation in AI applications

Note: This package implements the token calculation algorithms as documented by OpenAI. Always verify costs with the official OpenAI pricing page before making financial decisions.

Author

Eduardo J. Barrios - https://edujbarrios.com