토큰 카운팅

토큰 카운팅을 사용하면 Claude에 메시지를 보내기 전에 메시지의 토큰 수를 확인할 수 있어, 프롬프트와 사용량에 대해 정보에 기반한 결정을 내릴 수 있습니다. 토큰 카운팅을 통해 다음을 수행할 수 있습니다:

속도 제한 및 비용을 사전에 관리
스마트한 모델 라우팅 결정
특정 길이에 맞게 프롬프트 최적화

This feature is eligible for Zero Data Retention (ZDR). When your organization has a ZDR arrangement, data sent through this feature is not stored after the API response is returned.

메시지 토큰 카운팅 방법

토큰 카운팅 엔드포인트는 시스템 프롬프트, 도구, 이미지, PDF를 포함하여 메시지 생성을 위한 동일한 구조화된 입력 목록을 받습니다. 응답에는 총 입력 토큰 수가 포함됩니다.

토큰 수는 추정치로 간주해야 합니다. 경우에 따라 메시지 생성 시 실제 사용되는 입력 토큰 수가 소량 다를 수 있습니다.

토큰 수에는 시스템 최적화를 위해 Anthropic이 자동으로 추가한 토큰이 포함될 수 있습니다. 시스템이 추가한 토큰에 대해서는 요금이 청구되지 않습니다. 청구는 사용자의 콘텐츠만 반영합니다.

지원 모델

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

기본 메시지의 토큰 카운팅

import anthropic

client = anthropic.Anthropic()

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

print(response.json())

JSON

{ "input_tokens": 14 }

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

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

JSON

{ "input_tokens": 403 }

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

JSON

{ "input_tokens": 1551 }

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

확장 사고에서 컨텍스트 윈도우가 어떻게 계산되는지에 대한 자세한 내용은 여기를 참조하세요

이전 어시스턴트 턴의 사고 블록은 무시되며 입력 토큰에 포함되지 않습니다
현재 어시스턴트 턴의 사고는 입력 토큰에 포함됩니다

JSON

{ "input_tokens": 88 }

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

토큰 카운팅은 Messages API와 동일한 제한 사항으로 PDF를 지원합니다.

JSON

{ "input_tokens": 2188 }

가격 및 속도 제한

토큰 카운팅은 무료로 사용할 수 있지만 사용 티어에 따른 분당 요청 수 속도 제한이 적용됩니다. 더 높은 제한이 필요한 경우 Claude Console을 통해 영업팀에 문의하세요.

사용 티어	분당 요청 수 (RPM)
1	100
2	2,000
3	4,000
4	8,000

토큰 카운팅과 메시지 생성은 별도의 독립적인 속도 제한을 가지고 있습니다 -- 하나의 사용이 다른 하나의 제한에 영향을 미치지 않습니다.

FAQ

import anthropic

client = anthropic.Anthropic()

response = client.messages.count_tokens(
    model="claude-opus-4-6",
    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())

#!/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-6",
    "messages": [
        {"role": "user", "content": [
            {"type": "image", "source": {
                "type": "base64",
                "media_type": "'$IMAGE_MEDIA_TYPE'",
                "data": "'$IMAGE_BASE64'"
            }},
            {"type": "text", "text": "Describe this image"}
        ]}
    ]
}'

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-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. 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?"
        }
      ]
    }'

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-6",
      "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."
          }
        ]
      }]
    }'

메시지 토큰 카운팅 방법

지원 모델

기본 메시지의 토큰 카운팅

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

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

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

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

가격 및 속도 제한

FAQ

토큰 카운팅은 프롬프트 캐싱을 사용하나요?