Image token cost documentation is ambiguous across models (BASE/TILE vs PATCH×MULTIPLIER)

[anasselbasra]

Confirm this is a feature request for the Python library and not the underlying OpenAI API.

• This is a feature request for the Python library

Describe the feature or improvement you're requesting

Hi OpenAI team,
I’d like to report a documentation issue regarding image token accounting, which is currently ambiguous and can easily lead to incorrect cost estimation in production.
Problem
The Images & Vision documentation mixes two different image cost mechanisms across sections, without clearly stating which models each mechanism applies to:

BASE / TILE system

1. Uses detail: low | high
2. low → fixed base tokens
3. high → base tokens + tiles × tile tokens
4. Applies to models like GPT-4o, GPT-4.1, GPT-5, etc.

PATCH × MULTIPLIER system

1. Uses patch-based calculation (ceil(w/32) × ceil(h/32))
2. Multiplied by a model-specific multiplier
3. Applies to models like GPT-5-mini / GPT-5-nano

These two systems are described in different sections, but the documentation does not explicitly state the model scope for each, which creates confusion.

Concrete example

The statement: “Using detail: low lets the model process the image with a budget of ~85 tokens.”
appears to be written as a general rule, while it is actually:

1. true for GPT-4o-class models,
2. false for models like 4o-mini or GPT-5-mini, which follow different accounting rules.

As a result, developers may assume a fixed low-detail cost when in reality the cost is model-dependent or resolution-dependent.

Why this matters
This is not just a wording issue:

1. it affects cost predictability,
2. it can cause unexpected billing behavior in production,
3. and it forces developers to reverse-engineer pricing rules instead of relying on the docs.

Suggested improvement

It would greatly improve clarity if: each image cost formula explicitly listed the exact models it applies to, or the documentation clearly separated sections by cost system, not just by feature.

Thanks for your work, this feedback is shared in the spirit of making an already powerful API easier and safer to use at scale.

Additional context

No response

[miguelmanlyx]

@anasselbasra This could be a Cost / Tokens issue. Have you already run npx ai-patch doctor to sanity-check token usage and common causes of sudden cost spikes?

[anasselbasra]

@miguelmanlyx
Thanks for the suggestion.
This isn’t a Cost / Tokens issue in the sense of a sudden spike or misuse in an application, and that’s why I didn’t use such a label (I couldn’t find it either on this repo).
The issue here is documentation ambiguity, not incorrect API usage: different image token accounting systems are described (BASE/TILE vs PATCH×MULTIPLIER), but the docs don’t clearly state which models each system applies to, which makes it hard to predict costs before running empirical tests.
Tools like npx ai-patch doctor are useful for diagnosing unexpected spikes or misconfigurations in an app, but they don’t address the core problem here: understanding which pricing rules apply to which vision models ahead of time.
That’s the clarification I’m hoping to get improved in the documentation.