Claude Platform Docs
MensagensGerenciamento de contexto

Contagem de tokens

Conte os tokens em uma mensagem antes de enviá-la ao Claude. Use contagens de tokens para gerenciar limites de taxa e custos, tomar decisões de roteamento de modelos e ajustar prompts a um comprimento desejado.

O “token counting” (contagem de tokens) permite determinar o número de tokens em uma mensagem antes de enviá-la ao Claude. Isso ajuda você a tomar decisões informadas sobre seus prompts e seu uso. Com a contagem de tokens, você pode:

  • Gerenciar proativamente “rate limits” (limites de taxa) e custos
  • Tomar decisões inteligentes de roteamento de modelos
  • Otimizar prompts para um comprimento específico

Como contar os tokens de uma mensagem

O endpoint de contagem de tokensPré-visualização disponível com links para a referência da API — pressione Tab até o foco entrar no cartão, Escape para voltar. aceita a mesma lista estruturada de entradas usada para criar uma mensagem, incluindo suporte a prompts do sistema, ferramentas, imagens e PDFs. A resposta contém o número total de tokens de entradaPré-visualização disponível com links para a referência da API — pressione Tab até o foco entrar no cartão, Escape para voltar..

Este endpoint retorna um invalid_request_error para algumas entradas que a Messages API aceita:

Envie imagens e PDFs como base64 para contá-los. Para solicitações que usam ferramentas de servidor ou servidores MCP, a resposta da Messages API informa os tokens usados em seu objeto usagePré-visualização disponível com links para a referência da API — pressione Tab até o foco entrar no cartão, Escape para voltar..

Modelos suportados

Todos os modelos ativos suportam contagem de tokens.

Contar tokens em mensagens básicas

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 }

Contar tokens em mensagens com ferramentas

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 }

Contar tokens em mensagens com imagens

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 }

Um bloco de imagem incorporado que define "oversized_image": "error" é rejeitado no momento da contagem exatamente como a Messages API o rejeitaria.

Contar tokens em mensagens com pensamento

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 }

Contar tokens em mensagens com PDFs

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 }

Contagens de tokens nos modelos Claude Fable e Claude Mythos

Claude Fable 5.2, Claude Mythos 5.2, Claude Fable 5.1, Claude Mythos 5.1, Claude Fable 5 e Claude Mythos 5 compartilham o tokenizador introduzido com o Claude Opus 4.7. Um prompt tem a mesma contagem nos seis, e aproximadamente 30 por cento maior do que em modelos anteriores ao Claude Opus 4.7 (o aumento exato depende do conteúdo). O endpoint de contagem de tokens conta usando o tokenizador do model que você informar. Para medir a diferença para sua carga de trabalho, conte a mesma requisição uma vez com seu modelo atual e outra com o modelo para o qual você planeja migrar. Em seguida, compare os dois valores de input_tokens.


Preços e limites de taxa

A contagem de tokens é gratuita, mas está sujeita a limites de taxa de requisições por minuto com base no seu nível de uso. Se você precisar de limites mais altos, use Solicitar aumento de nível na página Limites de taxa no Claude Console.

Nível de usoRequisições por minuto (RPM)
Start5.000
Build10.000
Scale20.000

Perguntas frequentes


Próximos passos

Leia a referência completa da API para o endpoint de contagem de tokens.

Use contagens de tokens para manter os prompts dentro da janela de contexto de um modelo.

Verifique as contagens de tokens antes de enviar uma requisição para permanecer dentro do seu nível de uso.

Reduza o custo e a latência em prompts repetidos armazenando prefixos de prompt em cache.

Disponibilidade

Contagem de tokens
APIs
  • Messages API
  • Managed Agents Não compatível
Modelos
  • Todos os modelos

Endpoints aplicáveis

  • /v1/messages/count_tokens
Retenção zero de dadosElegível

Exclui Modelos cobertos

Contagem de tokens antes do envio das requisições.

HIPAAElegível

Esta página foi útil?