A contagem de tokens permite determinar o número de tokens em uma mensagem antes de enviá-la ao Claude, ajudando você a tomar decisões informadas sobre seus prompts e uso. Com a contagem de tokens, você pode:

  • Gerenciar proativamente limites de taxa e custos
  • Tomar decisões inteligentes de roteamento de modelos
  • Otimizar prompts para um comprimento específico

​
Como contar tokens de mensagens

O endpoint de contagem de tokens aceita a mesma lista estruturada de entradas para criar uma mensagem, incluindo suporte para prompts de sistema, ferramentas, imagens e PDFs. A resposta contém o número total de tokens de entrada.

A contagem de tokens deve ser considerada uma estimativa. Em alguns casos, o número real de tokens de entrada usados ao criar uma mensagem pode diferir por uma pequena quantidade.

​
Modelos suportados

O endpoint de contagem de tokens suporta os seguintes modelos:

  • Claude Opus 4
  • Claude Sonnet 4
  • Claude Sonnet 3.7
  • Claude Sonnet 3.5
  • Claude Haiku 3.5
  • Claude Haiku 3
  • Claude Opus 3

​
Contar tokens em mensagens básicas

import anthropic

client = anthropic.Anthropic()

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

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

​
Contar tokens em mensagens com ferramentas

As contagens de tokens de ferramentas de servidor só se aplicam à primeira chamada de amostragem.

import anthropic

client = anthropic.Anthropic()

response = client.messages.count_tokens(
    model="claude-opus-4-20250514",
    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())
JSON
{ "input_tokens": 403 }

​
Contar tokens em mensagens com imagens

#!/bin/sh

IMAGE_URL="https://upload.wikimedia.org/wikipedia/commons/a/a7/Camponotus_flavomarginatus_ant.jpg"
IMAGE_MEDIA_TYPE="image/jpeg"
IMAGE_BASE64=$(curl "$IMAGE_URL" | base64)

curl https://api.anthropic.com/v1/messages/count_tokens \
     --header "x-api-key: $ANTHROPIC_API_KEY" \
     --header "anthropic-version: 2023-06-01" \
     --header "content-type: application/json" \
     --data \
'{
    "model": "claude-opus-4-20250514",
    "messages": [
        {"role": "user", "content": [
            {"type": "image", "source": {
                "type": "base64",
                "media_type": "'$IMAGE_MEDIA_TYPE'",
                "data": "'$IMAGE_BASE64'"
            }},
            {"type": "text", "text": "Describe this image"}
        ]}
    ]
}'
JSON
{ "input_tokens": 1551 }

​
Contar tokens em mensagens com pensamento estendido

Veja aqui mais detalhes sobre como a janela de contexto é calculada com pensamento estendido

  • Blocos de pensamento de turnos anteriores do assistente são ignorados e não contam para seus tokens de entrada
  • O pensamento do turno atual do assistente conta para seus tokens de entrada
curl https://api.anthropic.com/v1/messages/count_tokens \
    --header "x-api-key: $ANTHROPIC_API_KEY" \
    --header "content-type: application/json" \
    --header "anthropic-version: 2023-06-01" \
    --data '{
      "model": "claude-opus-4-20250514",
      "thinking": {
        "type": "enabled",
        "budget_tokens": 16000
      },
      "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. Lets 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?"
        }
      ]
    }'
JSON
{ "input_tokens": 88 }

​
Contar tokens em mensagens com PDFs

A contagem de tokens suporta PDFs com as mesmas limitações da API de Mensagens.

curl https://api.anthropic.com/v1/messages/count_tokens \
    --header "x-api-key: $ANTHROPIC_API_KEY" \
    --header "content-type: application/json" \
    --header "anthropic-version: 2023-06-01" \
    --data '{
      "model": "claude-opus-4-20250514",
      "messages": [{
        "role": "user",
        "content": [
          {
            "type": "document",
            "source": {
              "type": "base64",
              "media_type": "application/pdf",
              "data": "'$(base64 -i document.pdf)'"
            }
          },
          {
            "type": "text",
            "text": "Please summarize this document."
          }
        ]
      }]
    }'
JSON
{ "input_tokens": 2188 }

​
Preços e limites de taxa

A contagem de tokens é gratuita para uso, mas está sujeita a limites de solicitações por minuto com base em seu nível de uso. Se você precisar de limites mais altos, entre em contato com vendas através do Console Anthropic.

Nível de usoSolicitações por minuto (RPM)
1100
22.000
34.000
48.000

A contagem de tokens e a criação de mensagens têm limites de taxa separados e independentes — o uso de um não conta para os limites do outro.

​
Perguntas frequentes