Prompt caching: come ridurre i costi API di GPT-6 e Claude

Il prompt caching è la voce che più spesso trovo sbagliata quando apro il codice di un agente AI che "costa troppo". Il modello va bene, i prompt vanno bene, ma ogni chiamata rielabora da zero le stesse istruzioni, le stesse definizioni degli strumenti e la stessa cronologia. E le paghi ogni volta a prezzo pieno.

Il 22 settembre 2026 OpenAI ha rinnovato il prompt caching per la famiglia GPT-6, pochi giorni dopo che Anthropic ha portato la lettura dalla cache di Claude Opus 5.5 a 0,20 $ per milione di token. È il momento giusto per mettere in fila come funziona su GPT-6, Claude e Gemini, con i numeri ufficiali, il codice e l'errore che fa saltare la cache nove volte su dieci.

Cos'è il prompt caching in parole semplici

Quando un modello legge il tuo input, calcola degli stati intermedi (le cosiddette chiavi e valori della cache KV) per ogni token. Il prompt caching salva quel lavoro per la parte iniziale del prompt che non cambia, cioè il prefisso. Se la richiesta successiva inizia con lo stesso identico prefisso, il modello riprende da lì invece di ricalcolare tutto.

Tre effetti pratici:

• Costo: i token letti dalla cache costano una frazione di quelli normali, in genere un decimo o meno.
• Velocità: il tempo prima del primo token di risposta si accorcia, soprattutto con contesti lunghi.
• Nessun effetto sulla risposta: il modello genera l'output esattamente come farebbe senza cache. Non è una cache delle risposte, è una cache del lavoro fatto sull'input.

La regola che conta più di tutte: la cache funziona solo sul prefisso identico. Basta un carattere diverso all'inizio e tutto quello che viene dopo va ricalcolato.

Prompt caching a confronto: GPT-6, Claude e Gemini

I tre provider fanno la stessa cosa in modi diversi. Questa è la tabella che uso come riferimento quando scelgo come impostare un progetto.

Una differenza pratica salta subito all'occhio: su OpenAI e Gemini la cache implicita parte da sola, su Claude no. Se usi Claude via API e non hai mai scritto cache_control nel codice, con buona probabilità stai pagando tutto a prezzo pieno.

Quanto si risparmia davvero: un conto su Claude Opus 5.5

Prendo un caso tipico: un agente con system prompt e definizioni degli strumenti per 20.000 token, che fa 50 chiamate in una sessione, ognuna entro 5 minuti dalla precedente. Uso i prezzi ufficiali di Claude Opus 5.5: 4 $ per milione di token in input, 5 $ per la scrittura in cache a 5 minuti, 0,20 $ per la lettura.

• Senza prompt caching: 50 chiamate per 20.000 token fanno 1 milione di token, cioè 4,00 $ solo per il prefisso ripetuto.
• Con prompt caching: una scrittura da 20.000 token costa 0,10 $, poi 49 letture per 980.000 token costano circa 0,20 $. Totale circa 0,30 $.

Sul solo prefisso si passa da 4 $ a 30 centesimi, un risparmio intorno al 92%. Il resto della richiesta (il messaggio nuovo dell'utente e l'output) si paga come sempre.

Su GPT-6 il ragionamento è lo stesso con moltiplicatori diversi. La documentazione di OpenAI fa questo esempio: scrivere un prefisso una volta e rileggerlo nove volte costa 2,15 volte il suo prezzo normale, contro 10 volte senza cache. Se ti interessa il confronto dei prezzi base tra i modelli, l'ho fatto nell'articolo su GPT-6 Sol e Luna.

Come attivare il prompt caching su Claude

Il modo più semplice è il caching automatico: un solo campo cache_control al livello principale della richiesta. Il sistema mette il punto di cache sull'ultimo blocco utile e lo sposta in avanti man mano che la conversazione cresce.

import anthropic

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=1024,
    cache_control={"type": "ephemeral"},
    system="Istruzioni stabili del mio agente...",
    messages=[{"role": "user", "content": "Domanda dell'utente"}],
)

print(response.usage)

Quando le parti del prompt cambiano con ritmi diversi, uso i breakpoint espliciti (fino a 4): uno dopo gli strumenti, uno dopo le istruzioni, uno dopo i documenti di contesto. L'ordine con cui Claude costruisce la cache è sempre strumenti, poi system, poi messaggi. Cambiare una definizione di strumento invalida tutto quello che segue.

Per la durata di 1 ora si aggiunge "ttl": "1h" dentro cache_control. Conviene quando tra una richiesta e l'altra passano più di 5 minuti ma meno di un'ora, per esempio un utente che risponde con calma in chat.

Come funziona il prompt caching su GPT-6

Su GPT-6 la cache implicita è già attiva e ora applica lo sconto ai prefissi riutilizzati entro 30 minuti. Le novità del 22 settembre servono a controllarla meglio:

• Breakpoint espliciti: con prompt_cache_options.mode impostato su explicit decidi tu dove finisce la parte da salvare, marcando il blocco con prompt_cache_breakpoint. Quello che sta dopo l'ultimo breakpoint non viene scritto in cache e non paga il sovrapprezzo di scrittura.
• Cambiare il livello di ragionamento senza perdere la cache: invece di modificare reasoning.effort nella richiesta, si aggiunge in coda un elemento configuration_update.
• Preriscaldamento: con prompt_cache_options.prewarm a true il prefisso viene preparato prima che arrivi l'utente, senza generare output.
• Dashboard e diagnostica: la piattaforma mostra il tasso di riscontri e, in caso di mancato riscontro, il motivo (per esempio strumenti cambiati).

{
  "model": "gpt-6-sol",
  "prompt_cache_options": { "mode": "explicit" },
  "input": [
    {
      "role": "developer",
      "content": [{
        "type": "input_text",
        "text": "Istruzioni stabili e materiale di riferimento...",
        "prompt_cache_breakpoint": { "mode": "explicit" }
      }]
    },
    { "role": "user", "content": "Domanda dell'utente..." }
  ]
}

Nella risposta controllo sempre usage.input_tokens_details.cached_tokens e cache_write_tokens: sono gli unici numeri che dicono se la cache sta lavorando davvero.

Gemini: cache implicita ed esplicita

Su Gemini il caching implicito è attivo di default, ma senza garanzia di risparmio: se la richiesta colpisce la cache, lo sconto arriva da solo. Il minimo sui modelli recenti come Gemini 3.8 Flash è di 4.096 token, quindi i prompt brevi restano fuori.

Per avere la garanzia serve il caching esplicito, oggi in beta e disponibile solo con l'API generateContent (non con la Interactions API). Si crea un oggetto cache con client.caches.create, gli si dà un TTL (di default 1 ora) e lo si richiama nelle richieste successive. Qui si paga anche la conservazione per il tempo scelto, quindi ha senso solo su contesti grandi riusati spesso: un manuale, un repository, un video da interrogare più volte.

L'errore che rompe il prompt caching più spesso

Il caso che vedo più spesso è sempre lo stesso: una data, un orario o un dato dell'utente messi all'inizio del system prompt. "Oggi è il 25 settembre, sono le 10:32, l'utente si chiama Marco..." e sotto 15.000 token di istruzioni fisse. Il prefisso cambia a ogni chiamata, quindi la cache non viene mai riletta: su Claude paghi pure il sovrapprezzo di scrittura ogni volta.

Le regole che applico:

• Prima lo stabile, poi il variabile: strumenti e istruzioni fisse in cima, date e dati dell'utente in fondo.
• Non toccare gli strumenti a metà sessione: se un agente deve usare meno strumenti, li disattivo (su OpenAI con allowed_tools o tool_choice) invece di toglierli dalla lista.
• Attenzione a memoria e riassunti: un nodo che riscrive o accorcia la cronologia a ogni turno cambia il prefisso. Nei flussi n8n con agente AI e memoria su database è la prima cosa da verificare.
• Chiavi JSON in ordine stabile: alcuni linguaggi riordinano le chiavi degli oggetti, e un ordine diverso è un prefisso diverso.
• Sotto la soglia non succede niente: su Claude un prompt troppo corto non dà errore, semplicemente non va in cache. Se i campi di scrittura e lettura sono entrambi a zero, il motivo è quasi sempre questo.

Come verifico che il prompt caching funzioni

Non mi fido mai dell'impostazione, guardo i numeri della risposta. Su Claude i campi sono cache_creation_input_tokens e cache_read_input_tokens: alla prima chiamata deve salire il primo, dalla seconda in poi il secondo. Su OpenAI guardo cached_tokens e il tasso di riscontri nella dashboard. Su Gemini il conteggio è nei metadati di utilizzo della risposta.

Se usi Claude Code invece dell'API diretta, la cache la gestisce lo strumento: lì il lavoro è tenere stabile il contesto, evitare di cambiare modello a metà e usare con criterio i comandi che compattano la sessione. Sui piani in abbonamento i conti sono diversi, li trovi nella guida ai prezzi di Claude.

Quando il prompt caching non conviene

Non è sempre un guadagno. Non ne vale la pena quando il prefisso è sotto la soglia minima e allungarlo non ha senso, quando le richieste sono rare (più di 5 minuti di pausa su Claude, più di 30 su GPT-6) o quando ogni chiamata ha un contesto diverso. In questi casi con la scrittura in cache paghi solo il sovrapprezzo.

Dove invece rende di più: agenti con molti strumenti, chatbot con istruzioni lunghe, analisi ripetute sugli stessi documenti e qualsiasi flusso con decine di chiamate a catena. Se stai costruendo uno di questi e vuoi capire dove perdi soldi, è il lavoro che faccio nei progetti di automazione AI: puoi scrivermi dalla pagina contatti.