Claude Platform Docs
Messages上下文管理

Token 計數

在將訊息傳送給 Claude 之前計算其中的 token 數量。使用 token 計數來管理速率限制和成本、做出模型路由決策，並將提示調整至目標長度。

「Token counting」（token 計數）可讓您在將訊息傳送給 Claude 之前，確定訊息中的 token 數量。這有助於您對提示和使用量做出明智的決策。透過 token 計數，您可以：

  • 主動管理「rate limit」（速率限制）和成本
  • 做出明智的「model routing」（模型路由）決策
  • 將提示最佳化至特定長度

如何計算訊息 token

token 計數端點接受與建立訊息相同的結構化輸入清單，包括支援「system prompt」（系統提示）、工具、圖片和 PDF。回應包含輸入 token 的總數。

對於 Messages API 所接受的少數幾種輸入，此端點會傳回 invalid_request_error：伺服器工具，例如網頁搜尋、網頁擷取、程式碼執行和工具搜尋（除了顧問工具之外的所有伺服器工具）、MCP 連接器，以及具有 url 或 file 來源的 image 或 document 區塊。請以 base64 格式傳送圖片和 PDF 以進行計數。對於使用伺服器工具或 MCP 伺服器的請求，Messages API 回應會在其 usage 物件中回報所使用的 token。

支援的模型

所有現行模型都支援 token 計數。

計算基本訊息中的 token

client = anthropic.Anthropic()

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

print(response.json())
Output
{ "input_tokens": 14 }

計算包含工具的訊息中的 token

client = anthropic.Anthropic()

response = client.messages.count_tokens(
    model="claude-opus-5-5",
    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 }

計算包含圖片的訊息中的 token

import base64
import httpx2

image_url = "https://platform.claude.com/docs/images/vision-example.jpg"
image_media_type = "image/jpeg"
image_data = base64.standard_b64encode(httpx2.get(image_url).content).decode("utf-8")

client = anthropic.Anthropic()

response = client.messages.count_tokens(
    model="claude-opus-5-5",
    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": 1028 }

設定了 "oversized_image": "error" 的內嵌圖片區塊，在計數時會被拒絕，方式與 Messages API 拒絕它的方式完全相同。

計算包含思考的訊息中的 token

client = anthropic.Anthropic()

response = client.messages.count_tokens(
    model="claude-opus-5-5",
    thinking={"type": "adaptive"},
    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 的訊息中的 token

import base64
import anthropic

client = anthropic.Anthropic()

with open("/path/to/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-5-5",
    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 和 Claude Mythos 模型上的 token 計數

Claude Fable 5.1、Claude Mythos 5.1、Claude Fable 5 和 Claude Mythos 5 共用隨 Claude Opus 4.7 推出的 tokenizer。同一個提示在這四個模型上的計數相同，且比 Claude Opus 4.7 之前的模型高出約 30%（確切的增幅取決於內容）。Token 計數端點會依據您傳入的 model 所使用的 tokenizer 進行計數。若要衡量您工作負載的差異，請將同一個請求計數兩次，一次使用您目前的模型，另一次使用您計劃遷移到的模型，然後比較兩個 input_tokens 值。

定價與速率限制

Token 計數可免費使用，但會受到基於您使用層級的每分鐘請求數速率限制。如果您需要更高的限制，請在速率限制頁面上使用 Request rate limit increase。

使用層級每分鐘請求數（RPM）
Start5,000
Build10,000
Scale20,000

常見問題

後續步驟

計算訊息 token

閱讀 token 計數端點的完整 API 參考文件。

上下文視窗

使用 token 計數讓提示保持在模型的上下文視窗範圍內。

速率限制

在傳送請求之前檢查 token 計數，以維持在您的使用層級範圍內。

提示快取

透過快取提示前綴，降低重複提示的成本和延遲。

Compatibility

Supported platforms
  • Claude API
  • Claude Platform on AWS
  • Amazon Bedrock
  • Google Cloud
  • Microsoft Foundry

Was this page helpful?