토큰 카운팅을 사용하면 Claude에게 메시지를 보내기 전에 메시지의 토큰 수를 결정할 수 있어, 프롬프트와 사용량에 대한 정보에 입각한 결정을 내릴 수 있습니다. 토큰 카운팅을 통해 다음을 할 수 있습니다:
  • 속도 제한 및 비용을 사전에 관리
  • 스마트한 모델 라우팅 결정
  • 특정 길이로 프롬프트 최적화

​
메시지 토큰을 카운트하는 방법

토큰 카운팅 엔드포인트는 시스템 프롬프트, 도구, 이미지, PDF 지원을 포함하여 메시지 생성을 위한 동일한 구조화된 입력 목록을 허용합니다. 응답에는 총 입력 토큰 수가 포함됩니다.
토큰 수는 추정치로 간주되어야 합니다. 경우에 따라 메시지를 생성할 때 사용되는 실제 입력 토큰 수는 소량 차이가 날 수 있습니다.토큰 수에는 시스템 최적화를 위해 Anthropic에서 자동으로 추가한 토큰이 포함될 수 있습니다. 시스템에서 추가한 토큰에 대해서는 요금이 청구되지 않습니다. 청구는 귀하의 콘텐츠만 반영합니다.

​
지원되는 모델

모든 활성 모델이 토큰 카운팅을 지원합니다.

​
기본 메시지의 토큰 카운트

import anthropic

client = anthropic.Anthropic()

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

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

​
도구가 포함된 메시지의 토큰 카운트

서버 도구 토큰 수는 첫 번째 샘플링 호출에만 적용됩니다.
import anthropic

client = anthropic.Anthropic()

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

​
이미지가 포함된 메시지의 토큰 카운트

#!/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-sonnet-4-5",
    "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 }

​
확장 사고가 포함된 메시지의 토큰 카운트

확장 사고를 통한 컨텍스트 윈도우 계산 방법에 대한 자세한 내용은 여기를 참조하세요
  • 이전 어시스턴트 턴의 사고 블록은 무시되며 입력 토큰에 포함되지 않습니다
  • 현재 어시스턴트 턴의 사고는 입력 토큰에 포함됩니다
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-sonnet-4-5",
      "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 }

​
PDF가 포함된 메시지의 토큰 카운트

토큰 카운팅은 Messages API와 동일한 제한사항으로 PDF를 지원합니다.
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-sonnet-4-5",
      "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 }

​
가격 및 속도 제한

토큰 카운팅은 무료로 사용할 수 있지만 사용 등급에 따른 분당 요청 수 제한이 적용됩니다. 더 높은 제한이 필요한 경우 Claude Console을 통해 영업팀에 문의하세요.
사용 등급분당 요청 수 (RPM)
1100
22,000
34,000
48,000
토큰 카운팅과 메시지 생성은 별도의 독립적인 속도 제한을 가지고 있습니다 — 하나의 사용량이 다른 것의 제한에 영향을 주지 않습니다.

​
FAQ

아니요, 토큰 카운팅은 캐싱 로직을 사용하지 않고 추정치를 제공합니다. 토큰 카운팅 요청에 cache_control 블록을 제공할 수 있지만, 프롬프트 캐싱은 실제 메시지 생성 중에만 발생합니다.