openai-usage 0.9.0

Simple Library for OpenAI Usage

openai-usage

One usage model for every OpenAI API.

The OpenAI Python SDK reports usage in a different shape for almost every endpoint — Chat Completions, Responses, Agents SDK, Realtime, Batch, Embeddings, Images, Transcription. openai-usage collapses them all into a single, additive Usage object and estimates what it costs against live model pricing.

📖 Full documentation: https://allen2c.github.io/openai-usage/

Installation

pip install openai-usage

Requires Python 3.11+.

Quickstart

from openai_usage import Usage

# Normalize usage from any OpenAI API into one shape
total = Usage()
total.add(Usage.from_openai(chat_completion.usage))          # Chat Completions
total.add(Usage.from_openai(response.usage))                 # Responses API
total.add(Usage.from_openai(realtime_event.response.usage))  # Realtime

print(total.input_tokens, total.output_tokens, total.total_tokens)

# Estimate the cost against any model
print(f"${total.estimate_cost('gpt-4o'):.6f}")

What it does

• Unify — Usage.from_openai(...) accepts Chat Completions, Responses, Agents SDK, Realtime, Batch, Embeddings, Images, Transcription, and Assistants run usage.
• Aggregate — Usage.add() accumulates requests, tokens, and per-modality detail (cached, reasoning, audio, image, text) across calls.
• Estimate — Usage.estimate_cost() prices usage against any model using OpenRouter pricing, with separate rates for cached, reasoning, audio, and image tokens.
• Serialize — Usage is a Pydantic model with full backward compatibility for older payloads.

See the Supported Usage Types table for the full compatibility matrix, and Estimating Costs for pricing details and limitations.

Documentation

The docs are built with Material for MkDocs and deployed to GitHub Pages on every push to main.

make mkdocs        # serve locally at http://localhost:8000

License

MIT — see LICENSE.