Conta i token prima di inviare una richiesta: tiktoken in Python

Puoi contare i token di un prompt sulla tua macchina prima che venga inviato: installa tiktoken, codifica il testo, prendi len() del risultato. tiktoken è il tokeniser di OpenAI, quindi per i modelli DeepSeek, GLM e MiniMax il numero è una stima. Il valore reale torna in usage.prompt_tokens dopo la prima chiamata, e confrontare i due richiede una riga in più.

Perché preoccuparsi? Perché sia la fattura sia gli errori iniziano con la dimensione dell'input. Incolla un contratto lungo in uno script e scopri che era troppo grande solo quando l'API risponde con un 400. Esegui un batch di cinquemila email e scopri quanto è costato solo quando il saldo è più basso. Contare prima trasforma entrambe le sorprese in un numero che puoi leggere in anticipo.

Cinque righe che contano i token#

Il README di tiktoken (verificato il 1 novembre 2026) mostra l'idea completa: scegli un encoding, codifica il testo, e la lunghezza della lista è il conteggio dei token.

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) restituisce il testo originale, un utile controllo di sanità per verificare che tu stia guardando lo stesso testo che vedrà il modello. Il README menziona anche tiktoken.encoding_for_model('gpt-4o'), che sceglie il tokeniser per uno specifico modello OpenAI. Questo è il punto da ricordare: i tokeniser appartengono a famiglie di modelli. La regola empirica del README è di circa quattro byte di testo per token, e descrive solo i tokeniser di OpenAI.

Quindi cosa fai per un modello DeepSeek? Usa lo stesso conteggio come stima di lavoro, e calibralo, come mostrato sotto.

Il prompt entra nella finestra?#

Ogni modello ha una finestra di contesto, e il tuo input più la risposta che consenti deve entrarci. Le finestre per i modelli che serviamo: DeepSeek-V4-Flash 380K, GLM-5.3-Flash 390K, MiniMax-M2.7 180K token. La risposta più lunga è 32.768 token per DeepSeek-V4-Flash e 8.192 per gli altri due (lista modelli CheapTokens, 1 novembre 2026).

Una guardia prima della chiamata è di quattro righe:

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]

Supponiamo che tu abbia un documento da 250.000 token. fits(250_000, 8_192, 'MiniMaxAI/MiniMax-M2.7') è False, quindi indirizzi quel lavoro a un modello con una finestra più grande o dividi il documento, e il 400 non si verifica mai. fits(250_000, 8_192, 'deepseek-ai/DeepSeek-V4-Flash-0731') è True. Se vuoi la storia completa di come appare l'errore, request too long: 400 vs 413, context window and max_tokens lo analizza.

Quanto costerà?#

Ora il budget. Prendi un elemento tipico, contalo e moltiplica. Supponi di classificare 5.000 email di ordini. Conti un'email rappresentativa e ottieni circa 800 token di input, e limiti l'etichetta e una breve motivazione a 200 token di output. I totali: 5.000 × 800 = 4.000.000 token di input e 5.000 × 200 = 1.000.000 token di output.

La tabella sotto prezza esattamente quel carico di lavoro ai prezzi correnti, con input e output contati insieme:

In totale, con input e output contati insieme, la colonna CheapTokens è più economica di OpenRouter per questi modelli. Cambia i tre numeri con i tuoi conteggi e hai un budget prima della prima richiesta. Per la differenza tra i due lati della fattura, vedi input vs output tokens: what an AI API bills you for, e per esempi realmente misurati how many tokens an API request uses. I prezzi correnti sono sempre sulla pagina dei prezzi.

Confronta la stima con l'uso#

La stima è un'ipotesi sul tokeniser di qualcun altro, quindi verificala una volta contro il foglio delle risposte. Ogni risposta porta un campo usage, e usage.prompt_tokens è ciò che l'API ha contato per il tuo input. Metti i due numeri fianco a fianco e dividi.

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}')

Da quel momento la routine è: stima localmente, proteggi la finestra, applica il tuo rapporto al budget, e lascia che usage in ogni risposta ti tenga onesto. Se vuoi anche il totale progressivo su un intero lavoro, track AI agent token cost in Python lo costruisce sullo stesso campo. Nuovo alla connessione stessa? Your first API request with CheapTokens lo copre, e la documentazione ha il resto.

Contare è economico, locale e richiede secondi. Fallo prima della chiamata che costa denaro.