Claude API token 計數（count tokens）怎麼用：發請求前先量，再估算費用

本文根據 Claude 官方《Token counting》整理，資料核對於 2026-11-05。配圖為本站整理的示意圖，不是介面截圖。代碼裏的模型名取自官方當天示例，請以官方模型頁為準。本站（bigolab.com）不是 Anthropic 官方網站。API 是按用量計費的獨立服務，與 Claude 訂閱分開計算，Key 的獲取見 /guides/claude-api-key-console。

適用於誰

• 想在正式調用前估算一次請求、一批文件會花多少錢的開發者；
• 提示詞越寫越長，擔心塞不進上下文窗口的人；
• 想按長度把請求分給不同模型，做“路由”的人；
• 從舊模型遷移到新模型，發現 token 數變了的人。

結論先說

1. 官方提供免費的計數接口 /v1/messages/count_tokens，參數和創建消息幾乎一樣，返回 input_tokens。
2. 它只數輸入，數的是你發出去會佔多少 token，不會真的生成回答。
3. 結果是估算，和實際用量可能有小幅差異；系統自動添加的 token 不向你收費。
4. 有些輸入不能數：伺服器工具、MCP 連接器、url 或 file 來源的圖片和 PDF。圖片和 PDF 要用 base64。
5. 新模型的分詞器不同：Claude 4.7 及之後的模型，同樣的文字大約多出 30% 的 token，換模型要重新數。

圖：本站根據 Claude 官方《Token counting》 整理的示意圖

一、最小示例

Python：

python
import anthropic

client = anthropic.Anthropic()

count = client.messages.count_tokens(
    model="claude-opus-5-5",  # 以官方模型頁當天為準
    system="你是一位科學家",
    messages=[{"role": "user", "content": "你好，Claude"}],
)

print(count.input_tokens)

TypeScript：

typescript
import Anthropic from "@anthropic-ai/sdk";

const client = new Anthropic();

const count = await client.messages.countTokens({
  model: "claude-opus-5-5",
  system: "你是一位科學家",
  messages: [{ role: "user", content: "你好，Claude" }],
});

console.log(count.input_tokens);

響應形如 { "input_tokens": 14 }。注意：請求裏要寫 model，因為不同模型的分詞器不一樣，數出來的數不同。

二、帶工具、圖片、PDF 的計數

計數接口接受與創建消息相同的結構，所以可以把你真正要發的請求原樣拿來數：

• 帶工具：把 tools 一起傳進去，工具定義也佔 token。官方示例裏一個 get_weather 工具加一句提問，計數是幾百個 token，遠多於單獨一句話；
• 帶圖片：用 base64 來源的 image 塊，規則見 /guides/claude-api-image-input；
• 帶 PDF：用 base64 來源的 document 塊，規則見 /guides/claude-api-pdf-support；
• 帶思考：官方寫明當前輪的思考計入輸入 token；之前輪次的思考塊是否計入，取決於模型是保留全部歷史思考，還是隻保留最近一輪。

工具的寫法見 /guides/claude-tool-use-basics。

三、哪些輸入不能數

官方列出，下面這些輸入對 Messages API 是合法的，但計數接口會返回 invalid_request_error：

• 伺服器工具，比如網頁搜尋、網頁抓取、代碼執行、工具搜尋（顧問工具除外）；
• MCP 連接器；
• 來源為 url 或 file 的 image 或 document 塊。

做法：圖片和 PDF 先下載讀成 base64 再數；用了伺服器工具或 MCP 伺服器的請求，實際用量只能在真實請求返回的 usage 裏看。

四、為什麼是估算，換模型為什麼不一樣

官方明確說這是估算值：有時實際輸入 token 與計數相差很少。計數可能包含 Anthropic 為系統優化自動添加的 token，但這部分不向你收費，帳單只算你自己的內容。

另一個容易踩的地方：Claude 4.7 及之後的模型、以及 Fable 和 Mythos 系列使用新分詞器，同樣的文字大約多出 30% 的 token，具體看內容類型。官方因此要求，從舊模型遷移時，不要拿舊模型的計數去估新模型的費用或上下文佔用，而是用要用的那個 model 重新數一遍。想知道差別有多大，就把同一份請求用舊模型和新模型各數一次，對比兩個 input_tokens。

五、限額：免費，但有每分鐘請求數

圖：本站根據 Claude 官方《Token counting》 整理的示意圖

官方寫明計數接口免費，但受每分鐘請求數限制，按你的用量檔位：

計數和創建消息的限額各算各的，互不佔用。需要更高限額，官方說可以在 Claude Console 的限額（Rate limits）頁面用“Request tier increase”申請提升檔位；限流報錯 429 的排查見 /guides/claude-api-error-429-rate-limit。還有一點：計數不使用提示詞緩存，即使傳了 cache_control，緩存也只在真正創建消息時才發生，所以它數出來的是“不命中緩存”的輸入量，緩存的省錢原理見 /guides/claude-prompt-caching。

六、發完請求後，用 usage 核對

每次真正的調用，響應裏都有 usage，這是帳單的依據。TypeScript SDK 頁的示例輸出是 { input_tokens: 25, output_tokens: 13 }。用了提示詞緩存時，還會多出緩存寫入和緩存讀取的字段。開啟思考時，usage.output_tokens_details.thinking_tokens 會告訴你輸出裏有多少是思考（流式時這個明細只出現在最後一個 message_delta 事件裏，事件順序見 /guides/claude-api-streaming）。

七、一個估算費用的小函數

下面是本站寫的示意，把官方價格頁當天的單價填進去（單位通常是每百萬 token 多少錢，以官方為準）：

python
def estimate_cost(input_tokens, expected_output_tokens, in_price_per_mtok, out_price_per_mtok):
    return (input_tokens * in_price_per_mtok + expected_output_tokens * out_price_per_mtok) / 1_000_000

count = client.messages.count_tokens(model="claude-opus-5-5", messages=[...])
# 單價請自行從官方價格頁填寫，這裏不寫具體數字
# cost = estimate_cost(count.input_tokens, 800, 單價_輸入, 單價_輸出)

輸出 token 無法事先數出來，只能按你預期的回答長度和 max_tokens 來估一個範圍。批量請求可以按官方的批量折扣再估一次，見 /guides/claude-api-message-batches。

常見問題

Q：計數接口會產生費用嗎？

官方寫明免費，受每分鐘請求數限制。

Q：數出來的和帳單不一樣？

這是估算，加上系統添加的 token 不收費、緩存命中會改變實際計費，所以會有差別；以真實請求返回的 usage 為準。

Q：換了新模型，token 數怎麼變多了？

Claude 4.7 及之後的模型分詞器不同，同樣內容大約多約 30%，需要用新模型重新數。

Q：想數帶網頁搜尋工具的請求？

計數接口不支持伺服器工具，只能發真實請求後看 usage。

參考資料

• Claude 官方：Token counting — https://platform.claude.com/docs/en/build-with-claude/token-counting
• Claude 官方：TypeScript SDK — https://platform.claude.com/docs/en/cli-sdks-libraries/sdks/typescript
• Claude 官方：Extended thinking — https://platform.claude.com/docs/en/build-with-claude/extended-thinking