Di Claude prompt caching: calcolo del punto di pareggio
La scrittura in cache costa 1,25x e la lettura 0,1x o meno: il prefisso di Claude conviene dal secondo utilizzo. Calcola e verifica il punto di pareggio via API.
Quanto costa il caching dei prompt prima di diventare conveniente
Il caching dei prompt consente a Claude di riutilizzare l'inizio del prompt invece di rileggerlo a ogni chiamata. La convenienza dipende da due moltiplicatori applicati al prezzo base dell'input del modello. A ottobre 2026, la scrittura nella cache costa 1.25x il prezzo base dell'input per la durata di 5 minuti, oppure 2x per la durata di 1 ora, su tutti i modelli. La lettura dalla cache costa 0.1x sulla maggior parte dei modelli, ma il moltiplicatore di lettura non è più uguale ovunque. È 0.025x su Claude Fable 5.1 e Claude Mythos 5.1, lanciati con questa tariffa il 1 settembre 2026. È 0.05x su Claude Opus 5.5 e Claude Sonnet 5.5; per Sonnet 5.5 la tariffa è stata ridotta da 0.1x a questo valore il 7 ottobre 2026. Gli esempi di calcolo riportati sotto usano la lettura standard a 0.1x. Le letture più economiche spostano leggermente a tuo favore il punto di pareggio. La sezione successiva mostra di quanto.
Il compromesso consiste in un sovrapprezzo immediato a fronte di uno sconto successivo. Paghi una volta un costo aggiuntivo per memorizzare un prefisso. Ogni richiesta successiva che inizia con esattamente gli stessi byte paga quindi, per quella parte, un decimo del normale prezzo dell'input, o una frazione ancora inferiore sui modelli indicati sopra. Un prefisso che non viene mai riutilizzato durante la propria durata costa il 25 percento in più senza 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 di lunga durata richiede due letture prima di raggiungere il punto di pareggio. Per questo non è la scelta predefinita.
Con letture meno costose il punto cambia, ma di poco. Con una lettura a 0.05x, la cache di 5 minuti dà 0.95N = 1.2, quindi N = 1.26; con 0.025x dà 0.975N = 1.225, ancora N = 1.26. Per la cache di 1 ora si scende a N = 2.05 e N = 2.03. La conclusione pratica è la stessa in ogni modello: la cache di 5 minuti conviene dalla seconda richiesta, quella di 1 ora dalla terza.
Il grafico seguente calcola questi costi per un prefisso di 20,000 token su Claude Opus 5. A ottobre 2026, la tariffa di input di base è $5 per milione di token, invariata da agosto. Opus 5 è ora un modello legacy, anche se è ancora disponibile. Il successore, Claude Opus 5.5, indica $4 per milione con una lettura a 0.05x; per lo stesso prefisso il costo è quindi $0.10 per la scrittura e $0.004 per la lettura. Per un modello da $3 per milione con la lettura standard a 0.1x, moltiplica ogni valore per 0.6. La forma della curva non cambia.
I dati alla base di questo grafico
[
{
"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 la cache. Memorizzare nella cache un prompt usato una sola volta comporta quindi 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 allo stesso valore di $0.20. Supera il costo senza cache solo alla terza richiesta: $0.22 rispetto a $0.30. Con 20 richieste, la differenza è $2.00 rispetto a $0.315.
Un accesso alla cache aggiorna anche la durata dell'elemento. Per questo la tabella dei prezzi pubblicata chiama quella colonna cache hits and refreshes. Un endpoint molto utilizzato mantiene quindi indefinitamente attiva una voce nella cache di 5 minuti, applicando i prezzi delle letture. La durata di 1 ora giustifica il costo di scrittura a 2x solo quando il traffico presenta intervalli effettivi tra le richieste.
Quanto costa un hit rate basso
Il traffico reale genera cache miss. Una richiesta che non trova il prefisso nella cache ma contiene comunque un breakpoint viene addebitata come una scrittura. Il modo corretto per modellare il costo è quindi esprimerlo in funzione dell’hit rate. Il grafico seguente mostra questo andamento per 1,000 richieste, ognuna con lo stesso prefisso di 20,000 token.
I dati alla base di questo grafico
[
{
"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 da 1 ora raddoppia il conto, portandolo a $200.00. Risolvendo 1.25 meno 1.15h uguale a 1, la cache da 5 minuti inizia a ridurre i costi con un hit rate di circa il 22 percento. Per questo, già al 25 percento, il costo è $96.25. Lo stesso calcolo applicato alla scrittura 2x dà circa il 53 percento per la cache da 1 ora. 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 sono rispettivamente $21.50 e $29.00. Al 99 percento, la cache breve arriva a $11.15, vicino al limite minimo di un decimo del prezzo senza cache.
Con un modello che applica una lettura da 0.05x, le soglie scendono a circa il 21 percento per la cache da 5 minuti e al 51 percento per quella da 1 ora. Con una lettura da 0.025x scendono a circa il 20 e il 51 percento. Il limite minimo diminuisce insieme al prezzo della lettura, fino a un ventesimo o a un quarantesimo del costo senza cache.
L’hit rate è il valore da monitorare, perché, una volta fissata la dimensione del prefisso, è l’unico parametro su cui puoi intervenire.
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 chiamate e abbastanza grandi da avere un impatto. Il grafico seguente calcola il costo di quattro strutture comuni su 1,000 richieste, con un tasso di hit del 90 percento nella cache di 5 minuti.
I dati alla base di questo grafico
[
{
"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. 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 delle policy di 25,000 token, sul quale ogni richiesta pone domande, fa risparmiare $98.12. L'ultima riga è quella che cambia l'architettura: 120,000 token di contesto del codebase o della 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 il tasso di hit, e con nient'altro. Questo cambia anche ciò che vale la pena inserire in un prompt: quanto costano davvero un milione di token Claude arriva a un decimo del prezzo indicato, o a una cifra inferiore sui modelli con letture meno costose, per qualsiasi contenuto 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.
I dati alla base di questo grafico
[
{
"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 di ordinamento che riduce 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, sistema, quindi 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 venire dopo tutto ciò che resta invariato.
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 percento, perché l’hash del prefisso cambia a ogni chiamata e nessuna voce precedente può mai corrispondere. Spostalo 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 per ogni richiesta devono essere inseriti dopo il blocco memorizzato nella cache. In caso contrario, spostano oltre un confine variabile ogni token stabile.
Il secondo problema consiste nel posizionare il punto di interruzione sul blocco che cambia. Le scritture nella cache avvengono in corrispondenza del 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 a un parametro che non consideravi parte del contenuto del prompt. Un modello diverso utilizza una cache diversa. La modifica di tool_choice invalida la cronologia dei messaggi, mentre gli strumenti e il prompt di sistema restano memorizzati nella cache. L’aggiunta o la rimozione di uno strumento invalida tutto.
Il prefisso minimo e l'operazione silenziosa
Un prefisso più breve del minimo previsto 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. A ottobre 2026, i valori minimi pubblicati sono:
- 512 token su Claude Opus 5 e Claude Fable 5, oltre che sulle versioni più recenti Opus 5.5, Sonnet 5.5, Fable 5.1 e Haiku 5.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 lo stesso motivo, il modello meno costoso non è automaticamente il più economico per un carico di lavoro che usa la cache. Haiku 4.5 richiede un prefisso otto volte più lungo di Opus 5 prima che la memorizzazione nella cache venga attivata, quindi un prompt di sistema di 2,000 token viene memorizzato nella cache con un modello e ignorato silenziosamente con l'altro.
Dove Claude Code usa la cache e dove non può aiutare
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 farebbe pensare la dimensione del contesto, come mostrano i contatori descritti in come Claude Code segnala l'uso dei token.
La cache non può aiutare quando cambia una parte vicina all'inizio del contesto. La cronologia della conversazione è append-only, quindi i nuovi turni aggiungono contenuto a un prefisso già memorizzato nella cache. Modificare un file letto all'inizio della sessione non interrompe questo meccanismo, perché Claude Code aggiunge una nota che indica la modifica del file invece di riscrivere la lettura precedente. Il cambio di modello, invece, lo interrompe, perché ogni modello ha una cache distinta. Anche la connessione di un server MCP i cui strumenti vengono caricati nel prefisso interrompe la cache, così come la compattazione della conversazione. Ognuna di queste operazioni fa riscrivere il prefisso al turno successivo. Lo stesso accade dopo un lungo periodo di inattività, perché la voce scade e il turno successivo deve eseguire una scrittura completa. Nessuno di questi comportamenti è un bug. È il funzionamento previsto della regola del prefisso.
Se invece stai scrivendo un client autonomo, applica questa struttura già dalla prima richiesta invece di aggiungerla in seguito: costruisci la chiamata come nell'esempio una prima applicazione Claude API su un VPS, mettendo prima i blocchi stabili e per ultimi quelli variabili.
Modalità di errore e risultati osservabili
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. Stampare i primi 200 caratteri del prefisso assemblato in due richieste consecutive e confrontarli visivamente.
Entrambi i contatori sono 0. Il prefisso è inferiore al minimo richiesto dal modello oppure il campo cache_control non è mai arrivato all’API. Contare prima i token del prefisso, quindi registrare il corpo della richiesta effettivamente inviato.
Le letture funzionano, poi si interrompono. Si verifica una sequenza di hit, seguita da una scrittura, quindi da altri hit. L’intervallo tra le richieste è stato più lungo della durata della cache. Accettare la scrittura oppure passare al TTL di 1 hour dopo aver verificato che il tasso di hit superi il 53 percento, o circa il 51 percento su un modello con letture a 0.05x o 0.025x.
Il tasso di hit 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, prevedere un ciclo iniziale costoso di scritture.
Il costo è aumentato dopo aver abilitato il caching. Il tasso di hit è inferiore al punto di pareggio. Con una cache di 5 minuti, al di sotto di circa il 22 percento è più economico inviare il prefisso senza caching; lo stesso vale per la cache di 1 hour al di sotto di circa il 53 percento. Sui modelli con letture meno costose, queste soglie sono circa il 20-21 percento e il 51 percento.
FAQ
Quante volte è necessario riutilizzare un prompt prima che 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 nella maggior parte dei modelli. Pertanto, N richieste senza cache costano N, mentre N richieste con cache costano 1.25 più 0.1 per N meno 1. I due costi si equivalgono a N = 1.28, quindi la seconda richiesta è già conveniente. Nei modelli con una lettura a 0.05x o 0.025x, il punto di pareggio è N = 1.26, con lo stesso risultato. La cache di 1 ora prevede scritture a 2x e raggiunge il punto di pareggio a N = 2.11, oppure a circa 2.05 con le letture meno costose. Sono quindi necessarie due letture.
Perché cache_read_input_tokens è sempre pari a zero?
Controllare innanzitutto la lunghezza del prefisso: al di sotto del minimo previsto dal modello, 512 token per Claude Opus 5 e 4,096 per Claude Haiku 4.5 a ottobre 2026, il caching viene ignorato senza messaggi e entrambi i contatori restano a 0. Se il prefisso è abbastanza lungo, verificare la presenza di contenuti che cambiano tra una chiamata e l'altra e che si trovano in corrispondenza del breakpoint o prima di esso, ad esempio un timestamp o un identificatore di sessione nel system prompt. Se i contatori funzionavano e poi si sono azzerati, 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 funzione per la fatturazione e la latenza, non una modifica del comportamento. Questo significa anche che è possibile abilitarla su un prompt funzionante senza ripetere le valutazioni.
Conviene pagare per la cache di 1 ora?
Solo quando il traffico presenta intervalli superiori a 5 minuti e il tasso di hit supera comunque circa il 53%, oppure circa il 51% nei modelli con una lettura meno costosa. In caso di miss, la scrittura a 2x costa quattro volte quella a 1.25x. Una scrittura a 1 ora senza hit spreca l'intero prezzo dell'input di base del prefisso, mentre una scrittura a 5 minuti senza hit ne spreca soltanto un quarto. Una voce della cache di 5 minuti viene aggiornata a ogni hit. Un traffico costante la mantiene quindi attiva al prezzo delle letture, senza pagare mai per una durata maggiore.