modelpricing-ai 2026.7.0

Python client for ModelPricing.ai cost estimates and tracking

modelpricing-ai

Python client for the ModelPricing.ai API — estimate LLM usage costs and track spending with a single call.

Installation

pip install modelpricing-ai

For async support (requires aiohttp):

pip install modelpricing-ai[async]

Quick Start

from modelpricing_ai import ModelPricingClient

with ModelPricingClient(api_key="YOUR_API_KEY") as client:
    estimate = client.estimate(
        model="claude-haiku-4-5-20251001",
        tokens_in=1000,
        tokens_out=500,
        trace_id={"requestId": "abc-123"},
    )
    print(f"Cost: ${estimate.total:.6f}")

From a provider SDK response

If you already have a response object from the Anthropic or OpenAI SDK, pass it directly — the client pulls the model name and token counts for you. Works with Anthropic Messages, OpenAI Chat Completions, and OpenAI Responses API (Pydantic objects or plain dicts).

from anthropic import Anthropic
from modelpricing_ai import ModelPricingClient

anthropic = Anthropic()
response = anthropic.messages.create(
    model="claude-haiku-4-5-20251001",
    max_tokens=1024,
    messages=[{"role": "user", "content": "hello"}],
)

with ModelPricingClient(api_key="YOUR_API_KEY") as client:
    estimate = client.estimate_from_response(response)
    print(f"Cost: ${estimate.total:.6f}")

from openai import OpenAI
from modelpricing_ai import ModelPricingClient

openai = OpenAI()
response = openai.chat.completions.create(
    model="gpt-4o-mini",
    messages=[{"role": "user", "content": "hello"}],
)

with ModelPricingClient(api_key="YOUR_API_KEY") as client:
    estimate = client.estimate_from_response(response)

The async client exposes the same method: await client.estimate_from_response(response).

Cache tokens

Cache metrics are additive: tokens_in contains only fresh, non-cached input. Pass generic OpenAI writes separately from Anthropic's TTL-specific writes:

estimate = client.estimate(
    model="gpt-5.6-terra",
    tokens_in=10_000,
    tokens_out=1_000,
    cache_read_tokens=2_000,
    cache_write_tokens=5_000,
)

estimate_from_response() extracts OpenAI cached_tokens and cache_write_tokens automatically. For Anthropic, it extracts cache reads and the 5-minute/1-hour write buckets into cache_write_5m_tokens and cache_write_1h_tokens.

Async Usage

Install the async extra, then use AsyncModelPricingClient as an async context manager:

import asyncio
from modelpricing_ai import AsyncModelPricingClient

async def main():
    async with AsyncModelPricingClient(api_key="YOUR_API_KEY") as client:
        estimate = await client.estimate(
            model="claude-haiku-4-5-20251001",
            tokens_in=1000,
            tokens_out=500,
            trace_id={"requestId": "abc-123"},
        )
        print(f"Cost: ${estimate.total:.6f}")

asyncio.run(main())

Response Structure

All estimate methods (estimate, estimate_from_response, and their async counterparts) return an EstimateResponse object:

estimate.total        # float — total USD cost
estimate.model        # str   — canonical model name
estimate.traceId      # dict | None — your pass-through trace ID
estimate.breakdown    # EstimateBreakdownGroup
  .input              # EstimateBreakdown
    .unit             #   str   — e.g. "token"
    .branch           #   str   — pricing tier that matched
    .qty              #   int   — number of input tokens
    .rate             #   float — per-unit rate
    .subtotal         #   float — input cost
  .output             # EstimateBreakdown (same fields for output tokens)

Configuration

Parameter	Default	Description
api_key	required	Your ModelPricing.ai API key (also reads MODELPRICING_API_KEY env var)
base_url	"https://api.modelpricing.ai"	API base URL (also reads MODELPRICING_BASE_URL env var)
timeout	30.0	Request timeout in seconds
max_retries	3	Maximum retry attempts for transient errors
session	None	Optional requests.Session (sync) or aiohttp.ClientSession (async)

Parameters are resolved in order: constructor argument > environment variable > default.

client = ModelPricingClient(
    api_key="YOUR_API_KEY",
    base_url="https://api.modelpricing.ai",
    timeout=30.0,
    max_retries=3,
)

Error Handling

The client raises typed exceptions for different failure modes. All of them inherit from ModelPricingError and carry a status_code attribute:

Exception	HTTP Status	When
Unauthorized	401	Invalid or missing API key
NotFound	404	Unknown endpoint
ValidationError	422	Invalid model name or metrics
ServerError	5xx	Server-side failures (retried automatically)
ModelPricingError	other	Base class — raised on unexpected status codes or malformed 200s

from modelpricing_ai.errors import Unauthorized, ValidationError, ServerError

try:
    estimate = client.estimate(model="claude-haiku-4-5-20251001", tokens_in=1000, tokens_out=500)
except Unauthorized:
    print("Check your API key")
except ValidationError as e:
    print(f"Bad request: {e}")
except ServerError:
    print("Server error — will be retried automatically")

Retry Behavior

The client automatically retries on transient errors with exponential backoff:

• Retries: 5xx server errors and network/connection errors
• No retry: 4xx client errors (401, 404, 422)
• Default: 3 retries with exponential backoff (0.1 s initial, 2 s max)

# Increase retries for unreliable networks
client = ModelPricingClient(api_key="YOUR_API_KEY", max_retries=5)

# Disable retries (no retry attempts)
client = ModelPricingClient(api_key="YOUR_API_KEY", max_retries=0)

License

MIT

Credits

Made with ❤️ by Humanspeak