计算 Token
在发送 Anthropic 兼容-Messages 请求之前,估算其输入 Token 数。适合 Claude Code 等客户端做上下文管理(判断是否接近上下文窗口、何时压缩历史)。
| 项 | 值 |
|---|---|
| 方法与路径 | POST /v1/messages/count_tokens |
| 鉴权 | x-api-key: YOUR_API_KEY 或 Authorization: Bearer YOUR_API_KEY |
| Content-Type | application/json |
| 计费 | 不调用模型,不产生费用 |
结果是估算值,不是官方精确计数。 平台在本地计算,不请求模型服务商,结果与 Anthropic 官方
count_tokens、以及实际计费的usage.input_tokens会有偏差。只适合做量级判断和阈值控制,不要用于计费或对账。
快速示例
cURL
BASH
curl https://www.nextai-code.com/v1/messages/count_tokens \
-H "x-api-key: $NEXTAI_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "Content-Type: application/json" \
-d '{
"model": "claude-sonnet-5-5",
"system": "你是一名严谨的代码审查员。",
"messages": [
{"role": "user", "content": "请检查这段代码的并发安全性。"}
]
}'
Python(anthropic SDK)
PYTHON
import os
import anthropic
client = anthropic.Anthropic(
api_key=os.environ["NEXTAI_API_KEY"],
base_url="https://www.nextai-code.com",
)
result = client.messages.count_tokens(
model="claude-sonnet-5-5",
messages=[{"role": "user", "content": "请检查这段代码的并发安全性。"}],
)
print(result.input_tokens)
Node.js(@anthropic-ai/sdk)
JAVASCRIPT
import Anthropic from "@anthropic-ai/sdk";
const client = new Anthropic({
apiKey: process.env.NEXTAI_API_KEY,
baseURL: "https://www.nextai-code.com",
});
const result = await client.messages.countTokens({
model: "claude-sonnet-5-5",
messages: [{ role: "user", content: "请检查这段代码的并发安全性。" }],
});
console.log(result.input_tokens);
请求参数
请求体与 Anthropic 兼容-Messages 相同。只有下表字段参与计数,其余字段(max_tokens、thinking、stream 等)可以带上,不影响结果。
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
model |
string | 是 | 模型 ID |
messages |
array | 是 | 待估算的消息,不能为空 |
system |
string / array | 否 | 系统提示词,计入结果 |
tools |
array | 否 | 工具定义,name、description、input_schema 计入结果;必须是数组 |
响应
JSON
{
"input_tokens": 42
}
| 字段 | 类型 | 说明 |
|---|---|---|
input_tokens |
integer | 估算的输入 Token 数 |
计数规则与精度
| 内容 | 计数方式 |
|---|---|
文本(text、字符串 content、system) |
按文本分词计数 |
| 每条消息 | 计入 role,另加少量格式开销 |
图片(image 块) |
每张固定按 1000 Token 计,与图片尺寸无关 |
tool_use |
工具名 + input 的 JSON 文本 |
tool_result |
content 的 JSON 文本 |
tools |
每个工具的 name + description + input_schema JSON,另加少量格式开销 |
thinking 等其他块 |
不计入 |
分词方式与 Claude 官方不同、图片按固定值计、思考块不计入,所以估算值可能偏高或偏低。建议:
- 判断「是否接近上下文上限」时预留足够余量,例如按窗口的 80%~90% 设阈值。
- 需要真实用量时,以 Messages 响应中的
usage为准。
错误
错误体为 Anthropic 格式 {"type":"error","error":{"type":"...","message":"..."}}。参数校验类错误的 error.type 为 new_api_error,请以 HTTP 状态码判断错误类别。
| HTTP | 场景 |
|---|---|
| 400 | 请求体不是合法 JSON、messages 为空、缺少 model、max_tokens 数值异常 |
| 401 | API Key 无效或已过期,请到控制台「API Keys」页检查 |
| 402 | API Key 额度已用尽 |
| 500 | tools 不是数组等无法计数的请求体(提示「服务暂不可用」);请先检查 tools 格式再重试 |
通用错误见 错误码。