토큰 카운팅 (Token Counting)

요청을 보내기 전에 그 메시지가 토큰으로는 얼마나 되는지 미리 알 수 있다면, 속도 제한이나 비용을 능동적으로 관리할 수 있어요. 토큰 카운팅은 바로 그 역할을 하는 API예요. 메시지를 Claude에 보내기 전에 토큰 수를 세어서 프롬프트를 목표 길이에 맞추고, 모델 라우팅 결정도 내릴 수 있어요.

출처: https://platform.claude.com/docs/en/build-with-claude/token-counting

무엇을 할 수 있나요

토큰 카운팅으로 이런 것들을 할 수 있어요.

속도 제한과 비용을 미리 관리해요.
똑똑한 모델 라우팅 결정을 내려요.
프롬프트를 특정 길이로 최적화해요.

토큰 카운팅 엔드포인트(/v1/messages/count_tokens)는 메시지 생성과 같은 구조화된 입력 목록을 받아요. 시스템 프롬프트는 물론 도구, 이미지, PDF까지 지원해요. 응답은 총 입력 토큰 수를 돌려줘요.

사용 방법

모든 활성 모델이 토큰 카운팅을 지원해요. Claude Opus 5와 Claude Sonnet 5를 포함한 현재 모델 전부 해당해요.

Python SDK에서는 client.messages.count_tokens()로 호출해요. 간단한 텍스트 예시는 이렇게 돼요.

client = anthropic.Anthropic()

response = client.messages.count_tokens(
    model="claude-opus-5",
    messages=[{"role": "user", "content": "What's the weather like in San Francisco?"}],
)

print(response.json())

이 요청은 { "input_tokens": 403 } 같은 응답을 돌려줘요. 도구 정의를 넣으면 도구가 차지하는 토큰까지 합산돼요. 도구 tools 배열을 함께 넘기면 그 정의가 토큰 수에 포함되는 걸 확인할 수 있어요.

주의할 점

Claude Opus 4.7부터 도입된 토크나이저를 쓰는 Claude Fable 5와 Claude Mythos 5는, 같은 텍스트라도 그 전 모델들보다 토큰이 대략 30% 정도 더 나올 수 있어요. 정확한 증가율은 콘텐츠와 작업 형태에 따라 달라져요. 토큰 카운팅 엔드포인트는 넘긴 model의 토크나이저 기준으로 수를 돌려주기 때문에, 차이를 측정하려면 같은 요청을 현재 모델로 한 번, "claude-fable-5"(또는 "claude-mythos-5")로 한 번 세어서 두 input_tokens를 비교하면 돼요.

또한 토큰 카운팅은 무료로 사용할 수 있지만, 사용 등급에 따른 분당 요청 수(RPM) 속도 제한을 받아요. Start 등급은 2,000, Build 등급은 4,000, Scale 등급은 8,000 RPM이에요. 더 높은 한도가 필요하면 Rate limits 페이지에서 요청하세요.

더 알아보기

컨텍스트 윈도우 안에서 프롬프트를 관리하는 법은 «컨텍스트 윈도우» 문서를 봐요.
반복되는 프롬프트의 비용과 지연을 줄이는 법은 «프롬프트 캐싱» 문서를 봐요.
속도 제한의 자세한 내용은 «속도 제한 (Rate Limits)» 문서를 봐요.