Skip to main content
Claude Messages Count Tokens API는 실제로 메시지를 생성하지 않고도 메시지의 입력 토큰 수를 계산할 수 있습니다. 여기에는 도구, 이미지 및 문서 등의 내용의 토큰 수 계산이 포함됩니다. 이는 비용을 예측하거나 입력이 모델의 컨텍스트 제한을 초과하는지 확인해야 할 때 매우 유용합니다. 이 문서는 Claude Messages Count Tokens API의 사용 프로세스를 주로 설명합니다.

신청 프로세스

Claude Messages Count Tokens API를 사용하려면 먼저 Ace Data Cloud 콘솔에서 API 토큰을 받아야 합니다. 이 토큰은 백업용으로 보관하십시오. 로그인 또는 등록이 되어 있지 않은 경우 자동으로 로그인 페이지로 리디렉션되어 등록 및 로그인을 초대합니다. 완료 후 현재 페이지로 자동으로 돌아옵니다. 하나의 API 토큰으로 플랫폼의 모든 서비스를 호출할 수 있으며, 각 서비스에 대해 별도로 신청할 필요가 없습니다. 처음 신청 시 무료 할당량이 제공되어 무료로 체험할 수 있습니다. 할당량이 부족할 경우 콘솔에서 일반 잔액을 충전할 수 있습니다.
📘 전체 문서: Claude Messages Count Tokens API →

기본 사용

Claude Messages Count Tokens API의 요청 경로는 /v1/messages/count_tokens이며, Anthropic 공식 API와 일치합니다. 최소한 두 개의 필수 매개변수를 제공해야 합니다:
  • model: 사용할 Claude 모델을 선택합니다. 예를 들어 최신 플래그십 모델인 claude-fable-5-1을 선택할 수 있습니다. 이전의 claude-fable-5도 여전히 호환됩니다.
  • messages: 입력 메시지 배열로, 각 메시지는 role(역할)과 content(내용)를 포함합니다.
자주 사용되는 선택적 매개변수:
  • system: 시스템 프롬프트로, 토큰 수에 포함됩니다.
  • tools: 도구 정의로, 토큰 수에 포함됩니다.
  • thinking: 확장된 사고 구성입니다.
  • tool_choice: 도구 선택 구성입니다.
  • cache_control: 최상위 또는 콘텐츠 블록 수준의 캐시 제어 구성입니다.
messages, system, 도구 호출 재생, URL 이미지 및 document/PDF 콘텐츠 블록은 Messages API와 동일한 안정적인 요청 구조를 사용합니다.

cURL 예시

Python 예시

반환 결과 예시:

Anthropic SDK 사용

Claude Messages Count Tokens API는 Anthropic SDK의 안정적인 요청 구조를 수용하며, anthropic 라이브러리를 통해 호출할 수 있습니다. 현재 반환 값은 Ace Data Cloud의 로컬 추정기가 계산한 것이며, Anthropic 공식 토크나이저의 정확한 결과가 아닙니다. 다중 모드, 도구 및 다양한 Claude 모델의 실제 토큰 수는 차이가 있을 수 있습니다.

도구 포함 토큰 수 계산

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

시스템 프롬프트 포함 토큰 수 계산

시스템 프롬프트도 토큰 수에 포함됩니다:

주의 사항

  • 이 API는 입력 토큰 수만 계산하며, 모델 출력을 생성하지 않습니다.
  • 토큰 수 계산 결과는 입력 규모를 대략적으로 예측하는 데 사용될 수 있으며, 정확한 청구, 컨텍스트 창 접근 제한 또는 모델 토크나이저 비교의 기준으로 사용되어서는 안 됩니다.
  • 현재 추정기는 이미지 및 PDF의 시각/문서 토큰을 정확하게 계산하지 않으며, 다양한 Claude 모델의 공식 토크나이저 차이를 반영하지 않습니다.
  • 이 API는 완전히 무료이며, 어떤 할당량도 소모하지 않습니다.