Adamant Tools

Adamant Tools › Blog

  • Costi
  • Token
  • Python
  • JavaScript
  • API

Contare i token e stimare i costi prima di chiamare un modello (Python e JavaScript)

Tre modi per contare i token (tokenizer locale, endpoint del fornitore, usage), come trasformarli in una forbice di costo e un controllo che blocca le chiamate troppo care.

Pubblicato 7 min di letturaGitHubRead in English

Contare i token e stimare i costi prima di chiamare un modello (Python e JavaScript)
Foto: Franklsf95, CC BY-SA 3.0, Wikimedia Commons

Le API dei modelli si pagano a token, e il conto arriva a lavoro finito. Un prompt che include un documento lungo, una chat la cui cronologia cresce senza limiti o un ciclo che chiama il modello più spesso del previsto possono trasformare una funzione economica in una costosa prima che qualcuno se ne accorga. Contare i token prima della chiamata permette tre cose utili: rifiutare le richieste fuori budget, controllare che il prompt entri nella finestra di contesto del modello e mandare i lavori piccoli a un modello più economico.

Questa guida mostra come contare i token in Python e JavaScript, come trasformare il conteggio in una forbice di costo e come controllare il costo reale dopo la chiamata. Versioni verificate il 30 ottobre 2026: tiktoken 0.14.0, anthropic 2.3.0 e openai 3.41.0 su PyPI, js-tiktoken 1.0.21 su npm.

Un token non è una parola, e non è uguale ovunque

I modelli leggono il testo a token: pezzi di parola, parole brevi intere, punteggiatura, byte di caratteri insoliti. Ogni famiglia di modelli ha il suo tokenizer, quindi lo stesso testo dà conteggi diversi su modelli diversi. Tre frasi del nostro test, contate con le codifiche o200k_base e cl100k_base di OpenAI:

Testo Caratteri Parole o200k_base cl100k_base
Frase in inglese 88 16 18 18
La stessa frase in italiano 90 14 23 26
Due righe di Python con un'emoji 54 13 21 22

La versione italiana ha meno parole e più o meno gli stessi caratteri, ma richiede cinque token in più con o200k_base e otto in più con la codifica precedente. Le regole pratiche come "quattro caratteri per token" sono tarate sull'inglese: per l'italiano, per le altre lingue e per il codice conviene misurare.

Il tokenizer può cambiare anche con lo stesso fornitore. La pagina dei prezzi di Anthropic indica che i modelli Claude 4.7 e successivi usano un tokenizer più recente, che produce circa il 30% di token in più per lo stesso testo. Un conteggio misurato su un modello non vale per un altro: quando cambi modello, conta di nuovo.

Tre modi per contare

Metodo Dove gira Cosa copre Quando usarlo
Tokenizer locale (tiktoken, js-tiktoken) Nel tuo processo, offline Solo testo, solo codifiche OpenAI Controlli veloci, tagliare un testo a una dimensione, molte chiamate al secondo
Endpoint di conteggio del fornitore Nell'API del fornitore Tutta la richiesta: prompt di sistema, messaggi, strumenti, immagini Prima di una chiamata costosa, quando serve il conteggio reale dell'input
usage nella risposta Dopo la chiamata Quello che ti è stato effettivamente fatturato Monitoraggio dei costi, avvisi, verifica delle stime

Per i modelli Claude la documentazione di Anthropic indica l'endpoint di conteggio, non un tokenizer locale.

Contare in locale in Python con tiktoken

python
import tiktoken


def count_tiktoken(text: str, encoding: str = "o200k_base") -> int:
    """Local count for OpenAI models (o200k_base: GPT-4o, GPT-4.1, GPT-5, o-series). Text only."""
    return len(tiktoken.get_encoding(encoding).encode(text))

tiktoken.encoding_for_model("gpt-4o") restituisce la codifica giusta per un nome di modello, ma solo per i nomi presenti nella tabella della libreria: per un modello che non conosce solleva un KeyError, quindi per i modelli nuovi è più semplice scegliere tu la codifica. In tiktoken 0.14.0 la tabella associa GPT-4o, GPT-4.1, GPT-5 e la serie o a o200k_base.

Due note pratiche. La prima chiamata scarica il file della codifica dallo storage pubblico di OpenAI e lo mette in cache: in un container senza accesso a internet imposta TIKTOKEN_CACHE_DIR e includi il file nell'immagine. E il conteggio copre solo il testo: l'API conta anche la struttura dei messaggi, gli strumenti e le immagini, che il solo testo non comprende. Considera il conteggio locale del testo dei messaggi come un valore minimo.

Contare in locale in JavaScript con js-tiktoken

js-tiktoken è una versione in JavaScript puro che funziona in Node.js e con i bundler. Il suo punto di ingresso lite permette di caricare solo la codifica che serve, così il bundle resta piccolo:

javascript
import { Tiktoken } from 'js-tiktoken/lite';
import o200k_base from 'js-tiktoken/ranks/o200k_base';

const enc = new Tiktoken(o200k_base); // load once: building the encoder is the slow part

export function countTiktoken(text) {
  return enc.encode(text).length;
}

Il nostro test esegue la versione Python e quella JavaScript sugli stessi testi e controlla che i conteggi siano identici: puoi quindi contare nel browser per avvisare l'utente e contare di nuovo sul server per far rispettare il limite.

Chiedere al fornitore il conteggio esatto

Anthropic ha un endpoint di conteggio dei token, POST /v1/messages/count_tokens. Accetta lo stesso input di una richiesta Messages, compresi prompt di sistema, strumenti, immagini e PDF, e restituisce input_tokens. Secondo la documentazione è gratuito, ha un proprio limite di richieste al minuto separato dalla creazione dei messaggi e restituisce una stima che può differire dall'uso reale "di poco". Non accetta i server tool, il connettore MCP, né immagini e documenti passati per URL o riferimento a file.

OpenAI offre un endpoint simile per la Responses API, POST /v1/responses/input_tokens. Con gli SDK Python ufficiali:

python
def count_claude(client, model: str, messages: list, system: str | None = None) -> int:
    """Exact input count from Anthropic's free count_tokens endpoint (includes system prompt and tools)."""
    extra = {"system": system} if system else {}
    return client.messages.count_tokens(model=model, messages=messages, **extra).input_tokens


def count_openai(client, model: str, text: str) -> int:
    """Input count from OpenAI's POST /v1/responses/input_tokens endpoint."""
    return client.responses.input_tokens.count(model=model, input=text).input_tokens
python
import anthropic

client = anthropic.Anthropic()  # reads ANTHROPIC_API_KEY
n = count_claude(client, "claude-sonnet-5-5", [{"role": "user", "content": "Summarise this contract: ..."}])

Senza SDK è una normale richiesta HTTP. Queste sono le intestazioni indicate nella documentazione di Anthropic; esegui il codice sul tuo server, mai nel browser, perché richiede la tua chiave API:

javascript
export async function countClaudeTokens({ model, messages, system, apiKey, baseUrl = 'https://api.anthropic.com' }) {
  const res = await fetch(`${baseUrl}/v1/messages/count_tokens`, {
    method: 'POST',
    headers: { 'content-type': 'application/json', 'x-api-key': apiKey, 'anthropic-version': '2023-06-01' },
    body: JSON.stringify({ model, messages, ...(system ? { system } : {}) }),
  });
  if (!res.ok) throw new Error(`count_tokens HTTP ${res.status}: ${await res.text()}`);
  return (await res.json()).input_tokens;
}

L'endpoint di conteggio è una chiamata HTTP con un proprio limite di frequenza, quindi può rispondere 429 come qualsiasi altra API. Il nostro simulatore di retry e backoff e la guida su HTTP 429 e Retry-After valgono anche qui.

Dai token ai soldi

I prezzi sono espressi in dollari per milione di token (MTok), con prezzi separati per input e output. Il 30 ottobre 2026 la pagina dei prezzi di Anthropic indicava, tra gli altri:

Modello Input Output Scrittura cache (5 min) Lettura cache
Claude Sonnet 5.5 $2 / MTok $10 / MTok $2,50 / MTok $0,10 / MTok
Claude Opus 5.5 $4 / MTok $20 / MTok $5 / MTok $0,20 / MTok

I prezzi cambiano: tienili nella configurazione e controlla la pagina del fornitore, non fidarti di una copia nel codice o in un articolo, compreso questo. Ci sono poi diversi modificatori: la Batch API dimezza i prezzi di input e output, alcuni modelli hanno prezzi diversi in base alla lunghezza del prompt (Claude Haiku 5.5 costa di più oltre i 100.000 token) e l'inferenza solo negli Stati Uniti aggiunge il 10% sui modelli Claude 4.6 e successivi.

Prima della chiamata conosci i token di input ma non quelli di output. Conosci però il massimo: il max_tokens che invii. La documentazione di Anthropic sull'extended thinking indica che max_tokens resta il tetto rigido dell'output totale, ragionamento compreso, e che i token di ragionamento si pagano come output. La stima onesta, quindi, è una forbice:

python
from dataclasses import dataclass


@dataclass(frozen=True)
class Price:
    """USD per million tokens (MTok)."""
    input: float
    output: float
    cache_write: float = 0.0  # 5-minute cache write
    cache_read: float = 0.0


def estimate_cost(input_tokens: int, max_output_tokens: int, price: Price) -> tuple[float, float]:
    """Cost range in USD: from an empty answer to an answer that uses all of max_output_tokens."""
    low = input_tokens * price.input / 1_000_000
    high = low + max_output_tokens * price.output / 1_000_000
    return low, high

Una richiesta con 12.000 token di input e max_tokens a 1.000 costa tra 0,024 e 0,034 dollari su Claude Sonnet 5.5, e tra 0,048 e 0,068 dollari su Claude Opus 5.5. La differenza sembra minima finché non la moltiplichi: 50.000 chiamate così al mese fanno fino a 1.700 dollari su Sonnet 5.5 e fino a 3.400 su Opus 5.5. Su entrambi i modelli i token di output costano cinque volte quelli di input, quindi abbassare max_tokens è spesso il risparmio più semplice.

Bloccare le chiamate fuori budget

Con un conteggio e un prezzo, il controllo sta in tre righe. Usa il caso peggiore, non la media:

python
class BudgetExceeded(Exception):
    pass


def check_budget(input_tokens: int, max_output_tokens: int, price: Price, max_usd: float) -> float:
    """Refuse a call whose worst case costs more than max_usd. Returns the worst case."""
    _, high = estimate_cost(input_tokens, max_output_tokens, price)
    if high > max_usd:
        raise BudgetExceeded(f"worst case ${high:.4f} is over the ${max_usd:.4f} limit")
    return high

Cosa fare quando il controllo fallisce dipende dalla funzione: accorciare il contesto (togliere i vecchi turni della chat, recuperare meno documenti), passare a un modello più economico, abbassare max_tokens o dire all'utente che il documento è troppo lungo. Tutte queste soluzioni sono meglio che scoprire il costo in fattura.

Controllare il costo reale dopo la chiamata

Ogni risposta riporta quanto è stato usato. Per Claude, l'oggetto usage contiene input_tokens, output_tokens, cache_creation_input_tokens e cache_read_input_tokens. Un dettaglio inganna spesso: secondo la documentazione sul prompt caching, input_tokens conta solo i token dopo l'ultimo punto di cache. L'input totale è la somma dei tre campi di input, ciascuno con il suo prezzo:

python
def actual_cost(usage, price: Price) -> float:
    """Cost of a finished Claude call from response.usage (input_tokens excludes cached tokens)."""
    return (usage.input_tokens * price.input
            + (usage.cache_creation_input_tokens or 0) * price.cache_write
            + (usage.cache_read_input_tokens or 0) * price.cache_read
            + usage.output_tokens * price.output) / 1_000_000

Nella Responses API di OpenAI, usage contiene input_tokens, output_tokens e total_tokens, e output_tokens_details.reasoning_tokens indica quanti token di output erano ragionamento nascosto. Anche i modelli locali riportano l'uso: Ollama restituisce prompt_eval_count ed eval_count nel messaggio finale.

Registra questi numeri a ogni chiamata, con il nome della funzione e il modello. Confrontarli con le stime è l'unico modo per sapere se le stime valgono qualcosa, e una somma giornaliera per funzione è l'avviso sui costi più semplice che si possa costruire. Per stimare quante chiamate contemporanee comporta il tuo traffico di punta, lo strumento di dimensionamento della capacità API fa i conti per te.

Provarlo senza chiave API

La cartella dell'esempio contiene un piccolo server finto, scritto con la libreria standard di Python, che risponde ai due endpoint di conteggio con numeri fissi e registra ogni richiesta. I test puntano gli SDK ufficiali anthropic e openai e la versione con fetch verso quel server, così controllano URL, intestazioni e corpo inviati dal tuo codice senza spendere nulla. Gli altri test confrontano i conteggi dei tokenizer Python e JavaScript e verificano i calcoli dei costi, comprese le letture dalla cache:

text
test_actual_cost_with_cache ... ok
test_count_claude_with_fetch ... ok
test_count_claude_with_sdk ... ok
test_count_openai_with_sdk ... ok
test_estimate_and_budget ... ok
test_python_and_javascript_tokenizers_agree ... ok

La suite gira in GitHub Actions a ogni modifica.

Limiti

  • Un conteggio locale è esatto solo per il testo e solo per la codifica scelta. Per richieste di chat, strumenti e immagini è un valore minimo.
  • Anche gli endpoint di conteggio dei fornitori sono stime: vicine, ma non garantite uguali alla fattura.
  • La lunghezza dell'output è la parte che non puoi conoscere in anticipo. Agenti e cicli di strumenti peggiorano le cose, perché ogni passo è una nuova chiamata con un contesto più lungo: metti il controllo del budget dentro il ciclo, non solo prima.
  • I prezzi di questo articolo e del repository sono una fotografia del 30 ottobre 2026.
Codice completo su GitHub
L'esempio completo e testato di questo articolo è nel nostro repository pubblico: adamant-solutions/ai-dev-examples/token-costs

Chi l'ha scritto

Scritto dal team tecnico di Adamant Solutions: ingegneri senior che lavorano su API, identità e integrazione enterprise, certificati WSO2 e Spring. Il codice è testato prima della pubblicazione; se trovi un errore, scrivi a administrata@adamant-solutions.com.