openai-usage 0.10.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. Gemini and LiteLLM usage are supported too, behind optional extras.

📖 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 — plus Gemini and LiteLLM usage via optional extras.
• Aggregate — Usage.add() accumulates requests, tokens, and per-modality detail (cached, cache-write, reasoning, audio, image, video, text) across calls.
• Estimate — Usage.estimate_cost() prices usage against any model using LiteLLM and OpenRouter pricing, with separate rates for cached, cache-write, reasoning, audio, image, and duration-billed usage.
• 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.