リクエストを送る前にトークンを数える: Python での tiktoken

プロンプトのトークン数は、送信前に自分のマシンで数えられます。tiktoken をインストールし、テキストをエンコードして、結果の len() を取ります。tiktoken は OpenAI のトークナイザーなので、DeepSeek、GLM、MiniMax のモデルではその数値は推定値です。実際の数値は最初の呼び出し後に usage.prompt_tokens で返ってくるので、両者を比較するのはあと1行です。

なぜわざわざ数えるのか？ 請求もエラーも入力サイズから始まるからです。長い契約書をスクリプトに貼り付けると、大きすぎたことがわかるのは API が 400 を返したときです。5,000通のメールをバッチ処理すると、いくらかかったかわかるのは残高が減ったときです。先に数えておけば、どちらの驚きも事前に読める数値になります。

トークンを数える5行#

tiktoken README（2026年11月1日確認）にすべてが書かれています。エンコーディングを選び、テキストをエンコードすれば、リストの長さがトークン数です。

pip install tiktoken

import tiktoken

enc = tiktoken.get_encoding('o200k_base')
text = 'Hello world'
tokens = enc.encode(text)
print(len(tokens))  # how many tokens the text is

enc.decode(tokens) は元のテキストを返すので、モデルが見るのと同じテキストを見ているかを確認するのに便利です。README には tiktoken.encoding_for_model('gpt-4o') についても書かれており、これは特定の OpenAI モデル用のトークナイザーを選びます。ここが覚えておくべき注意点です。トークナイザーはモデルファミリーに属します。README の経験則では1トークンあたり約4バイトのテキストで、これは OpenAI のトークナイザーについてのみ述べています。

では DeepSeek モデルではどうするか？ 同じカウントを作業用の推定値として使い、以下に示すように較正します。

プロンプトはウィンドウに収まるか？#

すべてのモデルにはコンテキストウィンドウがあり、入力と許可する回答の合計がそこに収まる必要があります。当社が提供するモデルのウィンドウは、DeepSeek-V4-Flash 380K、GLM-5.3-Flash 390K、MiniMax-M2.7 180K トークンです。最長の回答は DeepSeek-V4-Flash で 32,768 トークン、他の2つは 8,192 です（CheapTokens モデル一覧、2026年11月1日）。

呼び出し前のガードは4行です。

CONTEXT = {
    'deepseek-ai/DeepSeek-V4-Flash-0731': 380_000,
    'zai-org/GLM-5.3-Flash': 390_000,
    'MiniMaxAI/MiniMax-M2.7': 180_000,
}

def fits(prompt_tokens, max_tokens, model):
    return prompt_tokens + max_tokens <= CONTEXT[model]

250,000トークンのドキュメントがあるとします。fits(250_000, 8_192, 'MiniMaxAI/MiniMax-M2.7') は False なので、そのジョブをより大きなウィンドウを持つモデルに振り分けるか、ドキュメントを分割すれば、400 は決して起きません。fits(250_000, 8_192, 'deepseek-ai/DeepSeek-V4-Flash-0731') は True です。エラーがどのようなものか詳しく知りたい場合は、request too long: 400 vs 413, context window and max_tokens で解説しています。

いくらかかるか？#

次は予算です。典型的な1件を取り、数えて掛けます。5,000通の注文メールを分類するとします。代表的なメールを1通数えると約800入力トークンで、ラベルと短い理由を200出力トークンに制限します。合計は、5,000 × 800 = 4,000,000 入力トークン、5,000 × 200 = 1,000,000 出力トークンです。

以下の表は、まさにそのワークロードを実際の価格で、入力と出力を合算して算出したものです。

合計では、入力と出力を合算すると、これらのモデルについて CheapTokens の列は OpenRouter より安くなります。3つの数値を自分のカウントに変えれば、最初のリクエスト前に予算が得られます。請求の両側面の違いについては input vs output tokens: what an AI API bills you for を、実際に計測した例については how many tokens an API request uses をご覧ください。最新の価格は常に価格ページにあります。

推定値と使用量を比較する#

推定値は他人のトークナイザーに関する推測なので、答え合わせを一度しておきましょう。すべてのレスポンスには usage フィールドがあり、usage.prompt_tokens は API があなたの入力に対して数えた値です。2つの数値を並べて割ります。

pip install tiktoken openai
export CHEAPTOKENS_API_KEY='your-key-here'

import os
import tiktoken
from openai import OpenAI

MODEL = 'deepseek-ai/DeepSeek-V4-Flash-0731'
enc = tiktoken.get_encoding('o200k_base')
messages = [{'role': 'user',
             'content': 'Classify this email as order, refund or other: Hi, my parcel from last Tuesday has not arrived yet.'}]

estimate = sum(len(enc.encode(m['content'])) for m in messages)

client = OpenAI(base_url='https://api.cheaptokens.dev/v1',
                api_key=os.environ['CHEAPTOKENS_API_KEY'])
r = client.chat.completions.create(model=MODEL, messages=messages, max_tokens=200)

real = r.usage.prompt_tokens
print(f'estimate {estimate}, usage.prompt_tokens {real}, ratio {real / estimate:.2f}')

以後の手順は、ローカルで推定し、ウィンドウをガードし、予算に比率を適用し、各レスポンスの usage で正確さを保つ、というものです。ジョブ全体の累計も知りたい場合は、track AI agent token cost in Python が同じフィールドの上にそれを構築します。接続自体が初めてなら、Your first API request with CheapTokens で扱っており、残りはドキュメントにあります。

数えるのは安く、ローカルで、数秒で終わります。お金のかかる呼び出しの前にやりましょう。