메인 콘텐츠로 건너뛰기
Claude Messages Count Tokens API는 실제로 메시지를 생성하지 않고도 도구, 이미지 및 문서 등의 콘텐츠에 대한 Token 수를 포함하여 하나의 Message의 입력 Token 수를 계산할 수 있습니다. 이는 비용을 예상하거나 입력이 모델 컨텍스트 제한을 초과하는지 확인해야 할 때 매우 유용합니다. 이 문서는 주로 Claude Messages Count Tokens API의 사용 절차를 소개합니다.

신청 절차

Claude Messages Count Tokens API를 사용하려면 먼저 Ace Data Cloud 콘솔에서 API Token을 발급받아 예비용으로 보관하세요. 아직 로그인 또는 등록하지 않은 경우, 등록 및 로그인을 안내하는 로그인 페이지로 자동 이동하며, 완료 후 현재 페이지로 자동 반환됩니다. 하나의 API Token으로 플랫폼의 모든 서비스를 호출할 수 있으며, 서비스별로 별도 신청할 필요가 없습니다. 최초 신청 시 무료 크레딧이 제공되어 무료로 체험할 수 있으며, 크레딧이 부족한 경우 콘솔에서 공통 잔액을 충전할 수 있습니다.
📘 전체 문서: Claude Messages Count Tokens API →

기본 사용법

Claude Messages Count Tokens API의 요청 경로는 /v1/messages/count_tokens이며, Anthropic 공식 API와 일치합니다. 최소한 다음 두 개의 필수 파라미터를 제공해야 합니다.
  • model: 사용할 Claude 모델을 선택합니다. claude-opus-5-5는 최신 플래그십 claude-fable-5-1과 같이 Messages Token Count에 사용할 수 있으며, 기존 claude-fable-5도 계속 호환되어 유지됩니다. claude-sonnet-5-5는 네이티브 Messages 시리즈 인터페이스에 추가되었으며, 이미지 입력과 적응형 사고를 지원합니다. 입력, 출력 및 캐시 읽기에 대한 공식 참고 가격은 각각 백만 Token당 2, 10 및 0.20달러입니다.
  • messages: 입력 메시지 배열이며, 각 메시지에는 role(역할)과 content(내용)가 포함됩니다.
일반적인 선택 파라미터:
  • system: 시스템 프롬프트이며, Token 수에 포함됩니다.
  • tools: 도구 정의이며, Token 수에 포함됩니다.
  • thinking: 확장 사고 구성입니다.
  • tool_choice: 도구 선택 구성입니다.
  • cache_control: 최상위 또는 콘텐츠 블록 수준의 캐시 제어 구성입니다.
messages, system, 도구 호출 재생, URL 이미지 및 document/PDF 콘텐츠 블록은 Messages API와 동일한 안정적인 요청 구조를 사용합니다.

cURL 예시

Python 예시

반환 결과 예시:

Anthropic SDK 사용

Claude Messages Count Tokens API는 Anthropic SDK의 안정적인 요청 구조를 지원하며, anthropic 라이브러리를 통해 호출할 수 있습니다. 이 인터페이스는 선택한 모델에 해당하는 네이티브 Count Tokens 기능을 사용하여 입력을 계산하며, Messages 요청을 전송하기 전에 입력 규모를 확인하는 데 사용할 수 있습니다.

도구를 포함한 Token 계산

요청에 도구 정의가 포함된 경우, 이러한 도구도 Token 수에 포함됩니다.

시스템 프롬프트를 포함한 Token 계산

시스템 프롬프트도 Token 수에 포함됩니다.

유의 사항

  • 이 API는 입력 Token 수만 계산하며, 어떠한 모델 출력도 생성하지 않습니다.
  • Token 계산 결과는 입력 규모를 예상하고 컨텍스트 창을 확인하는 데 사용할 수 있으며, 최종 과금은 실제 Messages 응답의 usage를 기준으로 합니다.
  • 이미지, PDF, 도구 정의, 시스템 프롬프트 및 thinking 구성은 선택한 모델의 입력 규칙에 따라 결과에 포함됩니다.
  • 이 API는 완전히 무료이며, 어떠한 크레딧도 소모하지 않습니다.