La nuova API di prompt-caching di Claude Opus 5 riduce drasticamente i costi dei token per le applicazioni in stile chat, consentendo al modello di evitare di rileggere il testo invariato. La prima richiesta prevede un modesto sovrapprezzo; ogni hit successiva costa circa un decimo della tariffa base, trasformando una spesa ricorrente in un addebito una tantum.
Perché gli sviluppatori pagano due volte per le stesse parole
La maggior parte delle interfacce conversazionali ricostruisce l'intero prompt a ogni turno: un system prompt da 8.000 token, i PDF allegati e l'intera cronologia del dialogo vengono inviati insieme al modello ogni volta che un utente pone una domanda di follow-up. Il modello rielabora ogni singolo token, anche se la maggior parte di quel testo non cambia mai. Con i prezzi attuali, questa ridondanza può dominare i costi di un bot molto attivo.
Come la cache cambia i calcoli
L'API crea una voce di cache per ogni "blocco" di token fino a un breakpoint definito. Quando la richiesta successiva contiene lo stesso blocco all'inizio, il servizio lo legge dalla cache invece di tokenizzarlo di nuovo. La suddivisione dei prezzi riflette il lavoro risparmiato:
- Scrittura in cache – TTL di 5 minuti: 1,25 × prezzo base
- Scrittura in cache – TTL di 1 ora: 2 × prezzo base
- Lettura dalla cache (hit): 0,1 × prezzo base
In pratica, la prima chiamata a un nuovo blocco costa un po' più di una richiesta normale. Ogni chiamata successiva che colpisce la cache è più economica del 90%, quindi la spesa netta diminuisce drasticamente man mano che la conversazione si approfondisce.
La "regola d'oro" per strutturare i prompt
L'efficacia della cache dipende da dove si posizionano i contenuti statici rispetto a quelli dinamici. Metti tutto ciò che rimane invariato all'inizio e sposta le parti in continuo mutamento alla fine. Un ordine affidabile è il seguente:
- Strumenti (Tools) – definizioni di eventuali funzioni esterne che il modello può chiamare.
- Istruzioni di sistema (System instructions) – il comportamento di alto livello che desideri che il modello segua.
- Documenti (Documents) – contesti lunghi come PDF, basi di conoscenza o estratti di policy.
- Domande dell'utente (User questions) – la query in tempo reale che varia a ogni turno.
Se modifichi qualsiasi token prima di un breakpoint, la voce di cache viene invalidata e il modello deve rielaborare tutto ciò che segue.
Limiti nascosti da rispettare
- Dimensione minima del blocco – Opus 5 mette in cache solo i blocchi che contengono almeno 512 token. Qualsiasi cosa più piccola viene completamente esclusa dalla cache.
- Timestamp bug – inserire un timestamp variabile all'interno di un blocco in cache garantisce un fallimento (miss), perché il testo del blocco non corrisponderà mai esattamente.
- Look-back di 20 blocchi – il servizio scansiona solo gli ultimi 20 blocchi per trovare una corrispondenza. Le sessioni prolungate che avanzano rapidamente possono superare la finestra della cache.
- Richieste parallele – inviare diverse richieste identiche nello stesso istante risulterà in un fallimento per tutte, poiché la cache viene popolata solo dopo il completamento della prima richiesta. Scalda la cache con una singola chiamata, quindi invia le restanti.
Visualizzare il risparmio nella risposta API
Ogni risposta riporta tre contatori di token:
cache_read_input_tokens– token provenienti da un hit della cache.cache_creation_input_tokens– token scritti nella cache in questa richiesta.input_tokens– i nuovi token che non sono stati messi in cache.
Somma i tre numeri per ottenere il totale dei token considerati dal modello per quel turno. Se entrambi i campi della cache sono pari a zero, la richiesta non ha trovato la cache; controlla la dimensione del blocco e il posizionamento del breakpoint.
In sintesi: Caricando in anticipo il contesto immutabile e lasciando che l'API di prompt-caching di Claude Opus 5 faccia il lavoro pesante, trasformi una spesa ricorrente di token in un addebito una tantum. Il risultato è una drastica riduzione dei costi per qualsiasi chatbot che faccia ripetutamente riferimento allo stesso system prompt o set di documenti, a patto di rispettare la soglia minima di token, evitare marcatori variabili all'interno dei blocchi in cache e mantenere il contenuto idoneo alla cache entro l'orizzonte dei 20 blocchi.