Skip to main content
POST
/
v1
/
messages
/
count_tokens
curl --request POST \
  --url https://api.mixroute.ai/v1/messages/count_tokens \
  --header 'Authorization: Bearer sk-xxxxxxxxxx' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "claude-sonnet-4-5-20250929",
    "messages": [
      {"role": "user", "content": "Hello, how are you?"}
    ]
  }'

{
  "input_tokens": 14
}

​
簡介

計算 Claude 訊息的 token 數量，用於在發送請求前預估成本。此端點 不消耗配額，僅進行本地計算。

​
認證

Bearer Token，如 Bearer sk-xxxxxxxxxx

​
請求參數

​
model
string
required
Claude 模型識別碼，支援的模型包括：
  • claude-sonnet-4-20250514
  • claude-sonnet-4-5-20250929
  • claude-haiku-4-5-20251001
  • claude-opus-4-5-20251101（推薦替代 claude-3-opus）
  • 其他 Claude 系列模型
​
messages
array
required
對話訊息列表，每個元素包含 role（user/assistant）和 content。content 可以是字串或媒體內容陣列。支援的內容類型：
  • 純文字訊息
  • 多模態訊息（包含圖片）
  • 工具呼叫結果
​
system
string
系統提示詞（選填），可以是字串或媒體內容陣列。用於設定模型的行為和角色。
​
tools
array
工具定義列表（選填），用於計算工具呼叫相關的 token 數量。

​
回應參數

​
input_tokens
integer
輸入訊息的總 token 數量，包括：
  • 所有 messages 的 token 數
  • system prompt 的 token 數
  • tools 定義的 token 數（如果有）

​
基礎範例

curl -X POST "https://api.mixroute.ai/v1/messages/count_tokens" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-xxxxxxxxxx" \
  -d '{
    "model": "claude-sonnet-4-5-20250929",
    "messages": [
      {
        "role": "user",
        "content": "Hello, how are you?"
      }
    ]
  }'

​
Python 範例

from anthropic import Anthropic

client = Anthropic(
    api_key="sk-xxxxxxxxxx",
    base_url="https://api.mixroute.ai"
)

# 計算 token 數量
response = client.messages.count_tokens(
    model="claude-sonnet-4-5-20250929",
    system="You are a helpful assistant.",
    messages=[
        {"role": "user", "content": "Hello, Claude!"}
    ]
)

print(f"Input tokens: {response.input_tokens}")

​
回應範例

{
  "input_tokens": 14
}

​
進階用例

curl -X POST "https://api.mixroute.ai/v1/messages/count_tokens" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-xxxxxxxxxx" \
  -d '{
    "model": "claude-sonnet-4-5-20250929",
    "messages": [
      {
        "role": "user",
        "content": "What is the weather in San Francisco?"
      }
    ],
    "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"]
        }
      }
    ]
  }'

​
使用情境

​
1. 成本預估

在發送大量請求前，先計算 token 數量以預估成本： 
# 批次計算成本
messages_batch = [...]  # 批次訊息
total_tokens = 0

for messages in messages_batch:
    response = client.messages.count_tokens(
        model="claude-sonnet-4-5-20250929",
        messages=messages
    )
    total_tokens += response.input_tokens

# 根據定價計算總成本
cost = total_tokens * price_per_token
print(f"預估成本: ${cost:.4f}")

​
2. 上下文視窗管理

檢查訊息是否超過模型的上下文視窗限制： 
MAX_CONTEXT_WINDOW = 200000  # Claude Sonnet 4.5 的上下文視窗

response = client.messages.count_tokens(
    model="claude-sonnet-4-5-20250929",
    messages=long_conversation
)

if response.input_tokens > MAX_CONTEXT_WINDOW:
    print(f"警告：訊息 token 數 ({response.input_tokens}) 超過上下文視窗限制")
    # 執行訊息截斷或摘要

​
3. 最佳化提示詞

比較不同提示詞的 token 消耗： 
prompts = [
    "簡潔版提示詞...",
    "詳細版提示詞...",
    "超詳細版提示詞..."
]

for prompt in prompts:
    response = client.messages.count_tokens(
        model="claude-sonnet-4-5-20250929",
        system=prompt,
        messages=[{"role": "user", "content": "測試"}]
    )
    print(f"{len(prompt)} 字元 -> {response.input_tokens} tokens")

​
注意事項

  • 此端點不會發起實際的 AI 請求，不消耗配額
  • 不包括 max_tokens 等輸出相關參數，僅計算輸入 token 數
  • 圖片 token 使用固定估算值（約 1000 tokens），實際可能因解析度不同而變化

​
錯誤處理

​
缺少必需參數

{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "Key: 'ClaudeCountTokensRequest.Model' Error:Field validation for 'Model' failed on the 'required' tag"
  }
}

​
無效的 API Key

{
  "error": {
    "message": "無效的 token",
    "type": "invalid_request_error"
  }
}

​
相關資源

curl --request POST \
  --url https://api.mixroute.ai/v1/messages/count_tokens \
  --header 'Authorization: Bearer sk-xxxxxxxxxx' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "claude-sonnet-4-5-20250929",
    "messages": [
      {"role": "user", "content": "Hello, how are you?"}
    ]
  }'

{
  "input_tokens": 14
}