Cost Calculator | BetterAI Docs

Source: src/image_generation/cost_calculator/cost_calculator.py. This page's original notebook was empty; the content was written from the code.

#Overview

The CostCalculator class takes a price table in the constructor (by default, PricingTable; see Pricing Table) and offers two methods: merge_cost_information and calculate.

#merge_cost_information

Sums prompt_tokens, output_tokens and total_tokens from a list of usage records, used when a generation makes several calls to the model.

Minimum of two records. With an empty list or with fewer than two items, the method raises ValueError ("You must provide at least two cost_information objects."). PayloadBuilder only calls it when there is more than one record.

#calculate

Parameter	Type	Description
`model`	`str`	Model used, looked up in `PricingTable`.
`prompt_tokens`	`int`	Input tokens.
`output_tokens`	`int`	Output tokens.
`total_tokens`	`int`	Total tokens. It is only passed through to the result; it does not enter the calculation.
`num_images`	`int`	Number of images (default `0`).
`cached_prompt_tokens`	`int`	Input tokens read from the cache (default `0`).
`cache_storage_tokens`	`int`	Tokens kept in the cache (default `0`).
`cache_storage_hours`	`float`	Hours of cache storage (default `0.0`).

#Formulas

Item	Calculation
Input	`prompt_tokens / 1_000_000 * input_per_million_tokens`
Output	`output_tokens / 1_000_000 * output_per_million_tokens`, only if the price and the tokens are non-zero
Images	`num_images * image_price_per_unit`, only if the price and the quantity are non-zero
Input cache	`cached_prompt_tokens / 1_000_000 * cache_input_per_million_tokens`
Cache storage	`cache_storage_tokens / 1_000_000 * cache_storage_per_million_tokens_per_hour * cache_storage_hours`

The total is the sum of the five items.

#Return value

A dictionary with the tokens received and the dollar values rounded to 6 decimal places:

{
  "prompt_tokens": 1174,
  "output_tokens": 2633,
  "total_tokens": 3807,
  "prompt_usd": 0.000352,
  "output_usd": 0.0,
  "images_usd": 0.078,
  "total_usd": 0.078352
}

#Usage example

from src.image_generation.cost_calculator.cost_calculator import CostCalculator

calculator = CostCalculator()

# Calculate the cost of two images generated with gemini-2.5-flash-image
cost = calculator.calculate(
    model="gemini-2.5-flash-image",
    prompt_tokens=1174,
    output_tokens=2633,
    total_tokens=3807,
    num_images=2,
)
print(cost["total_usd"])

#Notes

Model without a price. If the model is not in PricingTable, PricingTable.get raises ValueError ("Modelo sem precificação cadastrada") and the generation fails while building the payloads.