Claude Platform Docs
MessagesGestione del contesto

Conteggio dei token

Conta i token in un messaggio prima di inviarlo a Claude. Usa i conteggi dei token per gestire limiti di velocità e costi, prendere decisioni di instradamento dei modelli e adattare i prompt a una lunghezza target.

Il "token counting" (conteggio dei token) ti consente di determinare il numero di token in un messaggio prima di inviarlo a Claude. Questo ti aiuta a prendere decisioni informate sui tuoi prompt e sul tuo utilizzo. Con il conteggio dei token, puoi:

  • Gestire in modo proattivo i "rate limits" (limiti di velocità) e i costi
  • Prendere decisioni intelligenti di instradamento dei modelli
  • Ottimizzare i prompt per una lunghezza specifica

Come contare i token di un messaggio

L'endpoint di conteggio dei token accetta lo stesso elenco strutturato di input usato per creare un messaggio, incluso il supporto per "system prompts" (prompt di sistema), strumenti, immagini e PDF. La risposta contiene il numero totale di token di input.

Questo endpoint restituisce un invalid_request_error per alcuni input che la Messages API accetta: gli strumenti server come la ricerca web, il recupero web, l'esecuzione di codice e la ricerca di strumenti (tutti gli strumenti server tranne lo strumento advisor), il connettore per il "Model Context Protocol", o MCP, e i blocchi image o document con una sorgente url o file. Invia immagini e PDF in base64 per contarli. Per le richieste che usano strumenti server o server MCP, la risposta della Messages API riporta i token utilizzati nel suo oggetto usage.

Modelli supportati

Tutti i modelli attivi supportano il conteggio dei token.

Contare i token in messaggi di base

client = anthropic.Anthropic()

response = client.messages.count_tokens(
    model="claude-opus-5-5",
    system="You are a scientist",
    messages=[{"role": "user", "content": "Hello, Claude"}],
)

print(response.json())
Output
{ "input_tokens": 14 }

Contare i token in messaggi con strumenti

client = anthropic.Anthropic()

response = client.messages.count_tokens(
    model="claude-opus-5-5",
    tools=[
        {
            "name": "get_weather",
            "description": "Get the current weather in a given location",
            "input_schema": {
                "type": "object",
                "properties": {
                    "location": {
                        "type": "string",
                        "description": "The city and state, e.g. San Francisco, CA",
                    }
                },
                "required": ["location"],
            },
        }
    ],
    messages=[{"role": "user", "content": "What's the weather like in San Francisco?"}],
)

print(response.json())
Output
{ "input_tokens": 403 }

Contare i token in messaggi con immagini

import base64
import httpx2

image_url = "https://platform.claude.com/docs/images/vision-example.jpg"
image_media_type = "image/jpeg"
image_data = base64.standard_b64encode(httpx2.get(image_url).content).decode("utf-8")

client = anthropic.Anthropic()

response = client.messages.count_tokens(
    model="claude-opus-5-5",
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "image",
                    "source": {
                        "type": "base64",
                        "media_type": image_media_type,
                        "data": image_data,
                    },
                },
                {"type": "text", "text": "Describe this image"},
            ],
        }
    ],
)
print(response.json())
Output
{ "input_tokens": 1028 }

Un blocco immagine incorporato che imposta "oversized_image": "error" viene rifiutato al momento del conteggio esattamente come lo rifiuterebbe la Messages API.

Contare i token in messaggi con thinking

client = anthropic.Anthropic()

response = client.messages.count_tokens(
    model="claude-opus-5-5",
    thinking={"type": "adaptive"},
    messages=[
        {
            "role": "user",
            "content": "Are there an infinite number of prime numbers such that n mod 4 == 3?",
        },
        {
            "role": "assistant",
            "content": [
                {
                    "type": "thinking",
                    "thinking": "This is a nice number theory question. Let's think about it step by step...",
                    "signature": "EuYBCkQYAiJAgCs1le6/Pol5Z4/JMomVOouGrWdhYNsH3ukzUECbB6iWrSQtsQuRHJID6lWV...",
                },
                {
                    "type": "text",
                    "text": "Yes, there are infinitely many prime numbers p such that p mod 4 = 3...",
                },
            ],
        },
        {"role": "user", "content": "Can you write a formal proof?"},
    ],
)

print(response.json())
Output
{ "input_tokens": 88 }

Contare i token in messaggi con PDF

import base64
import anthropic

client = anthropic.Anthropic()

with open("/path/to/document.pdf", "rb") as pdf_file:
    pdf_base64 = base64.standard_b64encode(pdf_file.read()).decode("utf-8")

response = client.messages.count_tokens(
    model="claude-opus-5-5",
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "document",
                    "source": {
                        "type": "base64",
                        "media_type": "application/pdf",
                        "data": pdf_base64,
                    },
                },
                {"type": "text", "text": "Please summarize this document."},
            ],
        }
    ],
)

print(response.json())
Output
{ "input_tokens": 2188 }

Conteggi dei token sui modelli Claude Fable e Claude Mythos

Claude Fable 5.1, Claude Mythos 5.1, Claude Fable 5 e Claude Mythos 5 condividono il tokenizer introdotto con Claude Opus 4.7. Un prompt produce lo stesso conteggio su tutti e quattro, e circa il 30 percento in più rispetto ai modelli precedenti a Claude Opus 4.7 (l'aumento esatto dipende dal contenuto). L'endpoint di conteggio dei token conta secondo il tokenizer del model che passi. Per misurare la differenza per il tuo carico di lavoro, conta la stessa richiesta due volte, una con il tuo modello attuale e una con il modello a cui intendi passare, e confronta i due valori di input_tokens.


Prezzi e limiti di velocità

Il conteggio dei token è gratuito ma soggetto a limiti di velocità in richieste al minuto basati sul tuo livello di utilizzo. Se hai bisogno di limiti più elevati, usa Request rate limit increase nella pagina Limiti di velocità.

Livello di utilizzoRichieste al minuto (RPM)
Start5.000
Build10.000
Scale20.000

Domande frequenti


Passaggi successivi

Leggi il riferimento API completo per l'endpoint di conteggio dei token.

Usa i conteggi dei token per mantenere i prompt entro la finestra di contesto di un modello.

Controlla i conteggi dei token prima di inviare una richiesta per rimanere entro il tuo livello di utilizzo.

Riduci costi e latenza sui prompt ripetuti memorizzando nella cache i prefissi dei prompt.

Compatibility

Supported platforms
  • Claude API
  • Claude Platform on AWS
  • Amazon Bedrock
  • Google Cloud
  • Microsoft Foundry

Was this page helpful?