Claude API 토큰 미리 세기: 요청 전에 비용과 길이를 확인하는 법

API 요금 계산법에서 실제 요청의 usage로 토큰을 측정하는 방법을 다뤘습니다. 그런데 요청을 보내기 전에 토큰 수를 알고 싶을 때가 있습니다. 문서 1만 건을 처리하기 전 예산을 잡을 때, 긴 문서가 컨텍스트에 들어가는지 확인할 때입니다. 이럴 때 토큰 카운팅을 씁니다.

기본 사용법

메시지를 실제로 보내는 대신 같은 형식으로 카운팅 요청을 보내면 입력 토큰 수를 알려 줍니다.

import anthropic

client = anthropic.Anthropic()

count = client.messages.count_tokens(
    model="claude-sonnet-5",
    system="너는 사내 규정 안내 도우미다.",
    messages=[{"role": "user", "content": open("manual.txt", encoding="utf-8").read()}],
)
print(count.input_tokens)

시스템 프롬프트, 메시지, 도구 정의, 이미지·PDF까지 실제 요청과 같은 구성으로 넣으면 그 요청의 입력 토큰 수가 나옵니다. 모델도 실제로 쓸 모델로 지정하세요. 모델 세대에 따라 같은 글도 토큰 수가 달라질 수 있습니다.

언제 쓰면 좋을까

1. 비용 미리 보기

대량 작업 전에 샘플 몇 건의 입력 토큰을 세고 건수를 곱하면 입력 비용을 예측할 수 있습니다. 출력은 미리 알 수 없으니 샘플 몇 건을 실제로 돌려 평균 출력 토큰을 측정합니다.

2. 컨텍스트 초과 방지

사용자가 올린 문서가 모델의 컨텍스트 한도를 넘을지 미리 확인하고, 넘으면 나눠 처리하거나 안내 메시지를 보여 줄 수 있습니다.

3. 문서를 통째로 넣을지 판단

RAG 기본 구조에서 말했듯, 문서가 적당한 크기라면 통째로 넣고 캐싱하는 편이 간단합니다. 토큰 수를 세 보면 어느 쪽이 맞는지 판단할 근거가 생깁니다.

4. 모델 전환 점검

다른 모델로 옮길 때 같은 프롬프트의 토큰 수가 얼마나 달라지는지 확인해 비용 변화를 미리 봅니다.

비용 예측 순서

1. 실제 데이터에서 대표 샘플 10~20건을 고릅니다.
2. 각 샘플의 입력 토큰을 셉니다.
3. 샘플을 실제로 돌려 평균 출력 토큰을 측정합니다.
4. 건수와 모델 단가를 곱합니다.
5. 프롬프트 캐싱이나 배치 API를 쓸 계획이면 할인을 반영합니다.

주의할 점

• 추정값과 실제 값의 차이: 카운팅 값은 실제 요청과 약간 다를 수 있습니다. 예산에는 여유를 둡니다.
• 요청 한도: 카운팅 요청에도 한도가 있으니, 수만 건을 하나씩 세기보다 샘플로 추정하세요.
• 출력이 비용의 큰 부분일 수 있음: 출력 단가가 입력보다 높으므로, 긴 답변을 받는 작업은 출력 쪽 측정이 더 중요합니다.

써 보며 느낀 점

토큰 카운팅을 쓰기 전에는 "대충 글자 수의 몇 배"로 예산을 잡았는데, 한국어·코드·표가 섞인 문서는 예상과 꽤 달랐습니다. 이제 대량 작업 전에는 샘플 20건을 세고 돌려 보는 걸 기본 절차로 둡니다. 10분 투자로 예산이 틀어지는 일을 막을 수 있습니다.

오늘의 체크포인트

1. count_tokens에 실제 요청과 같은 구성·모델을 넣으면 입력 토큰을 미리 알 수 있습니다.
2. 비용 예측, 컨텍스트 초과 방지, 문서 처리 방식 판단, 모델 전환 점검에 활용하세요.
3. 출력 토큰은 샘플로 측정하고, 예산에는 여유를 둡니다.

공식 문서와 함께 읽을 글

• Token counting (Anthropic 공식 문서)
• Claude API 요금 (공식)