pictoken

Calculate image tokens for Azure OpenAI models. This utility helps resize images to minimize token usage. Unlike openai/tiktoken, it isn't a tokenizer but calculates image tokens for specific requests. It supports OpenAI models such as gpt-4o-mini and gpt-4o.

Based on calculation costs for vision capabilities for OpenAI models. In the future models from other providers might be supported as well.

Installation

Requires Python 3.9 or later.

pip install pictoken

Usage

Calculate image tokens

You can provide images in two main ways: by passing a link to the image or by passing the base64 encoded image directly in the request.

Please note that passing the model is required, as the image token calculation is model-specific. The dollar price per image is the same for GPT-4o and GPT-4o mini. To maintain this, GPT-4o mini uses more tokens per image.. These additional tokens are only used for billing purposes and do not affect the context limit of the model.

By image

import pictoken

image_tokens_from_url = pictoken.calculate_image_tokens_by_image(image="http://", model="gpt-4o-mini")
image_tokens_from_base64 = pictoken.calculate_image_tokens_by_image(image="data:image/png;base64,...", model="gpt-4o-mini")

By image dimensions

import pictoken

image_tokens = pictoken.calculate_image_tokens_by_image_dimensions(
    width=2048, height=2048, model=pictoken.Model.GPT_4O, detail=pictoken.ImageDetail.HIGH
)

print(image_tokens)
# Response(total_tokens=765, base_tokens=85, tile_tokens=680, total_tiles=4, width_tiles=2, height_tiles=2, resized=ResizedImage(width=768, height=768))

Resize images

For low res mode, OpenAI expects a 512px x 512px image. For high res mode, the short side of the image should be less than 768px and the long side should be less than 2,000px. The latency of the model can also be improved by downsizing your images ahead of time to be less than the maximum size they are expected them to be.

#TODO

Add visual metadata to image

The model doesn't process original file names or metadata, and images are resized before analysis, affecting their original dimensions. This utility adds a small text overlay to the image. This can be useful for models to reference to the specific image in a request with multiple images.

#TODO

Development

Contributions are welcome. This packages uses uv for dependency management and packaging. If you use Visual Studio Code with Docker or GitHub CodeSpaces, you can leverage the included devcontainer. This will install all required dependencies and tools and has the right Python version available. Easy!

To manually set up the development environment, make sure you have uv installed and run uv sync to install all dependencies.

License

MIT