Di Prompt caching Claude: calcolo del punto di pareggio
La scrittura costa 1.25x e la lettura 0.1x: un prefisso Claude rientra al secondo utilizzo. Calcola il tuo punto di pareggio e verificalo con l'API.
Quanto costa il prompt caching prima di diventare conveniente
Il prompt caching consente a Claude di riutilizzare l'inizio del prompt invece di rileggerlo a ogni chiamata. La valutazione dipende da due moltiplicatori applicati al prezzo base degli input del modello. Ad agosto 2026, la scrittura nella cache costa 1.25x il prezzo base degli input per una durata di 5 minuti, oppure 2x per una durata di 1 ora. La lettura dalla cache costa 0.1x. Questi moltiplicatori sono gli stessi per tutti i modelli disponibili, quindi il punto di pareggio riportato di seguito non cambia quando varia il prezzo per token.
Il compromesso consiste nel pagare un sovrapprezzo subito per ottenere uno sconto in seguito. Si paga una volta in più per memorizzare un prefisso. Ogni richiesta successiva che inizia con gli stessi byte in modo identico paga quindi un decimo del normale prezzo degli input per quella parte. Se un prefisso non viene mai riutilizzato durante il suo periodo di validità, si paga il 25 percento in più senza ottenere alcun vantaggio.
Il punto di pareggio, in una sola riga di algebra
Indichiamo con B il costo di input di base del prefisso se venisse inviato senza cache. Senza caching, N richieste costano N volte B. Con la cache di 5 minuti, la prima richiesta scrive il prefisso a 1.25B e le altre N meno 1 richieste lo leggono a 0.1B. Uguagliando i due costi si ottiene 0.9N = 1.15, quindi N = 1.28. La seconda richiesta è già più economica rispetto a non usare affatto la cache.
Ripetendo il calcolo con la scrittura a 2x della cache di 1 ora si ottiene 0.9N = 1.9, quindi N = 2.11. La cache con durata maggiore richiede due letture prima di raggiungere il punto di pareggio, motivo per cui non è la scelta predefinita.
Il grafico seguente calcola questi costi per un prefisso di 20,000 token su Claude Opus 5, il cui costo di input di base è $5 per milione di token ad agosto 2026. Moltiplica ogni valore per 0.6 per un modello dal costo di $3 per milione. La forma della curva non cambia.
The data behind this chart
[
{
"requests": 1,
"uncached_usd": "0.10",
"cached_5m_usd": "0.125",
"cached_1h_usd": "0.20"
},
{
"requests": 2,
"uncached_usd": "0.20",
"cached_5m_usd": "0.135",
"cached_1h_usd": "0.21"
},
{
"requests": 3,
"uncached_usd": "0.30",
"cached_5m_usd": "0.145",
"cached_1h_usd": "0.22"
},
{
"requests": 5,
"uncached_usd": "0.50",
"cached_5m_usd": "0.165",
"cached_1h_usd": "0.24"
},
{
"requests": 10,
"uncached_usd": "1.00",
"cached_5m_usd": "0.215",
"cached_1h_usd": "0.29"
},
{
"requests": 20,
"uncached_usd": "2.00",
"cached_5m_usd": "0.315",
"cached_1h_usd": "0.39"
}
]Una singola richiesta costa $0.10 senza cache e $0.125 con cache, quindi memorizzare nella cache un prompt usato una sola volta comporta una perdita netta. Alla seconda richiesta, la cache di 5 minuti costa $0.135 rispetto a $0.20. A quel punto la cache di 1 ora è ancora più costosa, $0.21 rispetto agli stessi $0.20, e supera la linea del costo senza cache soltanto alla terza richiesta: $0.22 rispetto a $0.30. Con 20 richieste, il divario è di $2.00 rispetto a $0.315.
Un accesso alla cache aggiorna anche la voce, motivo per cui la tabella dei prezzi pubblicata denomina quella colonna cache hits and refreshes. Un endpoint molto utilizzato mantiene quindi attiva indefinitamente una voce con durata di 5 minuti, applicando i prezzi di lettura; la durata di 1 ora giustifica il costo di scrittura a 2x soltanto quando il traffico presenta intervalli effettivi tra le richieste.
Il costo di un hit rate basso
Nella pratica si verificano cache miss. Una richiesta che non trova il contenuto nella cache ma contiene comunque un breakpoint viene addebitata come scrittura. Il modo corretto per modellare il costo consiste quindi nel considerarlo una funzione dell’hit rate. Il grafico seguente mostra questo scenario per 1,000 richieste, ciascuna con lo stesso prefisso di 20,000 token.
The data behind this chart
[
{
"hit_rate_percent": 0,
"cost_5m_usd": "125.00",
"cost_1h_usd": "200.00",
"uncached_usd": "100.00"
},
{
"hit_rate_percent": 25,
"cost_5m_usd": "96.25",
"cost_1h_usd": "152.50",
"uncached_usd": "100.00"
},
{
"hit_rate_percent": 50,
"cost_5m_usd": "67.50",
"cost_1h_usd": "105.00",
"uncached_usd": "100.00"
},
{
"hit_rate_percent": 75,
"cost_5m_usd": "38.75",
"cost_1h_usd": "57.50",
"uncached_usd": "100.00"
},
{
"hit_rate_percent": 90,
"cost_5m_usd": "21.50",
"cost_1h_usd": "29.00",
"uncached_usd": "100.00"
},
{
"hit_rate_percent": 95,
"cost_5m_usd": "15.75",
"cost_1h_usd": "19.50",
"uncached_usd": "100.00"
},
{
"hit_rate_percent": 99,
"cost_5m_usd": "11.15",
"cost_1h_usd": "11.90",
"uncached_usd": "100.00"
}
]Con un hit rate dello 0 percento paghi $125.00 invece di $100.00, mentre la cache di 1 ora raddoppia il conto portandolo a $200.00. Risolvendo 1.25 meno 1.15h = 1, la cache di 5 minuti inizia a far risparmiare con un hit rate di circa 22 percento. Per questo, già al 25 percento mostra $96.25. Lo stesso calcolo con la scrittura 2x dà circa 53 percento per la cache di 1 ora. Di conseguenza, con un hit rate del 50 percento il costo è ancora $105.00, superiore alla linea senza cache. Al 90 percento, i due valori sono rispettivamente $21.50 e $29.00. Al 99 percento, la cache breve raggiunge $11.15, vicino al limite minimo pari a un decimo del prezzo senza cache.
L’hit rate è il valore da monitorare, perché è l’unico parametro che puoi controllare dopo aver fissato la dimensione del prefisso.
Quali prefissi meritano un breakpoint
Una richiesta può contenere fino a quattro breakpoint della cache. La domanda è quindi quali blocchi ne meritino uno. I candidati sono i blocchi identici byte per byte tra le chiamate e abbastanza grandi da avere un impatto. Il grafico seguente confronta quattro strutture comuni su 1,000 richieste, con un tasso di hit del 90 percento nella cache da 5 minuti.
The data behind this chart
[
{
"label": "System prompt",
"prefix_size_tokens": "2,000",
"uncached_usd": "10.00",
"cached_usd": "2.15",
"saved_usd": "7.85"
},
{
"label": "System plus tools",
"prefix_size_tokens": "8,000",
"uncached_usd": "40.00",
"cached_usd": "8.60",
"saved_usd": "31.40"
},
{
"label": "Policy document",
"prefix_size_tokens": "25,000",
"uncached_usd": "125.00",
"cached_usd": "26.88",
"saved_usd": "98.12"
},
{
"label": "Codebase context",
"prefix_size_tokens": "120,000",
"uncached_usd": "600.00",
"cached_usd": "129.00",
"saved_usd": "471.00"
}
]Un system prompt essenziale di 2,000 token fa risparmiare $7.85 ogni 1,000 richieste rispetto alle richieste senza cache, che costano $10.00. A volumi elevati è un risparmio reale, ma non è questo a rendere interessante il caching. Aggiungendo le definizioni degli strumenti, si arriva a 8,000 token e a un risparmio di $31.40. Un documento di policy di 25,000 token, su cui ogni richiesta pone domande, fa risparmiare $98.12. L'ultima riga è quella che modifica l'architettura: 120,000 token di contesto relativo al codebase o alla trascrizione costano $600.00 senza cache e $129.00 con cache, per un risparmio di $471.00.
Il risparmio cresce con la dimensione del prefisso e con il tasso di hit, e non dipende da altro. Questo modifica anche il modo in cui si decide cosa includere in un prompt: quanto costano davvero un milione di token Claude arriva a un decimo del prezzo di listino per tutto ciò che viene inviato più di una volta.
Come appare in una fattura mensile
Il grafico seguente prende il prefisso di 8,000 token indicato sopra, insieme a un prompt di sistema e alle definizioni degli strumenti, con un tasso di hit del 90 percento, e lo proietta sui volumi mensili di richieste.
The data behind this chart
[
{
"label": "10k requests",
"uncached_usd": "400.00",
"cached_usd": "86.00",
"saved_usd": "314.00"
},
{
"label": "100k requests",
"uncached_usd": "4,000.00",
"cached_usd": "860.00",
"saved_usd": "3,140.00"
},
{
"label": "1M requests",
"uncached_usd": "40,000.00",
"cached_usd": "8,600.00",
"saved_usd": "31,400.00"
}
]Con 10,000 richieste al mese, il risparmio è di $314.00, cioè la differenza tra $400.00 e $86.00. Con 100,000 richieste, il risparmio è di $3,140.00. Con un milione di richieste, il costo degli input senza cache è $40,000.00 e la cache ne elimina $31,400.00. Questi valori riguardano solo i token di input. L'output ha un prezzo separato e la cache non incide su questo costo. È importante ricordarlo prima di promettere a qualcuno una riduzione del 90 percento della fattura. La cache si aggiunge alle altre pratiche utili per tenere sotto controllo il costo di un agente AI su un VPS.
Come dimostrare che la cache funziona
Non fidarti della configurazione. Leggi il blocco sull'utilizzo nella risposta. Ogni risposta dell'API Messages riporta i token memorizzati nella cache, i token letti dalla cache e i nuovi token che ha dovuto elaborare.
from anthropic import Anthropic
client = Anthropic()
resp = client.messages.create(
model="claude-opus-5",
max_tokens=512,
system=[
{
"type": "text",
"text": POLICY_DOCUMENT,
"cache_control": {"type": "ephemeral"},
}
],
messages=[{"role": "user", "content": question}],
)
u = resp.usage
print("write:", u.cache_creation_input_tokens)
print("read: ", u.cache_read_input_tokens)
print("fresh:", u.input_tokens)Esegui la richiesta due volte con lo stesso documento e una domanda diversa. La prima chiamata riporta un valore cache_creation_input_tokens diverso da zero e un valore cache_read_input_tokens pari a zero. La seconda inverte questi valori, perché il prefisso è stato trovato. input_tokens conta solo i token successivi all'ultimo breakpoint, quindi in una seconda chiamata corretta è un valore ridotto, in genere limitato al nuovo messaggio dell'utente. Entrambe le chiamate sono fatturate, perché l'API Claude non offre un piano gratuito, anche se, per il prefisso di 20,000 token usato nell'esempio precedente, il costo della coppia è di circa quattordici centesimi.
Puoi eseguire lo stesso controllo dalla shell, usando un corpo della richiesta salvato in request.json:
curl -s https://api.anthropic.com/v1/messages \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "content-type: application/json" \
-d @request.json | jq '.usage'Una seconda chiamata corretta stampa un risultato simile al seguente:
{
"input_tokens": 42,
"cache_creation_input_tokens": 0,
"cache_read_input_tokens": 20143,
"output_tokens": 187
}Una riga mostra il risultato effettivo. Se cache_read_input_tokens rimane a 0 tra una chiamata e l'altra, paghi ogni volta la scrittura con moltiplicatore 1.25x senza ricevere nulla in cambio.
Per la durata di 1 hour, il breakpoint include un time to live (TTL):
{
"type": "text",
"text": "your stable prefix",
"cache_control": {"type": "ephemeral", "ttl": "1h"}
}È disponibile anche il caching automatico: basta un singolo campo cache_control al livello superiore della richiesta, quindi l'API gestisce i breakpoint mentre la conversazione cresce. Questo campo utilizza uno dei quattro slot disponibili per i breakpoint. Inizia da qui. Passa ai breakpoint espliciti quando devi stabilire con precisione la posizione del limite.
La regola dell’ordine che azzera il tasso di hit
La cache confronta un prefisso byte per byte a partire dall’inizio della richiesta. La richiesta viene assemblata in un ordine fisso: strumenti, poi sistema, quindi messaggi. Una modifica a un livello invalida quel livello e tutti quelli successivi. Se modifichi la descrizione di uno strumento, il prompt di sistema e l’intera cronologia dei messaggi vengono invalidati insieme, anche se non li hai modificati.
Ne deriva una regola senza eccezioni. Tutto ciò che cambia tra una chiamata e l’altra deve trovarsi dopo tutto ciò che non cambia.
Il responsabile più comune è un timestamp. Una riga contenente Current time: 2026-08-03T14:07:11Z all’inizio di un prompt di sistema garantisce un tasso di hit dello 0%, perché l’hash del prefisso è diverso a ogni chiamata e nessuna voce precedente può mai corrispondere. Spostalo nel messaggio dell’utente, alla fine. Un identificatore di sessione o un nonce per richiesta produce lo stesso problema e richiede la stessa soluzione. Anche i documenti recuperati che cambiano a ogni richiesta devono trovarsi dopo il blocco memorizzato nella cache; in caso contrario spostano oltre un confine variabile tutti i token stabili.
Il secondo problema consiste nel posizionare il punto di interruzione sul blocco che cambia. La cache scrive i dati al punto di interruzione. Se quel blocco è diverso a ogni richiesta, non viene mai memorizzato nulla di stabile e la ricerca all’indietro trova soltanto le voci che le richieste precedenti hanno scritto nei rispettivi punti di interruzione variabili. Posiziona cache_control sull’ultimo blocco il cui contenuto è identico tra le richieste.
Il terzo problema è una modifica di parametro che non consideri parte del contenuto del prompt. Un modello diverso usa una cache diversa. La modifica della scelta dello strumento invalida tutto a partire dal livello di sistema. L’aggiunta o la rimozione di uno strumento invalida ogni elemento.
Il prefisso minimo e l'operazione ignorata senza messaggi
Un prefisso più breve del minimo richiesto dal modello non viene memorizzato nella cache e non ricevi alcuna indicazione. Non viene restituito né un errore né un avviso. La richiesta ha esito positivo ed entrambi i contatori riportano 0. Ad agosto 2026, i valori minimi pubblicati sono:
- 512 token su Claude Opus 5 e Claude Fable 5
- 1,024 token su Claude Sonnet 5 e Claude Opus 4.8
- 4,096 token su Claude Haiku 4.5
Se entrambi i contatori riportano 0 per una richiesta che ritieni memorizzata nella cache, controlla innanzitutto la lunghezza del prefisso. Per questo il modello meno costoso non è automaticamente quello più economico per un carico di lavoro che usa la cache. Claude Haiku 4.5 richiede un prefisso otto volte più lungo rispetto a Claude Opus 5 prima che la memorizzazione nella cache venga attivata: di conseguenza, un prompt di sistema di 2,000 token viene memorizzato nella cache con un modello, ma viene ignorato senza messaggi dall'altro.
Dove Claude Code memorizza la cache e dove non può farlo
Claude Code memorizza nella cache il proprio prefisso. Il prompt di sistema e le definizioni degli strumenti si trovano all’inizio di ogni richiesta e non cambiano posizione, quindi vengono scritti una sola volta e riletti per il resto della sessione. Per questo il costo per turno di una sessione lunga è molto inferiore a quanto suggerirebbe la dimensione del contesto. Questo si riflette nei contatori descritti in come Claude Code segnala l’uso dei token.
La cache non è utile quando si modifica una parte vicina all’inizio del contesto. La cronologia della conversazione è di sola aggiunta, quindi i nuovi turni estendono un prefisso già presente nella cache. Se si modifica un file letto all’inizio della sessione, cambia il contenuto nella parte centrale di quel prefisso e ogni token successivo deve essere scritto di nuovo. Lo stesso accade dopo un lungo periodo di inattività, perché la voce scade e il turno successivo richiede una scrittura completa. Nessuno dei due comportamenti è un bug. In entrambi i casi viene applicata esattamente la regola del prefisso.
Se invece stai scrivendo un client personalizzato, applica questa struttura già dalla prima richiesta anziché introdurla in un secondo momento: costruisci la chiamata come descritto in una prima app Claude API su un VPS, inserendo prima i blocchi stabili e per ultimi quelli variabili.
Modalità di errore e comportamento osservato
Ogni chiamata è una scrittura. cache_creation_input_tokens è diverso da zero in ogni richiesta, mentre cache_read_input_tokens resta 0. Qualcosa cambia tra una chiamata e l’altra, nel punto di interruzione o prima di esso. Stampa i primi 200 caratteri del prefisso assemblato in due richieste consecutive e confrontali visivamente.
Entrambi i contatori sono 0. Il prefisso è inferiore alla dimensione minima prevista dal modello oppure il campo cache_control non è mai arrivato all’API. Conta prima i token del prefisso, quindi registra il corpo della richiesta effettivamente inviato.
Le letture funzionano, poi si interrompono. Si verifica una sequenza di riscontri, seguita da una scrittura e poi da altri riscontri. L’intervallo tra le richieste è stato più lungo della durata della cache. Accetta la scrittura oppure passa al TTL di 1 hour dopo avere verificato che il tasso di riscontro superi il 53 percento.
Il tasso di riscontro diminuisce dopo un deploy. È stata modificata la descrizione di uno strumento oppure è stato cambiato il modello. Entrambe le operazioni invalidano l’intero prefisso. Dopo ogni deploy che modifica il prompt, prevedi un ciclo iniziale costoso di scritture.
Il costo è aumentato dopo l’abilitazione della cache. Il tasso di riscontro è inferiore al punto di pareggio. Con la cache di 5 minuti, al di sotto di circa 22 percento è più conveniente inviare il prefisso senza cache; lo stesso vale per la cache di 1 hour al di sotto di circa 53 percento.
FAQ
Quante volte deve essere riutilizzato un prompt perché il caching diventi conveniente?
Una volta, con la cache di 5 minuti. Una scrittura costa 1.25x l'input di base e una lettura costa 0.1x, quindi N richieste senza cache costano N, mentre N richieste con cache costano 1.25 più 0.1 per N meno 1. I due costi coincidono a N = 1.28, quindi la seconda richiesta è già conveniente. La cache di 1 ora applica un costo di scrittura pari a 2x e raggiunge il punto di pareggio a N = 2.11, quindi richiede due letture.
Perché cache_read_input_tokens è sempre pari a zero?
Controllare prima la lunghezza del prefisso: al di sotto del minimo del modello, 512 token su Claude Opus 5 e 4,096 su Claude Haiku 4.5 ad agosto 2026, il caching viene saltato senza messaggi e entrambi i contatori restano pari a 0. Se il prefisso è sufficientemente lungo, cercare contenuti che cambiano tra una chiamata e l'altra e che si trovano al breakpoint o prima di esso, ad esempio un timestamp o un identificatore di sessione nel prompt di sistema. Se i contatori funzionavano e poi si sono fermati, l'intervallo tra le richieste era più lungo della durata della cache.
Il caching dei prompt modifica le risposte di Claude?
No. La cache memorizza la forma elaborata dei token già inviati e il modello riceve lo stesso prompt in entrambi i casi. È una funzionalità per la fatturazione e la latenza, non una modifica del comportamento. Questo significa anche che si può abilitarla su un prompt già funzionante senza ripetere le valutazioni.
Conviene pagare la cache di 1 ora?
Solo quando il traffico presenta intervalli superiori a 5 minuti e il tasso di hit previsto supera comunque circa il 53 percento. Il costo di scrittura pari a 2x raddoppia lo svantaggio rispetto alla scrittura da 1.25x quando non si verifica un hit. Una voce della cache di 5 minuti viene rinnovata a ogni hit, quindi un traffico costante la mantiene attiva al costo delle letture senza pagare mai la durata maggiore.