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

# 計算 Token 數量（Claude）

> 計算 Claude 訊息的 token 數量，用於在發送請求前預估成本

## 簡介

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

## 認證

Bearer Token，如 `Bearer sk-xxxxxxxxxx`

## 請求參數

**model** `string` *required*

Claude 模型識別碼，支援的模型包括：

* `claude-opus-4-8`
* `claude-sonnet-5`
* `claude-haiku-4-5`
* 其他 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 數（如果有）

## 基礎範例

**簡單文字訊息**

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

**帶 system prompt**

```bash theme={null}
curl -X POST "https://api.mixroute.ai/v1/messages/count_tokens" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-xxxxxxxxxx" \
  -d '{
    "model": "claude-opus-4-8",
    "system": "You are a helpful AI assistant.",
    "messages": [
      {
        "role": "user",
        "content": "What is artificial intelligence?"
      }
    ]
  }'
```

**多輪對話**

```bash theme={null}
curl -X POST "https://api.mixroute.ai/v1/messages/count_tokens" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-xxxxxxxxxx" \
  -d '{
    "model": "claude-opus-4-8",
    "messages": [
      {
        "role": "user",
        "content": "你好"
      },
      {
        "role": "assistant",
        "content": "你好！有什麼我可以幫助你的嗎？"
      },
      {
        "role": "user",
        "content": "給我講講人工智慧的歷史"
      }
    ]
  }'
```

## Python 範例

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

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

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

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

## 回應範例

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

## 進階用例

**帶工具定義的計算**

```bash theme={null}
curl -X POST "https://api.mixroute.ai/v1/messages/count_tokens" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-xxxxxxxxxx" \
  -d '{
    "model": "claude-opus-4-8",
    "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"]
        }
      }
    ]
  }'
```

**多模態內容計算**

```bash theme={null}
curl -X POST "https://api.mixroute.ai/v1/messages/count_tokens" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-xxxxxxxxxx" \
  -d '{
    "model": "claude-opus-4-8",
    "messages": [
      {
        "role": "user",
        "content": [
          {
            "type": "text",
            "text": "What is in this image?"
          },
          {
            "type": "image",
            "source": {
              "type": "url",
              "url": "https://example.com/image.jpg"
            }
          }
        ]
      }
    ]
  }'
```

## 使用情境

### 1. 成本預估

在發送大量請求前，先計算 token 數量以預估成本：

```python theme={null}
# 批次計算成本
messages_batch = [...]  # 批次訊息
total_tokens = 0

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

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

### 2. 上下文視窗管理

檢查訊息是否超過模型的上下文視窗限制：

```python theme={null}
MAX_CONTEXT_WINDOW = 1000000  # Claude Sonnet 5 的上下文視窗

response = client.messages.count_tokens(
    model="claude-opus-4-8",
    messages=long_conversation
)

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

### 3. 最佳化提示詞

比較不同提示詞的 token 消耗：

```python theme={null}
prompts = [
    "簡潔版提示詞...",
    "詳細版提示詞...",
    "超詳細版提示詞..."
]

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

## 注意事項

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

## 錯誤處理

### 缺少必需參數

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

### 無效的 API Key

```json theme={null}
{
  "error": {
    "message": "無效的 token",
    "type": "invalid_request_error"
  }
}
```

## 相關資源

* 定價說明 - 了解 token 計費標準
* [模型列表](https://console.mixroute.ai/models) - 查看支援的 Claude 模型
* [建立訊息請求（Claude）](/docs/zh-Hant/api-reference/endpoint/messages) - 發送實際的 Claude 請求

```bash cURL theme={null}
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-opus-4-8",
    "messages": [
      {"role": "user", "content": "Hello, how are you?"}
    ]
  }'
```

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

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

response = client.messages.count_tokens(
    model="claude-opus-4-8",
    messages=[
        {"role": "user", "content": "Hello, how are you?"}
    ]
)
print(f"Input tokens: {response.input_tokens}")
```

```javascript JavaScript theme={null}
const response = await fetch('https://api.mixroute.ai/v1/messages/count_tokens', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer sk-xxxxxxxxxx',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    model: 'claude-opus-4-8',
    messages: [
      { role: 'user', content: 'Hello, how are you?' }
    ]
  })
});
const data = await response.json();
console.log(data);
```

```php PHP theme={null}
<?php
$client = new GuzzleHttp\Client();
$response = $client->post('https://api.mixroute.ai/v1/messages/count_tokens', [
    'headers' => [
        'Authorization' => 'Bearer sk-xxxxxxxxxx',
        'Content-Type' => 'application/json',
    ],
    'json' => [
        'model' => 'claude-opus-4-8',
        'messages' => [
            ['role' => 'user', 'content' => 'Hello, how are you?']
        ]
    ]
]);
echo $response->getBody();
```

```go Go theme={null}
package main

import (
    "bytes"
    "encoding/json"
    "net/http"
)

func main() {
    payload := map[string]interface{}{
        "model": "claude-opus-4-8",
        "messages": []map[string]string{
            {"role": "user", "content": "Hello, how are you?"},
        },
    }
    body, _ := json.Marshal(payload)
    req, _ := http.NewRequest("POST", "https://api.mixroute.ai/v1/messages/count_tokens", bytes.NewBuffer(body))
    req.Header.Set("Authorization", "Bearer sk-xxxxxxxxxx")
    req.Header.Set("Content-Type", "application/json")
    http.DefaultClient.Do(req)
}
```

```java Java theme={null}
import java.net.http.*;
import java.net.URI;

HttpClient client = HttpClient.newHttpClient();
String json = """
    {
      "model": "claude-opus-4-8",
      "messages": [
        {"role": "user", "content": "Hello, how are you?"}
      ]
    }
    """;
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.mixroute.ai/v1/messages/count_tokens"))
    .header("Authorization", "Bearer sk-xxxxxxxxxx")
    .header("Content-Type", "application/json")
    .POST(HttpRequest.BodyPublishers.ofString(json))
    .build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());
```

```ruby Ruby theme={null}
require 'net/http'
require 'json'

uri = URI('https://api.mixroute.ai/v1/messages/count_tokens')
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true

request = Net::HTTP::Post.new(uri)
request['Authorization'] = 'Bearer sk-xxxxxxxxxx'
request['Content-Type'] = 'application/json'
request.body = {
  model: 'claude-opus-4-8',
  messages: [
    { role: 'user', content: 'Hello, how are you?' }
  ]
}.to_json

response = http.request(request)
puts response.body
```

```json Response theme={null}
{
  "input_tokens": 14
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.