Di Caching dei prompt Claude: calcolo del punto di pareggio
La scrittura in cache costa 1,25x e la lettura 0,1x: un prefisso Claude si ripaga al secondo uso. Calcola il tuo punto di pareggio e verificalo via API.
Costi del caching dei prompt prima del risparmio
Il caching dei prompt consente a Claude di riutilizzare l'inizio del prompt invece di rileggerlo a ogni chiamata. La scelta 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 la durata di 5 minuti oppure 2x per la durata di 1 ora. Una lettura dalla cache costa 0.1x. Questi moltiplicatori valgono per tutti i modelli disponibili, quindi il punto di pareggio indicato sotto non cambia quando cambia il prezzo per token.
Il compromesso consiste nel pagare un sovrapprezzo subito per ottenere uno sconto in seguito. Paghi una volta in più per memorizzare un prefisso. Ogni richiesta successiva che inizia con esattamente gli stessi byte paga quindi un decimo del normale prezzo degli input per quella parte. Se un prefisso non viene mai riutilizzato durante il relativo periodo di validità, paghi 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 lo inviassi 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 all'assenza totale di caching.
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 più lunga ha bisogno di due letture prima di raggiungere il punto di pareggio; per questo 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 da $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; usare la cache per un prompt eseguito una sola volta comporta quindi una perdita netta. Alla seconda richiesta, la cache di 5 minuti costa $0.135 contro $0.20. A quel punto la cache di 1 ora è ancora più costosa, $0.21 contro gli stessi $0.20, e supera il costo senza cache soltanto alla terza richiesta: $0.22 contro $0.30. Dopo 20 richieste, il divario è di $2.00 senza cache contro $0.315 con cache.
Un cache hit aggiorna inoltre la durata dell'entry. Per questo la tabella dei prezzi pubblicata chiama quella colonna cache hit e refresh. Un endpoint molto utilizzato mantiene quindi in vita indefinitamente una entry di 5 minuti ai prezzi di lettura, mentre la durata di 1 ora giustifica il costo di scrittura a 2x soltanto quando il traffico presenta intervalli effettivi tra le richieste.
Quanto costa un hit rate basso
Il traffico reale produce anche cache miss. Una richiesta che non trova il prefisso nella cache ma contiene comunque un breakpoint viene addebitata come scrittura. Per questo, il modo corretto di modellare il costo è esprimerlo in funzione dell'hit rate. Il grafico seguente mostra il risultato 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 hour raddoppia il costo portandolo a $200.00. Risolvendo 1.25 meno 1.15h uguale 1, la cache di 5 minute inizia a ridurre i costi con un hit rate di circa 22 percento. Per questo, già al 25 percento il costo è $96.25. Lo stesso calcolo con la scrittura a 2x dà circa 53 percento per la cache di 1 hour. Di conseguenza, con un hit rate del 50 percento il costo è ancora $105.00, quindi superiore alla linea senza cache. Al 90 percento, i due costi scendono rispettivamente a $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 a livello di byte tra le chiamate e abbastanza grandi da incidere sul costo. Il grafico seguente confronta quattro strutture comuni su 1,000 richieste, con un hit rate del 90 percento sulla cache di 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 al costo di $10.00 senza cache. Su volumi elevati è un risparmio reale, ma non è questo l'aspetto più interessante del 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 cambia l'architettura: 120,000 token di contesto proveniente da una codebase o da una trascrizione costano $600.00 senza cache e $129.00 con cache, con un risparmio di $471.00.
Il risparmio cresce con la dimensione del prefisso e con l'hit rate, e non dipende da altro. Questo cambia anche ciò che conviene includere in un prompt: quanto costano davvero un milione di token Claude costa un decimo del prezzo di listino per qualsiasi contenuto inviato più di una volta.
Come appare in una fattura mensile
Il grafico seguente prende il prefisso di 8,000 token illustrato sopra, insieme a un prompt di sistema e alle definizioni degli strumenti, con una percentuale di hit del 90%, 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 è pari a $314.00, ovvero la differenza tra $400.00 e $86.00. Con 100.000 richieste, il risparmio è $3,140.00. Con un milione di richieste, il costo degli input senza caching è $40,000.00 e il caching elimina $31,400.00 di questa spesa. Si tratta soltanto dei token di input. L'output viene tariffato separatamente e il caching non incide su questo costo. È un aspetto da ricordare prima di promettere a qualcuno una riduzione del 90% della fattura. Il caching si aggiunge alle altre pratiche descritte in mantenere sotto controllo la spesa di un agente AI su un VPS.
Come verificare che la cache funzioni
Non fidarti della configurazione. Leggi il blocco relativo all’utilizzo nella risposta. Ogni risposta dell’API Messages indica i token memorizzati nella cache, i token letti dalla cache e i token nuovi 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 restituisce un valore diverso da zero per cache_creation_input_tokens e un valore pari a zero per cache_read_input_tokens. La seconda inverte questi valori, perché il prefisso è stato trovato nella cache. input_tokens conta soltanto i token successivi all’ultimo breakpoint, quindi in una seconda chiamata corretta è ridotto, in genere limitato al nuovo messaggio dell’utente.
Puoi eseguire lo stesso controllo dalla shell, usando il 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 restituisce un output simile al seguente:
{
"input_tokens": 42,
"cache_creation_input_tokens": 0,
"cache_read_input_tokens": 20143,
"output_tokens": 187
}Una sola riga mostra il comportamento effettivo. Se cache_read_input_tokens rimane pari a 0 tra una chiamata e l’altra, paghi ogni volta la scrittura con moltiplicatore 1.25x senza ottenere alcun riutilizzo.
Per la durata di 1 hour, il breakpoint include un valore time to live (TTL):
{
"type": "text",
"text": "your stable prefix",
"cache_control": {"type": "ephemeral", "ttl": "1h"}
}È disponibile anche il caching automatico: un singolo campo cache_control al livello principale della richiesta, dopo il quale l’API gestisce i breakpoint mentre la conversazione cresce. Questo utilizza uno dei quattro slot disponibili per i breakpoint. Inizia da qui. Passa ai breakpoint espliciti quando devi stabilire con precisione dove collocare il confine.
La regola di ordinamento che azzera i tassi di hit
La cache confronta un prefisso byte per byte a partire dall'inizio della richiesta, che viene assemblata in un ordine fisso: prima gli strumenti, poi il sistema, quindi i messaggi. Una modifica a qualsiasi 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 essere collocato dopo tutto ciò che non cambia.
Il caso 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 pari allo 0 percento, perché l'hash del prefisso cambia a ogni chiamata e nessuna voce precedente può corrispondere. Spostala nel messaggio dell'utente, alla fine. Un identificatore di sessione o un nonce specifico per la richiesta produce lo stesso effetto e richiede la stessa correzione. Anche i documenti recuperati che cambiano a ogni richiesta devono essere collocati dopo il blocco memorizzato nella cache; in caso contrario spostano oltre un confine variabile ogni token stabile.
Il secondo problema consiste nel collocare il breakpoint sul blocco che cambia. La scrittura nella cache avviene in corrispondenza del breakpoint. 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 breakpoint 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. Cambiare la scelta dello strumento invalida tutto a partire dal livello di sistema. Aggiungere o rimuovere 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 generato alcun errore o 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 debba usare la cache, controlla innanzitutto la lunghezza del prefisso. Per questo il modello meno costoso non è automaticamente quello più conveniente per un carico di lavoro che usa la cache. Claude Haiku 4.5 richiede un prefisso otto volte più lungo di 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 e viene ignorato senza messaggi con l'altro.
Dove Claude Code memorizza nella cache i contenuti 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 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. Il costo viene riportato nei contatori descritti in come Claude Code riporta l'uso dei token.
Non può però aiutare nel caso di una modifica vicino all'inizio del contesto. La cronologia della conversazione è solo incrementale, quindi i nuovi turni ordinari estendono un prefisso già presente nella cache. Se modifichi un file letto all'inizio della sessione, cambi il contenuto nel mezzo di quel prefisso e ogni token successivo alla modifica 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 casi indica un bug. In entrambi i casi si applica 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 nell'esempio una prima applicazione Claude API su un VPS, inserendo prima i blocchi stabili e per ultimi quelli variabili.
Modalità di errore e cosa osservare
Ogni chiamata è una scrittura. cache_creation_input_tokens è diverso da zero in ogni richiesta, mentre cache_read_input_tokens resta 0. Qualcosa nel punto di interruzione o prima di esso cambia tra una chiamata e l’altra. Stampa i primi 200 caratteri del prefisso assemblato in due richieste consecutive e confrontali visivamente.
Entrambi i contatori sono 0. Il prefisso è inferiore al minimo richiesto 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 accessi alla cache, poi una scrittura, quindi di nuovo accessi alla cache. L’intervallo tra le richieste è stato più lungo del TTL. Accetta la scrittura oppure passa al TTL di 1 hour dopo aver verificato che il tasso di accesso alla cache superi il 53 percento.
Il tasso di accesso alla cache diminuisce dopo un deploy. È stata modificata la descrizione di uno strumento oppure è cambiato il modello. Entrambe le modifiche 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 accesso alla cache è inferiore al punto di pareggio. Con la cache di 5 minute, al di sotto di circa il 22 percento è più economico inviare il prefisso senza cache; con la cache di 1 hour, la stessa condizione si applica al di sotto di circa il 53 percento.
FAQ
Quante volte è necessario riutilizzare un prompt perché il caching diventi conveniente?
Una volta, con la cache di 5 minuti. Una scrittura costa 1.25 volte il costo base dell’input e una lettura costa 0.1 volte tale costo. Di conseguenza, 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 con N = 1.28, quindi la seconda richiesta è già più conveniente. La cache di 1 ora applica un costo di scrittura pari a 2 volte il costo base e raggiunge il punto di convenienza con 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 richiesto dal modello, 512 token per Claude Opus 5 e 4,096 per Claude Haiku 4.5 ad agosto 2026, il caching viene saltato senza messaggi e entrambi i contatori restano pari a 0. Se il prefisso è abbastanza 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 system prompt. Se i contatori funzionavano e poi hanno smesso, l’intervallo tra le richieste era superiore alla durata della cache.
Il prompt caching 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 modifica il comportamento. Questo significa anche che è possibile abilitarla su un prompt 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 cache hit supera comunque circa il 53 percento. Il costo di scrittura pari a 2 volte il costo base è il doppio del costo di scrittura pari a 1.25 volte quando si verifica un cache miss. Una voce della cache di 5 minuti viene aggiornata a ogni hit, quindi un traffico regolare la mantiene attiva al costo delle letture senza pagare mai per una durata maggiore.