Effort di ragionamento e token di pensiero: perché pensare costa di più

La tua richiesta era una sola domanda fattuale. La risposta era di tre righe. Il contatore di output dice migliaia di token. Non è un bug: prima di rispondere, molti modelli pensano in un blocco nascosto, e quei token di pensiero vengono fatturati come token di output. L'impostazione effort decide quanto di quel pensiero avviene, e max_tokens deve lasciare spazio, altrimenti si ottiene una risposta troncata o vuota.

Cosa fa il modello prima di rispondere#

Pensa a un esame. Puoi scrivere la risposta subito, oppure riempire prima una pagina di brutta. La brutta spesso dà un risultato migliore su un problema difficile, ma la carta non è gratis. Il ragionamento è quella brutta, e viene contato in token come tutto il resto.

La documentazione di Anthropic sul pensiero esteso (verificata il 23 ottobre 2026) dice che i token di pensiero fanno parte dei token di output fatturati, e la risposta ti dice quanti: usage.output_tokens_details.thinking_tokens. Supponi che una risposta torni con questo blocco di utilizzo (numeri di esempio):

"usage": {
  "input_tokens": 480,
  "output_tokens": 2150,
  "output_tokens_details": { "thinking_tokens": 1900 }
}

Ti vengono fatturati 2.150 token di output. Il pensiero ne ha presi 1.900, quindi il testo che leggi effettivamente è 2.150 − 1.900 = 250 token. Lo stesso vale anche quando il testo del pensiero non ti viene restituito: conta comunque. Se vuoi prima la differenza tra input e output spiegata, inizia da token di input vs output.

Effort: la manopola del pensiero#

Nell'API di Claude la manopola è output_config.effort. La pagina di Anthropic sull'effort (verificata il 23 ottobre 2026) elenca cinque livelli: low, medium, high, xhigh, max. Tre dettagli contano per un principiante:

• Influisce su ogni token di output, non solo sul pensiero: testo, chiamate agli strumenti e pensiero insieme.
• È un segnale comportamentale, non un budget rigido. Un effort più basso significa meno token al prezzo di alcune capacità; a effort basso Claude può saltare del tutto il pensiero su un problema semplice.
• Il valore predefinito è medium su Claude Opus 5.5 e Claude Haiku 5.5, e high sulla maggior parte degli altri modelli che supportano il parametro. Impostare esplicitamente il valore predefinito equivale a ometterlo.

I livelli vengono ricalibrati per modello, quindi high su un modello non è la stessa quantità di pensiero di high su un altro, e non tutti i modelli accettano tutti i livelli. In un video pubblicato qualcuno ha eseguito ogni livello di effort di Claude Opus 5.5 sullo stesso compito di motion graphics e ha confrontato le immagini. È un buon modo per vedere cosa si guadagna con più pensiero. Non ti dirà la tua bolletta, perché il tuo compito non è il loro.

Una richiesta per una domanda semplice, con effort abbassato:

{
  "model": "claude-opus-5-5",
  "max_tokens": 4000,
  "output_config": { "effort": "low" },
  "messages": [
    { "role": "user", "content": "What is the capital of Australia?" }
  ]
}

La trappola della risposta vuota: il pensiero conta verso max_tokens#

Ecco come va storto. Ti aspetti una risposta di due frasi, quindi imposti max_tokens a 300. Il modello inizia a pensare, spende i 300 nella sua brutta, raggiunge il limite e si ferma. Ottieni una risposta vuota o una frase che finisce a metà parola, e il motivo di arresto dice max_tokens.

La documentazione è esplicita: max_tokens è un limite rigido sull'output totale, pensiero più testo della risposta, e il pensiero conta anche quando il suo contenuto non viene restituito. A effort high e superiori, Anthropic dice di impostare un valore grande.

In pratica:

1. Prendi la lunghezza della risposta che vuoi.
2. Aggiungi spazio generoso per il pensiero. Qualche migliaio di token è un inizio sensato per qualsiasi cosa sopra low.
3. Controlla il motivo di arresto dopo le prime esecuzioni. Se dice ancora max_tokens, alza il limite. Se la risposta è completa, puoi abbassarlo.

Il troncamento in sé, con finish_reason e la finestra di contesto, è trattato in perché una risposta AI si ferma a metà frase.

Cosa fa il ragionamento lungo alla bolletta#

Supponi di gestire un bot di supporto con 2.000 ticket al giorno. Ogni ticket è circa 500 token in input. Una risposta breve e diretta è circa 400 token in output. Lo stesso ticket con un lungo ragionamento nascosto è circa 4.000 token in output. Queste sono assunzioni per l'esempio; per i tuoi numeri vedi quanti token usa una richiesta.

Al giorno sono 2.000 × 500 = 1.000.000 token di input, e o 2.000 × 400 = 800.000 token di output o 2.000 × 4.000 = 8.000.000 token di output. Il lettore del ticket vede le stesse due righe in entrambi i casi. L'unica cosa che è cambiata è il volume di output, e l'output è il lato che il ragionamento gonfia.

L'aritmetica è la stessa su qualsiasi modello che fattura il ragionamento nascosto: token di output × il prezzo di output. Per DeepSeek-V4-Flash quel prezzo è $0.10 per 1M token di output, e il suo lato output è più economico del prezzo di riferimento di OpenRouter. Risponde anche fino a 32.768 token alla volta con un contesto di 380K, quindi un max_tokens grande ci sta. I prezzi sono fissi per modello, senza ore di punta, e la tabella sopra si ricalcola dal listino live. Tutti i prezzi sono sulla pagina dei prezzi; la pagina DeepSeek ha i dettagli del modello.

Ecco una richiesta da inviare tu stesso. È un semplice compito di riassunto, quindi non serve un lungo ragionamento, e il limite lascia molto spazio:

curl https://api.cheaptokens.dev/v1/chat/completions \
  -H "Authorization: Bearer $CHEAPTOKENS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek-ai/DeepSeek-V4-Flash-0731",
    "max_tokens": 2000,
    "messages": [
      {"role": "user", "content": "Summarize in one sentence: A token is a small piece of text that a model reads and writes, and APIs bill by the token."}
    ]
  }'

Nella risposta, usage.completion_tokens è ciò per cui paghi sul lato output, e finish_reason dovrebbe essere stop. Se dice length, il limite ha tagliato la risposta. Per ottenere la chiave e la prima chiamata: docs.

Quale effort per quale lavoro#

• Un fatto, un riassunto di una riga, un'etichetta. Effort minimo. È il caso dell'inizio dell'articolo: non serve la brutta.
• Scrittura quotidiana, una breve spiegazione, una modifica semplice. Il valore predefinito per il modello. Cambialo solo dopo aver visto quanto costano le risposte.
• Un bug complicato, un piano multi-step, un problema di matematica. high o superiore, e un max_tokens grande. Qui il pensiero extra è il punto.

In caso di dubbio, esegui lo stesso prompt a due livelli, confronta le risposte e confronta output_tokens. Se la risposta più economica è altrettanto buona, hai trovato il tuo livello.

Migrare una vecchia richiesta: l'errore 400#

Il codice più vecchio controllava il pensiero con un budget di token. Su Claude 4.7 e modelli successivi (Opus 5.5, Sonnet 5.5, Haiku 5.5, Fable 5.1) quella forma viene rifiutata con un errore 400. Si passa al pensiero adattivo e si imposta la profondità con effort:

// before: returns 400 on newer models
"thinking": { "type": "enabled", "budget_tokens": 8000 }

// after
"thinking": { "type": "adaptive" },
"output_config": { "effort": "medium" }

Un'altra trappola: su Opus 5.5 il pensiero adattivo è sempre attivo, e thinking: { "type": "disabled" } restituisce 400 a ogni livello di effort. Haiku 5.5 consente di disabilitare il pensiero a effort high o inferiore. Se vuoi meno pensiero su Opus 5.5, abbassa l'effort invece di disattivarlo.

Agenti e chat lunghe: scegli un livello e mantienilo#

Se il tuo prompt è in cache, cambiare l'effort di primo livello tra le richieste invalida i punti di interruzione della cache per quella conversazione. Per un ciclo di agente o una chat lunga, scegli un livello in anticipo. Alcuni modelli offrono effort per messaggio in beta che mantiene la cache, cosa che vale la pena guardare una volta che le basi sono a posto. Le chat lunghe hanno un secondo fattore di costo, trattato in perché una chat lunga costa di più.

Provalo sulla tua richiesta#

1. Invia il tuo prompt reale una volta e leggi usage: quanti token di output, e quanti di essi sono pensiero.
2. Abbassa l'effort di un gradino e invialo di nuovo. Confronta le risposte e i conteggi.
3. Imposta max_tokens alla risposta che vuoi più spazio per il pensiero, e controlla il motivo di arresto.

Poi inserisci i tuoi conteggi di token nella tabella dei prezzi live sulla pagina dei prezzi e hai una stima mensile.