# How Headroom Handles Image Compression for LLM Vision Inputs

> Discover how Headroom optimizes image compression for LLM vision inputs, slashing token costs by up to 90% without quality loss using its innovative tile optimizer.

- Repository: [Tejas Chopra/headroom](https://github.com/chopratejas/headroom)
- Tags: how-to-guide
- Published: 2026-06-12

---

**Headroom reduces token costs for vision-enabled LLMs by applying a tile optimizer that splits images into model-specific token budgets, cutting usage by 40-90% without quality loss.**

Headroom is an open-source proxy that optimizes API calls to large language models. Understanding how Headroom handles image compression for LLM vision inputs reveals a sophisticated approach to token management that preserves visual fidelity while significantly reducing costs.

## Token-Aware Optimization Architecture

The compression pipeline begins with estimating token consumption before transmitting the image to the provider. In [`headroom/image/tile_optimizer.py`](https://github.com/chopratejas/headroom/blob/main/headroom/image/tile_optimizer.py), the system calculates token counts using model-specific formulas embedded in the source code. For Anthropic Claude, the implementation approximates tokens as `(width × height) / 750`, while OpenAI GPT-4o uses the provider's specific token estimation logic defined in the optimizer class.

This estimation allows Headroom to predict costs accurately and determine whether compression is necessary before the image ever reaches the LLM API.

## Tile-Level Processing Strategy

When estimated tokens exceed configurable thresholds, Headroom employs an intelligent tiling approach. The optimizer splits images into smaller tiles that align with the model's token constraints while maintaining what the codebase describes as **"zero quality loss"**—the original image can be perfectly reconstructed from the processed tiles.

This tile-based method preserves all visual information while ensuring each segment fits within the API's token limits, preventing automatic truncation or request errors.

## Compression Decision Logic

The module [`headroom/proxy/image_compression_decision.py`](https://github.com/chopratejas/headroom/blob/main/headroom/proxy/image_compression_decision.py) orchestrates whether to optimize, preserve, or downscale an image. The decision routine evaluates three primary criteria:

- **Model capabilities**: The system checks `supports_vision` flags in [`headroom/models/registry.py`](https://github.com/chopratejas/headroom/blob/main/headroom/models/registry.py) to verify the target model accepts vision inputs
- **Token budgets**: Comparison of estimated tokens against configured limits for the specific provider
- **Configuration overrides**: Request-specific flags that can force compression on or off regardless of the default behavior

## Proxy Integration and Request Handling

When requests reach the Headroom proxy, the system inspects the `messages` payload for `image_url` entries. Upon detecting base64-encoded images or external URLs, the proxy invokes `decide_image_compression()` and transparently replaces the original image data with optimized tiles before forwarding the request to downstream LLMs.

This integration works automatically for standard OpenAI-formatted chat requests containing vision inputs, requiring no changes to the client application logic.

## Implementation Examples

### Direct Tile Optimization

Use the `TileOptimizer` class directly when you need programmatic control over image splitting:

```python
from headroom.image.tile_optimizer import TileOptimizer

# Example image dimensions (width, height)

width, height = 2048, 1536

optimizer = TileOptimizer()

# Returns a list of tiles that fit the token budget for GPT‑4o

tiles = optimizer.optimize(width, height, model="gpt-4o")
print(f"Generated {len(tiles)} tiles to stay under token limit")

```

### Proxy-Level Automatic Compression

For transparent optimization at the proxy layer, process the full request payload:

```python
import json
from headroom.proxy.image_compression_decision import decide_image_compression

# Simulated OpenAI chat request payload

payload = {
    "model": "gpt-4o",
    "messages": [
        {
            "role": "user",
            "content": [
                {"type": "image_url",
                 "image_url": {"url": "data:image/png;base64,iVBORw0KGgo..."}}
            ],
        }
    ],
}

# The proxy will replace the image with optimized tiles if needed

compressed_payload = decide_image_compression(payload)
print(json.dumps(compressed_payload, indent=2))

```

## Summary

- Headroom estimates token usage using model-specific formulas in [`headroom/image/tile_optimizer.py`](https://github.com/chopratejas/headroom/blob/main/headroom/image/tile_optimizer.py) before transmitting images to LLMs
- The system splits oversized images into tiles that maintain perfect reconstruction capability while reducing token counts by 40-90%
- Compression decisions in [`headroom/proxy/image_compression_decision.py`](https://github.com/chopratejas/headroom/blob/main/headroom/proxy/image_compression_decision.py) factor in model capabilities from the registry, token budgets, and configuration flags
- The proxy automatically intercepts `image_url` entries in request payloads and replaces them with optimized versions transparently

## Frequently Asked Questions

### How does Headroom calculate vision tokens for different models?

Headroom applies model-specific formulas defined in the source code. For Anthropic Claude, the calculation uses `(width × height) / 750`, while OpenAI GPT-4o uses the specific token estimation logic implemented in [`headroom/image/tile_optimizer.py`](https://github.com/chopratejas/headroom/blob/main/headroom/image/tile_optimizer.py). These formulas allow the system to predict API costs before sending the actual request.

### Does Headroom's image compression reduce image quality?

No. Headroom uses a tile-based approach that achieves "zero quality loss" according to the codebase. The original image can be perfectly reconstructed from the tiles, preserving all visual information while fitting within the model's token constraints. This differs from traditional lossy compression algorithms.

### Which models support vision compression in Headroom?

Headroom checks the `supports_vision` flag in [`headroom/models/registry.py`](https://github.com/chopratejas/headroom/blob/main/headroom/models/registry.py) to determine eligibility for each model. The system currently supports OpenAI GPT-4o and Anthropic Claude among other vision-capable models listed in the registry, applying provider-specific logic for each.

### Can I disable image compression for specific requests?

Yes. The [`headroom/proxy/image_compression_decision.py`](https://github.com/chopratejas/headroom/blob/main/headroom/proxy/image_compression_decision.py) module respects configuration flags that can force compression on or off for individual requests. This allows granular control when you need to guarantee original image quality or when working with images that already fall within token limits.