---
id: openai-messages-token-helper
version: "0.1.13"
license: unclear
license_treatment: permissive
maintenance: aging
---

# openai-messages-token-helper — A helper library for estimating tokens used by messages sent through OpenAI Chat Completions API.

License: permissive · Maintenance: aging · Downloads: 86.8K/mo

## What it is and what it does

This package wraps OpenAI's tokenization logic to help you stay within token budgets when building chat conversations. It provides functions to count tokens in individual messages, images (for GPT-4 vision), and tool definitions, then uses those counts to automatically truncate old messages from a conversation history so the final message list fits within a model's token limit.

You supply a system prompt, optional few-shot examples, past messages, and a new user message, along with a target token budget and model name. The library calculates the token cost of each component using tiktoken for text and Pillow for image dimensions, then drops old messages from the history until everything fits. It also supports Azure OpenAI model names and can fall back to default limits if a model is unrecognized.

Use it for:

- Automatically truncate chat history to fit within a model's context window before sending to the OpenAI API.
- Calculate token costs for images in GPT-4 vision requests to budget vision-enabled conversations.
- Build few-shot prompts with known token budgets, ensuring examples fit alongside user messages.
- Estimate API costs by counting tokens before making requests to OpenAI.
- Handle tool definitions and tool-choice parameters in token calculations for function-calling workflows.

## Worth the install?

AI-flagged interpretation of the facts above — verify before relying.

Estimates token usage for OpenAI Chat Completions API messages and builds message lists that fit within model token limits, accounting for text, images, tools, and few-shot examples.

Yes, if you are building applications that use OpenAI's Chat Completions API and need to manage token budgets programmatically. The library is straightforward, has low install friction, carries no known vulnerabilities, and solves a real operational problem—preventing token-limit errors by pre-calculating and truncating conversations. Maintenance is aging but the repository is active; use it with the understanding that updates may be infrequent.

## Install

pip install openai-messages-token-helper
uv add openai-messages-token-helper
poetry add openai-messages-token-helper

## Installing openai-messages-token-helper

Before you install: Low install friction; depends on openai, tiktoken, and pillow. Maintenance status is aging—last commit 2025-12-29, 228 days since release—but the repository is active and not archived. Supports Python 3.9, 3.10, and 3.11.

License in practice: Licensed under MIT (permissive), so you can use, modify, and distribute freely with minimal restrictions.

Quickstart:

from openai_messages_token_helper import build_messages

messages = build_messages(
    model="gpt-4",
    system_prompt="You are a helpful assistant.",
    new_user_content="Hello",
    past_messages=[]
)

Requires openai and tiktoken to be installed; model name must be recognized or fallback_to_default must be True.

Verify before relying:

- Whether the package handles all current OpenAI model variants or only a fixed set.
- Performance characteristics when processing large message histories or many images in a single call.
- Whether token counts match OpenAI's actual billing exactly or are estimates.

## Package facts

- License: not declared (permissive)
- Python support: supports_current
- Install friction: low
- Maintenance: aging
- Downloads: 86.8K/month (top 15,000 on PyPI)
- Known vulnerabilities: none known

## Tags

openai token counting, gpt message token estimation, chat completion token limits, openai api token calculator, message history truncation, gpt-4 vision token cost, token budget management, openai-integration, token-accounting, llm-utilities

[View on SkillFed](https://skillfed.io/packages/openai-messages-token-helper) · [View on PyPI](https://pypi.org/project/openai-messages-token-helper/)