Usage

The usage module provides precise cost calculation using integer microcents to avoid floating-point precision errors in billing systems.

CostCalculator

fastroai.usage.CostCalculator

Token cost calculator with microcents precision.

Uses genai-prices for model pricing data, with support for custom pricing overrides. All costs are returned as integer microcents.

Supports cache tokens (90% cheaper on Anthropic) and audio tokens for accurate cost calculation with prompt caching and multimodal models.

1 microcent = 1/10,000 cent = 1/1,000,000 dollar

Examples:

calc = CostCalculator()

# Calculate cost for a request
cost = calc.calculate_cost("gpt-4o", input_tokens=1000, output_tokens=500)
print(f"Cost: {cost} microcents")
print(f"Cost: ${calc.microcents_to_dollars(cost):.6f}")

# With cache tokens (saves ~18% on this example)
cost = calc.calculate_cost(
    "claude-3-5-sonnet",
    input_tokens=250,
    output_tokens=150,
    cache_read_tokens=200,  # 200 of 250 input tokens were cached
)

# With custom pricing override (e.g., volume discount)
calc = CostCalculator(pricing_overrides={
    "gpt-4o": {"input_per_mtok": 2.00, "output_per_mtok": 8.00},
})

__init__(pricing_overrides=None)

Initialize calculator.

Parameters:

Name	Type	Description	Default
pricing_overrides	dict[str, dict[str, float]] | None	Custom pricing for specific models. Keys are model names, values are dicts with 'input_per_mtok', 'output_per_mtok', and optionally 'cache_read_per_mtok', 'cache_write_per_mtok' (dollars per million tokens). Use for volume discounts or custom models.	None

calculate_cost(model, input_tokens, output_tokens, *, cache_read_tokens=0, cache_write_tokens=0, input_audio_tokens=0, output_audio_tokens=0, cache_audio_read_tokens=0)

Calculate cost in microcents.

Supports cache tokens for accurate cost calculation when prompt caching is enabled. Cache read tokens are typically 90% cheaper on Anthropic.

Parameters:

Name	Type	Description	Default
model	str	Model identifier (e.g., "gpt-4o" or "openai:gpt-4o").	required
input_tokens	int	Number of input/prompt tokens (includes cached + uncached).	required
output_tokens	int	Number of output/completion tokens.	required
cache_read_tokens	int	Tokens read from prompt cache (typically 90% cheaper).	0
cache_write_tokens	int	Tokens written to prompt cache (typically 25% premium).	0
input_audio_tokens	int	Audio input tokens for multimodal models.	0
output_audio_tokens	int	Audio output tokens for multimodal models.	0
cache_audio_read_tokens	int	Audio tokens read from cache.	0

Returns:

Type	Description
int	Cost in microcents (integer). Returns 0 for unknown models.

Examples:

calc = CostCalculator()

# Basic usage
cost = calc.calculate_cost("gpt-4o", 1000, 500)
print(f"${calc.microcents_to_dollars(cost):.6f}")

# With cache tokens (more accurate cost)
cost = calc.calculate_cost(
    "claude-3-5-sonnet",
    input_tokens=250,
    output_tokens=150,
    cache_read_tokens=200,
)

microcents_to_dollars(microcents)

Convert microcents to dollars for display.

Use this only for display purposes. For calculations, always use integer microcents.

Parameters:

Name	Type	Description	Default
microcents	int	Cost in microcents.	required

Returns:

Type	Description
float	Cost in dollars (float).

Examples:

calc = CostCalculator()
dollars = calc.microcents_to_dollars(1_500_000)
print(f"${dollars:.2f}")  # $1.50

dollars_to_microcents(dollars)

Convert dollars to microcents.

Parameters:

Name	Type	Description	Default
dollars	float	Cost in dollars.	required

Returns:

Type	Description
int	Cost in microcents (integer).

Examples:

calc = CostCalculator()

# Set a budget of $0.10
budget = calc.dollars_to_microcents(0.10)
print(budget)  # 100000

format_cost(microcents)

Format cost in multiple representations.

Parameters:

Name	Type	Description	Default
microcents	int	Cost in microcents.	required

Returns:

Type	Description
dict[str, Any]	Dict with microcents, cents, and dollars representations.

Examples:

calc = CostCalculator()
formatted = calc.format_cost(1_500_000)

print(formatted)
# {
#     "microcents": 1500000,
#     "cents": 150,
#     "dollars": 1.5
# }

add_pricing_override(model, input_per_mtok, output_per_mtok, *, cache_read_per_mtok=None, cache_write_per_mtok=None)

Add or update pricing override for a model.

Use this for custom pricing (volume discounts) or models not in genai-prices.

Parameters:

Name	Type	Description	Default
model	str	Model identifier (will be normalized).	required
input_per_mtok	float	Input cost in dollars per million tokens.	required
output_per_mtok	float	Output cost in dollars per million tokens.	required
cache_read_per_mtok	float | None	Cache read cost (default: 10% of input, i.e. 90% discount).	None
cache_write_per_mtok	float | None	Cache write cost (default: 125% of input, i.e. 25% premium).	None

Examples:

calc = CostCalculator()

# Add volume discount pricing (20% off standard)
calc.add_pricing_override(
    model="gpt-4o",
    input_per_mtok=2.00,   # Standard is $2.50
    output_per_mtok=8.00,  # Standard is $10.00
)

# Add custom model with explicit cache pricing
calc.add_pricing_override(
    model="my-cached-model",
    input_per_mtok=3.00,
    output_per_mtok=15.00,
    cache_read_per_mtok=0.30,   # 90% discount
    cache_write_per_mtok=3.75,  # 25% premium
)

---

← Tools Tracing →