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.
A "token counting" (contagem de tokens) permite que você determine 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 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 tokens de mensagens
O endpoint de contagem de tokens 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 entrada.
Modelos suportados
Todos os modelos ativos suportam contagem de tokens, incluindo Claude Opus 5 e Claude Sonnet 5.
Contar tokens em mensagens básicas
client = anthropic.Anthropic()
response = client.messages.count_tokens(
model="claude-opus-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",
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",
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-sonnet-4-6",
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. 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",
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 no Claude Fable 5 e no Claude Mythos 5
O Claude Fable 5 e o Claude Mythos 5 usam o tokenizador introduzido com o Claude Opus 4.7, que produz aproximadamente 30 por cento mais tokens do que os modelos anteriores ao Claude Opus 4.7 para o mesmo texto. O aumento exato depende do conteúdo e do formato da carga de trabalho. O endpoint de contagem de tokens retorna a contagem de acordo com o tokenizador do model que você informa; portanto, para medir a diferença na sua carga de trabalho, conte a mesma requisição duas vezes: uma vez com seu modelo atual e outra com model: "claude-fable-5" (ou "claude-mythos-5"), e 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 Request rate limit increase na página Rate limits.
| Nível de uso | Requisições por minuto (RPM) |
|---|---|
| Start | 2.000 |
| Build | 4.000 |
| Scale | 8.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 na sua requisição de contagem de tokens, o "prompt caching" (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.
Compatibility
| Supported platforms |
|
|---|
Was this page helpful?