Messages컨텍스트 관리

토큰 계산

Claude에 메시지를 보내기 전에 토큰 수를 계산하세요. 토큰 수를 사용하여 속도 제한과 비용을 관리하고, 모델 라우팅 결정을 내리며, 프롬프트를 목표 길이에 맞출 수 있습니다.

토큰 계산을 사용하면 Claude에 메시지를 보내기 전에 해당 메시지의 토큰 수를 확인할 수 있습니다. 이를 통해 프롬프트와 사용량에 대해 정보에 기반한 결정을 내릴 수 있습니다. 토큰 계산으로 다음을 수행할 수 있습니다:

속도 제한과 비용을 사전에 관리
스마트한 모델 라우팅 결정
프롬프트를 특정 길이에 맞게 최적화

이 기능은 Zero Data Retention (ZDR)의 적용 대상입니다. 조직에 ZDR 계약이 체결되어 있는 경우, 이 기능을 통해 전송된 데이터는 API 응답이 반환된 후 저장되지 않습니다.

메시지 토큰 계산 방법

토큰 계산 엔드포인트는 메시지 생성과 동일한 구조화된 입력 목록을 받으며, 시스템 프롬프트, 도구, 이미지, PDF를 지원합니다. 응답에는 총 입력 토큰 수가 포함됩니다.

토큰 수는 추정치로 간주해야 합니다. 경우에 따라 메시지를 생성할 때 실제로 사용되는 입력 토큰 수가 약간 다를 수 있습니다.

토큰 수에는 시스템 최적화를 위해 Anthropic이 자동으로 추가한 토큰이 포함될 수 있습니다. 시스템이 추가한 토큰에 대해서는 요금이 청구되지 않습니다. 청구는 사용자의 콘텐츠만 반영합니다.

지원되는 모델

모든 활성 모델이 토큰 계산을 지원합니다.

기본 메시지의 토큰 계산

client = anthropic.Anthropic()

response = client.messages.count_tokens(
    model="claude-opus-4-8",
    system="You are a scientist",
    messages=[{"role": "user", "content": "Hello, Claude"}],
)

print(response.json())

Output

{ "input_tokens": 14 }

도구가 포함된 메시지의 토큰 계산

서버 도구 토큰 수는 첫 번째 샘플링 호출에만 적용됩니다.

client = anthropic.Anthropic()

response = client.messages.count_tokens(
    model="claude-opus-4-8",
    tools=[
        {
            "name": "get_weather",
            "description": "Get the current weather in a given location",
            "input_schema": {
                "type": "object",
                "properties": {
                    "location": {
                        "type": "string",
                        "description": "The city and state, e.g. San Francisco, CA",
                    }
                },
                "required": ["location"],
            },
        }
    ],
    messages=[{"role": "user", "content": "What's the weather like in San Francisco?"}],
)

print(response.json())

Output

{ "input_tokens": 403 }

이미지가 포함된 메시지의 토큰 계산

import base64
import httpx

image_url = "https://upload.wikimedia.org/wikipedia/commons/a/a7/Camponotus_flavomarginatus_ant.jpg"
image_media_type = "image/jpeg"
image_data = base64.standard_b64encode(httpx.get(image_url).content).decode("utf-8")

client = anthropic.Anthropic()

response = client.messages.count_tokens(
    model="claude-opus-4-8",
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "image",
                    "source": {
                        "type": "base64",
                        "media_type": image_media_type,
                        "data": image_data,
                    },
                },
                {"type": "text", "text": "Describe this image"},
            ],
        }
    ],
)
print(response.json())

Output

{ "input_tokens": 1551 }

확장 사고가 포함된 메시지의 토큰 계산

자세한 내용은 확장 사고에서 컨텍스트 윈도우가 계산되는 방식을 참조하세요

이전 어시스턴트 턴의 thinking 블록은 무시되며 입력 토큰에 포함되지 않습니다
현재 어시스턴트 턴의 thinking은 입력 토큰에 포함됩니다

client = anthropic.Anthropic()

response = client.messages.count_tokens(
    model="claude-sonnet-4-6",
    thinking={"type": "enabled", "budget_tokens": 16000},
    messages=[
        {
            "role": "user",
            "content": "Are there an infinite number of prime numbers such that n mod 4 == 3?",
        },
        {
            "role": "assistant",
            "content": [
                {
                    "type": "thinking",
                    "thinking": "This is a nice number theory question. Let's think about it step by step...",
                    "signature": "EuYBCkQYAiJAgCs1le6/Pol5Z4/JMomVOouGrWdhYNsH3ukzUECbB6iWrSQtsQuRHJID6lWV...",
                },
                {
                    "type": "text",
                    "text": "Yes, there are infinitely many prime numbers p such that p mod 4 = 3...",
                },
            ],
        },
        {"role": "user", "content": "Can you write a formal proof?"},
    ],
)

print(response.json())

Output

{ "input_tokens": 88 }

PDF가 포함된 메시지의 토큰 계산

토큰 계산은 Messages API와 동일한 제한 사항으로 PDF를 지원합니다.

import base64
import anthropic

client = anthropic.Anthropic()

with open("document.pdf", "rb") as pdf_file:
    pdf_base64 = base64.standard_b64encode(pdf_file.read()).decode("utf-8")

response = client.messages.count_tokens(
    model="claude-opus-4-8",
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "document",
                    "source": {
                        "type": "base64",
                        "media_type": "application/pdf",
                        "data": pdf_base64,
                    },
                },
                {"type": "text", "text": "Please summarize this document."},
            ],
        }
    ],
)

print(response.json())

Output

{ "input_tokens": 2188 }

Claude Fable 5 및 Claude Mythos 5의 토큰 수

Claude Fable 5와 Claude Mythos 5는 Claude Opus 4.7에서 도입된 토크나이저를 사용하며, 동일한 텍스트에 대해 Claude Opus 4.7 이전 모델보다 약 30% 더 많은 토큰을 생성합니다. 토큰 계산 엔드포인트는 전달한 model의 토크나이저 기준으로 토큰 수를 반환하므로, 워크로드에 대한 차이를 측정하려면 동일한 요청을 두 번 계산하세요. 한 번은 현재 모델로, 한 번은 model: "claude-fable-5"(또는 "claude-mythos-5")로 계산한 다음 두 input_tokens 값을 비교하세요.

청구 및 마이그레이션: Claude Fable 5와 Claude Mythos 5의 사용량 및 청구는 이 토크나이저의 토큰 수를 반영합니다. Claude Opus 4.7 이전 모델에서 마이그레이션하는 경우, 동일한 콘텐츠가 약 30% 더 많은 토큰을 소비합니다. 워크로드를 Claude Fable 5 및 Claude Mythos 5로 마이그레이션할 때는 Claude Opus 4.7 이전 모델에서 측정한 토큰 수를 비용이나 컨텍스트 윈도우 적합성 추정에 재사용하지 마세요. model: "claude-fable-5"(또는 "claude-mythos-5")로 프롬프트의 토큰 수를 계산하세요.

가격 및 속도 제한

토큰 계산은 무료로 사용할 수 있지만 사용량 티어에 따라 분당 요청 수 속도 제한이 적용됩니다. 더 높은 한도가 필요한 경우 Claude Console을 통해 영업팀에 문의하세요.

사용량 티어	분당 요청 수(RPM)
1	100
2	2,000
3	4,000
4	8,000

토큰 계산과 메시지 생성은 별도의 독립적인 속도 제한을 가집니다. 한쪽의 사용량은 다른 쪽의 한도에 영향을 주지 않습니다.

FAQ

다음 단계

메시지 토큰 계산

토큰 계산 엔드포인트에 대한 전체 API 레퍼런스를 읽어보세요.

컨텍스트 윈도우

토큰 수를 사용하여 프롬프트를 모델의 컨텍스트 윈도우 내로 유지하세요.

속도 제한

요청을 보내기 전에 토큰 수를 확인하여 사용량 티어 내에서 유지하세요.

프롬프트 캐싱

프롬프트 접두사를 캐싱하여 반복되는 프롬프트의 비용과 지연 시간을 줄이세요.

Was this page helpful?

Messages컨텍스트 관리

토큰 계산

속도 제한과 비용을 사전에 관리
스마트한 모델 라우팅 결정
프롬프트를 특정 길이에 맞게 최적화

메시지 토큰 계산 방법

토큰 수는 추정치로 간주해야 합니다. 경우에 따라 메시지를 생성할 때 실제로 사용되는 입력 토큰 수가 약간 다를 수 있습니다.

지원되는 모델

모든 활성 모델이 토큰 계산을 지원합니다.

기본 메시지의 토큰 계산

client = anthropic.Anthropic()

response = client.messages.count_tokens(
    model="claude-opus-4-8",
    system="You are a scientist",
    messages=[{"role": "user", "content": "Hello, Claude"}],
)

print(response.json())

Output

{ "input_tokens": 14 }

도구가 포함된 메시지의 토큰 계산

서버 도구 토큰 수는 첫 번째 샘플링 호출에만 적용됩니다.

client = anthropic.Anthropic()

response = client.messages.count_tokens(
    model="claude-opus-4-8",
    tools=[
        {
            "name": "get_weather",
            "description": "Get the current weather in a given location",
            "input_schema": {
                "type": "object",
                "properties": {
                    "location": {
                        "type": "string",
                        "description": "The city and state, e.g. San Francisco, CA",
                    }
                },
                "required": ["location"],
            },
        }
    ],
    messages=[{"role": "user", "content": "What's the weather like in San Francisco?"}],
)

print(response.json())

Output

{ "input_tokens": 403 }

이미지가 포함된 메시지의 토큰 계산

import base64
import httpx

image_url = "https://upload.wikimedia.org/wikipedia/commons/a/a7/Camponotus_flavomarginatus_ant.jpg"
image_media_type = "image/jpeg"
image_data = base64.standard_b64encode(httpx.get(image_url).content).decode("utf-8")

client = anthropic.Anthropic()

response = client.messages.count_tokens(
    model="claude-opus-4-8",
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "image",
                    "source": {
                        "type": "base64",
                        "media_type": image_media_type,
                        "data": image_data,
                    },
                },
                {"type": "text", "text": "Describe this image"},
            ],
        }
    ],
)
print(response.json())

Output

{ "input_tokens": 1551 }

확장 사고가 포함된 메시지의 토큰 계산

자세한 내용은 확장 사고에서 컨텍스트 윈도우가 계산되는 방식을 참조하세요

이전 어시스턴트 턴의 thinking 블록은 무시되며 입력 토큰에 포함되지 않습니다
현재 어시스턴트 턴의 thinking은 입력 토큰에 포함됩니다

client = anthropic.Anthropic()

response = client.messages.count_tokens(
    model="claude-sonnet-4-6",
    thinking={"type": "enabled", "budget_tokens": 16000},
    messages=[
        {
            "role": "user",
            "content": "Are there an infinite number of prime numbers such that n mod 4 == 3?",
        },
        {
            "role": "assistant",
            "content": [
                {
                    "type": "thinking",
                    "thinking": "This is a nice number theory question. Let's think about it step by step...",
                    "signature": "EuYBCkQYAiJAgCs1le6/Pol5Z4/JMomVOouGrWdhYNsH3ukzUECbB6iWrSQtsQuRHJID6lWV...",
                },
                {
                    "type": "text",
                    "text": "Yes, there are infinitely many prime numbers p such that p mod 4 = 3...",
                },
            ],
        },
        {"role": "user", "content": "Can you write a formal proof?"},
    ],
)

print(response.json())

Output

{ "input_tokens": 88 }

PDF가 포함된 메시지의 토큰 계산

토큰 계산은 Messages API와 동일한 제한 사항으로 PDF를 지원합니다.

import base64
import anthropic

client = anthropic.Anthropic()

with open("document.pdf", "rb") as pdf_file:
    pdf_base64 = base64.standard_b64encode(pdf_file.read()).decode("utf-8")

response = client.messages.count_tokens(
    model="claude-opus-4-8",
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "document",
                    "source": {
                        "type": "base64",
                        "media_type": "application/pdf",
                        "data": pdf_base64,
                    },
                },
                {"type": "text", "text": "Please summarize this document."},
            ],
        }
    ],
)

print(response.json())

Output

{ "input_tokens": 2188 }

Claude Fable 5 및 Claude Mythos 5의 토큰 수

가격 및 속도 제한

사용량 티어	분당 요청 수(RPM)
1	100
2	2,000
3	4,000
4	8,000

토큰 계산과 메시지 생성은 별도의 독립적인 속도 제한을 가집니다. 한쪽의 사용량은 다른 쪽의 한도에 영향을 주지 않습니다.

FAQ

다음 단계

메시지 토큰 계산

토큰 계산 엔드포인트에 대한 전체 API 레퍼런스를 읽어보세요.

컨텍스트 윈도우

토큰 수를 사용하여 프롬프트를 모델의 컨텍스트 윈도우 내로 유지하세요.

속도 제한

요청을 보내기 전에 토큰 수를 확인하여 사용량 티어 내에서 유지하세요.

프롬프트 캐싱

프롬프트 접두사를 캐싱하여 반복되는 프롬프트의 비용과 지연 시간을 줄이세요.

Was this page helpful?

메시지 토큰 계산 방법

지원되는 모델

기본 메시지의 토큰 계산

도구가 포함된 메시지의 토큰 계산

이미지가 포함된 메시지의 토큰 계산

확장 사고가 포함된 메시지의 토큰 계산

PDF가 포함된 메시지의 토큰 계산

Claude Fable 5 및 Claude Mythos 5의 토큰 수

가격 및 속도 제한

FAQ

토큰 계산은 프롬프트 캐싱을 사용하나요?

다음 단계

메시지 토큰 계산 방법

지원되는 모델

기본 메시지의 토큰 계산

도구가 포함된 메시지의 토큰 계산

이미지가 포함된 메시지의 토큰 계산

확장 사고가 포함된 메시지의 토큰 계산

PDF가 포함된 메시지의 토큰 계산

Claude Fable 5 및 Claude Mythos 5의 토큰 수

가격 및 속도 제한

FAQ

토큰 계산은 프롬프트 캐싱을 사용하나요?

다음 단계

메시지 토큰 계산 방법

지원되는 모델

기본 메시지의 토큰 계산

도구가 포함된 메시지의 토큰 계산

이미지가 포함된 메시지의 토큰 계산

확장 사고가 포함된 메시지의 토큰 계산

PDF가 포함된 메시지의 토큰 계산

Claude Fable 5 및 Claude Mythos 5의 토큰 수

가격 및 속도 제한

FAQ

다음 단계

메시지 토큰 계산 방법

지원되는 모델

기본 메시지의 토큰 계산

도구가 포함된 메시지의 토큰 계산

이미지가 포함된 메시지의 토큰 계산

확장 사고가 포함된 메시지의 토큰 계산

PDF가 포함된 메시지의 토큰 계산

Claude Fable 5 및 Claude Mythos 5의 토큰 수

가격 및 속도 제한

FAQ

다음 단계