Conteggio dei token di ragionamento
In questa pagina
Lezione riscritta il 3 novembre 2026 sulla base del riferimento API xAI (Chat Completions e Responses), della guida Reasoning e dell’esempio Reasoning Effort Evals dal cookbook: presso xAI,
completion_tokens(ooutput_tokens) conta solo la risposta visibile, il ragionamento viene conteggiato separatamente e il totale somma tutte e tre le voci; il limite di output non limita il ragionamento. La versione precedente affermava il contrario, utilizzava i campi di Chat Completions su una risposta dell’API Responses, impostava l’effort sugrok-4.20-0309-reasoningche non lo accetta e mostrava uno screenshot non corrispondente all’API; questi elementi sono stati corretti o rimossi. Fonti: Chat Completions · Responses · Reasoning Effort Evals.
Comprendere i token di ragionamento
I modelli di ragionamento producono due tipi di token: quelli per la risposta visibile e quelli per il processo di pensiero interno del modello. Capire come xAI li conteggia è essenziale per padroneggiare i costi e leggere correttamente le dashboard.
L’oggetto usage in Chat Completions
Ogni risposta include un oggetto usage che dettaglia il consumo. Ecco l’esempio tratto dal riferimento API Chat Completions di xAI:
{
"usage": {
"prompt_tokens": 32,
"completion_tokens": 9,
"total_tokens": 135,
"completion_tokens_details": {
"reasoning_tokens": 94
}
}
}
In questo esempio:
- prompt_tokens (32): token nel messaggio di input
- completion_tokens (9): token nella risposta visibile
- reasoning_tokens (94): token dedicati al ragionamento interno
- total_tokens (135): la somma di tutti e tre, 32 + 9 + 94
Il ragionamento non è quindi incluso in completion_tokens: vi si aggiunge. Fai attenzione se provieni da un’altra API dove la convenzione è diversa, o se la tua dashboard calcola la risposta visibile per sottrazione.
Accedere ai token di ragionamento nel codice
Nell’API Responses, le stesse informazioni portano nomi diversi: input_tokens, output_tokens per la risposta visibile e output_tokens_details.reasoning_tokens per il ragionamento.
response = client.responses.create(
model="grok-4.7",
input="Solve the integral of x^2 * e^x dx.",
reasoning={"effort": "high"},
)
visible_response = response.usage.output_tokens
reasoning = response.usage.output_tokens_details.reasoning_tokens
billed_output = visible_response + reasoning
print(f"Reasoning tokens: {reasoning}")
print(f"Response tokens: {visible_response}")
print(f"Reasoning share: {reasoning / billed_output * 100:.0f}%")
Imposti l’effort su grok-4.7, grok-4.6 e grok-4.5; grok-4.20-0309-reasoning ragiona sempre, senza parametro effort.
Fatturazione alla tariffa di output
I token di ragionamento sono fatturati alla tariffa dei token di output, come ci ricorda l’esempio Reasoning Effort Evals nel cookbook di xAI. Per grok-4.7 a 6 $ per milione di token di output (prompt inferiore a 200.000 token), ogni token di ragionamento costa quanto un token di risposta.
L’effort pesa quindi sulla fattura, ma non sempre quanto potresti immaginare. In questo stesso esempio, su trenta brevi ticket di supporto gestiti da grok-4.7, gli effort medium, high e xhigh hanno consumato circa la stessa quantità di ragionamento — intorno ai 600 token per risposta — mentre low ne ha consumati circa 140 ed è costato la metà, con punteggi tutti compresi tra l’87% e il 93%. Misura sui tuoi dati prima di scegliere.
Esempio di calcolo dei costi
# grok-4.7: 6,00 $/M token di output (prompt < 200k)
cost_per_token = 6.00 / 1_000_000
reasoning = 600
visible_response = 350
billed_output = reasoning + visible_response # 950
cost = billed_output * cost_per_token
print(f"Output cost: ${cost:.4f}") # $0.0057
Il ruolo di max_completion_tokens
Il limite di output — max_completion_tokens in Chat Completions, max_output_tokens nell’API Responses — si applica solo alla risposta visibile: secondo il riferimento API, i token di ragionamento e le chiamate di funzione non contano verso questo limite. Senza un valore specificato, il default è 128.000 token. Per limitare il ragionamento, devi impostare l’effort (lezione 10).
{
"model": "grok-4.7",
"messages": [
{"role": "user", "content": "Explain special relativity."}
],
"reasoning_effort": "medium",
"max_completion_tokens": 2000
}
Prezzi verificati il 3 novembre 2026 — i prezzi cambiano regolarmente: prima di qualsiasi calcolo di budget, controlla la tariffa attuale sulla pagina ufficiale dei modelli e dei prezzi xAI.
Punti chiave
- I token di ragionamento si trovano in
usage.completion_tokens_details.reasoning_tokens(Chat Completions) ousage.output_tokens_details.reasoning_tokens(Responses) - Presso xAI,
completion_tokenseoutput_tokenscontano solo la risposta visibile; il totale somma input, risposta e ragionamento - I token di ragionamento sono fatturati alla tariffa di output
- Il limite di output limita solo la risposta visibile; l’effort controlla il ragionamento
- La differenza di costo tra gli effort dipende dal compito: misurala sui tuoi dati