tokencost

0.1.26 · active · verified Sun Apr 12

tokencost is a Python library that provides client-side token counting and USD cost estimation for over 400 Large Language Models (LLMs) from providers like OpenAI, Anthropic, Google, and AWS Bedrock. It helps AI agents and LLM applications accurately track and manage API expenses by offering up-to-date pricing and model-specific tokenization, released frequently to reflect changing LLM provider costs.

Warnings

gotcha LLM providers frequently update model pricing and introduce new models. To ensure accurate cost estimations, it is crucial to keep the `tokencost` library updated to its latest version.
Fix: Regularly update the library: `pip install --upgrade tokencost`.
gotcha Different LLM providers (e.g., OpenAI, Anthropic) use distinct tokenization methods. Manual token counting or cost estimation can be inaccurate due to these variations (e.g., Tiktoken for OpenAI, Anthropic's beta API for Claude 3.5+). `tokencost` abstracts this complexity, using the appropriate tokenizer for each model.
Fix: Always use `tokencost` for reliable, model-specific token counting and cost estimation instead of attempting manual calculations or generic tokenizers.
gotcha Some advanced LLMs generate 'reasoning tokens' (internal thought processes) that are billed at the more expensive output token rate but are not visible in the final API response. This can lead to higher-than-expected costs for a given visible output. `tokencost` helps in understanding the total cost incurred by such models.
Fix: Monitor total costs reported by `tokencost` and consider using more cost-efficient models or prompt engineering strategies to reduce internal reasoning if costs are a concern.
breaking Past versions (e.g., 0.1.20) had fixes for incorrect token and cost calculations for certain OpenAI 'o' series models and issues with lazy loading of `update_token_costs`. While addressed, this highlights the dynamic nature of LLM pricing and tokenization.
Fix: Ensure you are on `tokencost` version 0.1.20 or newer to benefit from these specific fixes. Always keep the library updated to receive the latest pricing and tokenization logic corrections.

Install

pip install tokencost Install with pip

Imports

calculate_prompt_cost

from tokencost import calculate_prompt_cost

calculate_completion_cost

from tokencost import calculate_completion_cost

Quickstart

This quickstart demonstrates how to calculate the estimated token cost for both a prompt and its completion using `tokencost`. It includes an optional interaction with the OpenAI API for a realistic example, which requires the `OPENAI_API_KEY` environment variable to be set. The library automatically handles different tokenization methods for various LLM providers.

import os
from openai import OpenAI
from tokencost import calculate_prompt_cost, calculate_completion_cost

# Ensure OPENAI_API_KEY is set in your environment variables
openai_api_key = os.environ.get('OPENAI_API_KEY', 'YOUR_OPENAI_API_KEY')
if not openai_api_key or openai_api_key == 'YOUR_OPENAI_API_KEY':
    print("Warning: OPENAI_API_KEY environment variable not set. Using dummy key.")
    # This allows the example to run without an actual API call, but cost calculation still works.
    # For actual API calls, replace with a valid key or set the env var.

client = OpenAI(api_key=openai_api_key)
model = "gpt-3.5-turbo"
prompt_messages = [{ "role": "user", "content": "Say this is a test"}]

# Simulate an OpenAI API call (or make a real one if API key is valid)
try:
    chat_completion = client.chat.completions.create(
        messages=prompt_messages,
        model=model
    )
    completion_content = chat_completion.choices[0].message.content
    print(f"API Completion: {completion_content}")
except Exception as e:
    print(f"Could not make actual OpenAI API call (continuing with dummy completion for cost calculation): {e}")
    completion_content = "This is a test."

# Calculate costs
prompt_cost = calculate_prompt_cost(prompt_messages, model)
completion_cost = calculate_completion_cost(completion_content, model)
total_cost = prompt_cost + completion_cost

print(f"Prompt Cost: ${prompt_cost:.6f}")
print(f"Completion Cost: ${completion_cost:.6f}")
print(f"Total Estimated Cost: ${total_cost:.6f}")

view raw JSON →