> ## Documentation Index
> Fetch the complete documentation index at: https://docs.xhuoapi.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Claude Messages Count Tokens API 申請及使用

> Claude AI 集成指南 - XHuoAPI

Claude Messages Count Tokens API 可以在不實際創建消息的情況下，計算一條 Message 的輸入 Token 數量，包括工具、圖片和文檔等內容的 Token 計數。這在需要預估成本或檢查輸入是否超出模型上下文限制時非常有用。

本文檔主要介紹 Claude Messages Count Tokens API 的使用流程。

## 申請流程

要使用 Claude Messages Count Tokens API，首先可以到 [Claude Messages Count Tokens API](https://api.xhuoapi.ai/documents/claude-messages-count-tokens) 頁面點擊「Acquire」按鈕，獲取請求所需要的憑證。

如果你尚未登錄或註冊，會自動跳轉到登錄頁面邀請您來註冊和登錄，登錄註冊之後會自動返回當前頁面。

該 API 完全免費使用，無需消耗額度。

## 基本使用

Claude Messages Count Tokens API 的請求路徑為 `/v1/messages/count_tokens`，與 Anthropic 官方 API 保持一致。我們至少需要提供兩個必填參數：

* `model`：選擇使用的 Claude 模型，如 `claude-sonnet-4-5-20250929`、`claude-opus-4-20250514` 等。
* `messages`：輸入的消息數組，每條消息包含 `role`（角色）和 `content`（內容）。

常用可選參數：

* `system`：系統提示詞，會計入 Token 數量。
* `tools`：工具定義，會計入 Token 數量。
* `thinking`：擴展思考配置。

### cURL 示例

```bash theme={null}
curl -X POST 'https://api.xhuoapi.ai/v1/v1/messages/count_tokens' \
  -H 'accept: application/json' \
  -H 'authorization: Bearer {token}' \
  -H 'content-type: application/json' \
  -d '{
    "model": "claude-sonnet-4-5-20250929",
    "messages": [
      {
        "role": "user",
        "content": "Hello, Claude"
      }
    ]
  }'
```

### Python 示例

```python theme={null}
import httpx

url = "https://api.xhuoapi.ai/v1/v1/messages/count_tokens"
headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json",
}
payload = {
    "model": "claude-sonnet-4-5-20250929",
    "messages": [
        {
            "role": "user",
            "content": "Hello, Claude"
        }
    ],
}
response = httpx.post(url, headers=headers, json=payload)
print(response.json())
```

返回結果示例：

```json theme={null}
{
  "input_tokens": 11
}
```

### 使用 Anthropic SDK

Claude Messages Count Tokens API 完全兼容 Anthropic 官方 SDK，可以直接使用 `anthropic` 庫來調用。

```python theme={null}
from anthropic import Anthropic

client = Anthropic(
    api_key="{token}",
    base_url="https://api.xhuoapi.ai/v1",
)

result = client.messages.count_tokens(
    model="claude-sonnet-4-5-20250929",
    messages=[
        {
            "role": "user",
            "content": "Hello, Claude"
        }
    ],
)
print(result.input_tokens)
```

## 包含工具的 Token 計數

如果你的請求中包含工具定義，這些工具也會計入 Token 數量：

```python theme={null}
result = client.messages.count_tokens(
    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"]
            }
        }
    ],
)
print(result.input_tokens)
```

## 包含系統提示詞的 Token 計數

系統提示詞也會計入 Token 數量：

```python theme={null}
result = client.messages.count_tokens(
    model="claude-sonnet-4-5-20250929",
    system="You are a helpful assistant that speaks Chinese.",
    messages=[
        {
            "role": "user",
            "content": "Hello"
        }
    ],
)
print(result.input_tokens)
```

## 注意事項

* 該 API 僅計算輸入 Token 數量，不會產生任何模型輸出。
* Token 計數結果可用於預估調用 Claude Messages API 的成本。
* 不同模型的 Token 化方式可能有所不同，請使用與實際調用相同的 model 參數。
* 該 API 完全免費，不消耗任何額度。