Misurare prima di stimare

Ci sono due strumenti, uno prima e uno dopo la chiamata.

Prima: POST /v1/messages/count_tokens accetta gli stessi input di una creazione — system, tools, immagini, PDF — e restituisce i token di input. È gratuito e ha limiti di richieste al minuto separati da quelli della creazione dei messaggi (5.000, 10.000 o 20.000 a seconda del tier). Due avvertenze: il conteggio è una stima, e non usa la logica di caching anche se passi il campo di controllo cache. Usalo per il routing e per il fit nel contesto, non per la contabilità.

Dopo: l’oggetto usage sulla risposta, il dato vero della singola richiesta.

input_tokens                 token non letti dalla cache né usati per crearla
cache_creation_input_tokens  token scritti in cache
cache_read_input_tokens      token letti dalla cache
output_tokens                token generati, thinking incluso

In streaming i conteggi usage che arrivano con message_delta sono cumulativi: se li sommi, conti due volte. La regola sul thinking è asimmetrica: i blocchi dei turni assistant precedenti non contano nell’input, quelli del turno corrente sì. E dal modello 4.7 in poi il tokenizer è nuovo e produce circa il 30 per cento di token in più sullo stesso testo: quando migri, ricontà con l’ID del modello di destinazione, altrimenti sbagli sia il preventivo sia la capienza del contesto.

Modellare il costo

I prezzi base sono $5 in ingresso e $25 in uscita per milione di token su Opus 5, $2 e $10 su Sonnet 5, $1 e $5 su Haiku 4.5. Sopra questi si applicano moltiplicatori: scrittura in cache 1,25x per la durata di 5 minuti e 2x per quella di un’ora, lettura dalla cache 0,1x, sconto del 50 per cento su input e output con la Batch API. Un modello di costo onesto li tiene tutti separati:

cost = (
    usage.input_tokens * INPUT_PER_MTOK
    + writes_1h * INPUT_PER_MTOK * 2.0
    + writes_5m * INPUT_PER_MTOK * 1.25
    + cache_read_tokens * CACHE_READ_PER_MTOK
    + usage.output_tokens * OUTPUT_PER_MTOK
) / 1_000_000

Voce che quasi tutti dimenticano: i tool costano token di input anche quando non vengono chiamati. Paghi le definizioni in tools più un system prompt di tool use che su Opus 5 vale 286 token con tool_choice auto o none, 406 con any o tool.

Per il dato aggregato d’organizzazione esistono due endpoint della Admin API — richiedono una chiave admin, le chiavi di workspace non funzionano:

GET /v1/organizations/usage_report/messages   bucket 1m/1h/1d, group_by modello, workspace, chiave
GET /v1/organizations/cost_report             solo granularità giornaliera, importi in USD

I dati compaiono tipicamente entro 5 minuti e il polling sostenibile è di una volta al minuto. Regola pratica: usage per la telemetria per richiesta e gli alert, Cost API per la riconciliazione con la fattura.

Prompt caching, e i modi in cui si rompe

La Exam Guide lo chiama cache check-pointing; la documentazione parla di cache breakpoints. Il meccanismo: il sistema verifica se un prefisso del prompt, fino a un breakpoint, è già in cache da una richiesta recente; se lo trova lo riusa, altrimenti processa tutto e mette in cache il prefisso. Si attiva in automatico con un solo campo cache_control a livello di richiesta, o in modo esplicito sui singoli blocchi. «You can define up to 4 cache breakpoints if you want to cache different sections that change at different frequencies.»

La durata predefinita è 5 minuti; per un’ora si passa il TTL:

{"cache_control": {"type": "ephemeral", "ttl": "1h"}}

Il pareggio è aritmetico: con la scrittura a 1,25x la cache da 5 minuti ripaga dopo una lettura, quella da un’ora dopo due. Scegli in base a quanto spesso i turni arrivano dopo una pausa lunga.

Tre modi tipici di sprecarla. Il primo è silenzioso: sotto la lunghezza minima cacheabile — 512 token su Opus 5, 1.024 su Sonnet 5, 4.096 su Haiku 4.5 — la richiesta viene processata senza caching e non ricevi alcun errore. Controlla cache_read_input_tokens, non il codice di stato. Il secondo è l’ordine: il prefisso è un match byte-esatto su tools, poi system, poi messages, e una modifica a un livello invalida quel livello e tutto ciò che segue. Metti davanti ciò che è stabile, in fondo ciò che cambia. Il terzo sono le invalidazioni non ovvie: cambiare le definizioni dei tool, tool_choice, i parametri di thinking o il valore top-level di effort rompe la cache. Per variare l’effort in conversazione esiste la forma per messaggio, che preserva il prefisso.

L’ordine in cui applicare le leve

Non sono equivalenti, e conviene applicarle in quest’ordine.

  1. Caching, di gran lunga la leva più grande: nei benchmark della documentazione ha ridotto il costo di un loop agentico di un fattore da 2,7 a 5,3, e la bolletta di un piccolo agente di triage dell’83 per cento.
  2. Igiene dei token: tagliare l’input, gestire il ciclo di vita del contesto, e su un parco tool grande cercare i tool invece di allegarli tutti (45 per cento con 500 definizioni).
  3. Effort, se il costo è alto e la qualità è già buona: su lavoro di conoscenza medium ha risparmiato dal 13 al 31 per cento.
  4. Scelta del modello, misurata sul costo per compito.
  5. Batch per ciò che può aspettare: 50 per cento di sconto, fino a 100.000 richieste o 256 MB per batch, i risultati accessibili quando tutte le richieste finiscono o dopo 24 ore, e un batch che non completa in 24 ore scade.

Nessuna di queste leve vale molto senza un costo per compito nei log. Strumenta prima, ottimizza dopo.