计算 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 格式再重试

通用错误见 错误码。

相关文档