Claude API 토큰 카운팅으로 요청 전에 비용을 가늠한 방법 - 공식 문서 기준으로 정리한 기록

Claude API 토큰 카운팅으로 요청 전에 비용을 가늠한 방법 - 공식 문서 기준으로 정리한 기록

AI API 활용

공식 문서와 실제 사용 경험을 기준으로 정리했습니다.

API에 요청을 보내면 입력한 내용이 토큰 단위로 계산되고, 그 양에 따라 비용이 매겨집니다. 그런데 프롬프트가 길어지거나 문서를 통째로 넣을 때는 "이게 대체 몇 토큰이지?"가 궁금해집니다. 토큰 카운팅(Token Counting)은 실제 요청을 보내기 전에 입력이 몇 토큰인지 미리 세어 보는 기능입니다. 이 글은 토큰 카운팅이 어떻게 동작하고, 왜 다른 토크나이저로 어림잡으면 안 되는지, 그리고 이 값으로 요청 전에 비용을 어떻게 가늠하는지를 공식 문서를 기준으로 정리한 기록입니다. 가격과 세부 수치는 모델·시점에 따라 달라질 수 있으니 본문 끝의 공식 문서를 함께 확인하시길 권합니다.

핵심 개념 — 보내기 전에 미리 세어 본다

토큰 카운팅은 별도의 엔드포인트(count_tokens)를 통해, 실제 응답을 생성하지 않고 입력이 몇 토큰인지만 돌려줍니다. 기억해 둘 점은 두 가지입니다.

• 결과는 input_tokens — 이 값이 요청에 들어갈 입력 토큰 수입니다.
• 토큰 수는 모델마다 다르다 — 토큰을 나누는 방식이 모델별로 다르므로, 실제 추론에 쓸 모델 ID를 그대로 넣어 세어야 정확합니다.

사용법 — count_tokens

메시지를 그대로 client.messages.count_tokens에 넘기면, 응답 객체의 input_tokens에서 토큰 수를 읽을 수 있습니다.

from anthropic import Anthropic

client = Anthropic()

resp = client.messages.count_tokens(
    model="claude-opus-4-8",
    messages=[{"role": "user", "content": "안녕하세요, 이 문장은 몇 토큰인가요?"}],
)
print(resp.input_tokens)  # 입력 토큰 수

파일이나 긴 프롬프트도 마찬가지입니다. 내용을 content에 그대로 담아 세면 됩니다.

text = open("문서.md").read()
resp = client.messages.count_tokens(
    model="claude-opus-4-8",
    messages=[{"role": "user", "content": text}],
)
print(resp.input_tokens)

주의 — 다른 토크나이저로 어림잡지 않는다

가장 흔한 실수는 손쉬운 다른 토크나이저(예: tiktoken)로 토큰 수를 어림잡는 것입니다. 그런데 tiktoken은 다른 모델 계열을 위한 토크나이저라, Claude의 실제 토큰 수와 어긋납니다. 공식 문서 기준으로 일반 텍스트에서는 대략 15~20% 정도 적게 세고, 코드나 비영어(예: 한국어) 입력에서는 그 차이가 더 커집니다. 비용을 미리 가늠하려는 목적이라면, 어긋난 추정치는 오히려 판단을 흐립니다.

정확한 값이 필요하면 Claude 모델을 대상으로 하는 count_tokens를 사용하세요. 특히 한국어·코드가 많은 프롬프트일수록 다른 토크나이저의 추정치와 실제 값의 차이가 벌어질 수 있습니다.

요청 전에 비용을 가늠하기

입력 토큰 수를 알면, 요청을 보내기 전에 대략적인 입력 비용을 계산해 볼 수 있습니다. 공식 가격 문서의 100만 토큰당 단가를 곱하면 됩니다(가격은 모델·시점에 따라 달라질 수 있습니다).

tokens = resp.input_tokens
# 입력 단가는 공식 가격 문서 기준(변동 가능). 예: 100만 토큰당 $5 가정
est = tokens / 1_000_000 * 5.0
print(f"예상 입력 비용: ${est:.4f}")

여기서 얻는 값은 입력 비용의 대략적인 추정입니다. 실제 청구는 출력 토큰, 캐싱, 배치 여부 등에 따라 달라지므로, 이 숫자는 "요청을 보내기 전에 대략의 규모를 가늠하는 용도"로 이해하는 편이 안전합니다.

같은 프롬프트의 두 버전 중 어느 쪽이 더 짧은지 비교하고 싶다면, 각각 따로 세어 빼면 됩니다. 카운팅 엔드포인트는 상태를 기억하지 않으므로(stateless), 버전마다 한 번씩 세어 그 차이를 확인하면 됩니다.

터미널에서 빠르게 — CLI

스크립트를 짜기 전에 값만 빠르게 확인하고 싶다면 CLI로도 셀 수 있습니다.

ant messages count-tokens \
  --model claude-opus-4-8 \
  --message '{role: user, content: "@./문서.md"}' \
  --transform input_tokens -r

언제 쓰면 좋은가

• 대량 처리 전 예산 가늠 — 수백~수천 건을 돌리기 전에 입력 규모를 미리 계산해 보고 싶을 때.
• 한도 초과 예방 — 프롬프트가 너무 길어 컨텍스트 한도를 넘거나 응답 여유가 부족하지 않은지 미리 점검할 때.
• 프롬프트 다이어트 — 시스템 지침이나 예시를 줄였을 때 실제로 토큰이 얼마나 줄었는지 확인할 때.

자주 묻는 질문

Q. tiktoken으로 세면 안 되나요?

권장하지 않습니다. tiktoken은 다른 모델 계열의 토크나이저라 Claude의 실제 토큰 수와 어긋나며, 코드나 한국어에서는 차이가 더 큽니다. 정확한 값은 Claude 모델을 대상으로 하는 count_tokens로 확인하세요.

Q. 모델마다 토큰 수가 달라지나요?

네. 토큰을 나누는 방식이 모델별로 다를 수 있어, 같은 텍스트라도 모델에 따라 토큰 수가 달라질 수 있습니다. 그래서 셀 때도 실제 추론에 쓸 모델 ID를 그대로 넣는 것이 정확합니다.

Q. 카운팅 값으로 정확한 청구액을 알 수 있나요?

완전히 정확하지는 않습니다. count_tokens는 입력 토큰 수를 알려 주며, 실제 청구는 출력 토큰·캐싱·배치 여부 등에 따라 달라집니다. 요청 전에 대략의 규모를 가늠하는 용도로 쓰는 것이 안전합니다.

마무리

정리하면, 토큰 카운팅은 "요청을 보내기 전에 입력이 몇 토큰인지 미리 세어 본다"는 단순한 기능입니다. count_tokens로 input_tokens를 확인하고, 그 값에 단가를 곱해 대략적인 입력 비용을 가늠하는 것 — 그리고 다른 토크나이저로 어림잡지 않고 실제 쓸 모델로 세는 것, 이 두 가지만 기억하면 대량 작업에 앞서 규모와 비용을 미리 점검할 수 있었습니다.

이 글의 수치와 동작 설명은 Claude API 공식 문서를 기준으로 정리했습니다. 가격·한도 등 세부 사항은 모델과 시점에 따라 달라질 수 있으니, 최신 내용은 공식 문서에서 직접 확인하시길 권합니다.

• 토큰 카운팅 문서: platform.claude.com/docs/en/build-with-claude/token-counting
• 가격 문서: platform.claude.com/docs/en/pricing

※ 본 글은 공개된 공식 문서와 개인적인 사용 경험을 바탕으로 정리한 정보성 콘텐츠입니다. API의 기능·가격·수치는 모델과 시점에 따라 달라질 수 있으며, 특정 비용 절감 결과를 보장하지 않습니다.