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:
- Ferramentas de servidor, como busca na web, web fetch, execução de código e busca de ferramentas (todas as ferramentas de servidor, exceto a ferramenta advisor)
- O conector MCP
- Blocos
imageoudocumentcom uma fonteurloufile
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()){ "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()){ "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()){ "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()){ "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()){ "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 uso | Requisições por minuto (RPM) |
|---|---|
| Start | 5.000 |
| Build | 10.000 |
| Scale | 20.000 |
Perguntas frequentes
Não, a contagem de tokens fornece uma estimativa sem usar a lógica de cache. Embora você possa fornecer blocos cache_control em sua requisição de contagem de tokens, o cache de prompt ocorre apenas durante a criação real de mensagens.
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
Claude API
- APIs
- Messages API
- Managed Agents Não compatível
- Modelos
- Todos os modelos
Amazon Bedrock
- API
- Messages API
- Modelos
- Todos os modelos
Amazon Bedrock (bedrock-runtime)
- API
- Messages API
- Modelos
- Todos os modelos
Claude Platform on AWS
- APIs
- Messages API
- Managed Agents Não compatível
- Modelos
- Todos os modelos
Claude Models on Google Cloud (Anthropic managed)
- APIs
- Messages API
- Managed Agents Não compatível
- Modelos
- Todos os modelos
Claude Models on Google Cloud (Google managed)
- API
- Messages API
- Modelos
- Todos os modelos
Microsoft Foundry
- API
- Messages API
- Modelos
- Todos os modelos
Tratamento de dados
Visão geral do tratamento de dadosEndpoints aplicáveis
/v1/messages/count_tokens
Exclui Modelos cobertos
Contagem de tokens antes do envio das requisições.
Esta página foi útil?