跳转到主要内容
POST
/
v1
/
messages
/
count_tokens
计算 Token 数量（Claude）
curl --request POST \
  --url https://llm.ai-nebula.com/v1/messages/count_tokens \
  --header 'Authorization: <authorization>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "model": "<string>",
  "messages": [
    {}
  ],
  "system": {},
  "tools": [
    {}
  ]
}
'
{
  "input_tokens": 14
}

Documentation Index

Fetch the complete documentation index at: https://docs.openai-nebula.com/llms.txt

Use this file to discover all available pages before exploring further.

​
简介

计算 Claude 消息的 token 数量，用于在发送请求前预估成本。此端点不消耗配额，仅进行本地计算。

​
认证

​
Authorization
string
必填
Bearer Token，如 Bearer sk-xxxxxxxxxx

​
请求参数

​
model
string
必填
Claude 模型标识，支持的模型包括：
  • claude-opus-4-5-20251101（推荐替代 claude-3-opus）
  • claude-haiku-4-5-20251001
  • claude-sonnet-4-5-20250929
  • claude-sonnet-4-20250514
  • 其他 Claude 系列模型
​
messages
array
必填
对话消息列表，每个元素包含 role（user/assistant）和 content。content 可以是字符串或媒体内容数组。支持的内容类型：
  • 纯文本消息
  • 多模态消息（包含图片）
  • 工具调用结果
​
system
string|array
系统提示词（可选），可以是字符串或媒体内容数组。用于设定模型的行为和角色。
​
tools
array
工具定义列表（可选），用于计算工具调用相关的 token 数量。

​
响应参数

​
input_tokens
number
输入消息的总 token 数量，包括：
  • system prompt 的 token 数
  • 所有 messages 的 token 数
  • tools 定义的 token 数（如果有）

​
基础示例

curl -X POST "https://llm.ai-nebula.com/v1/messages/count_tokens" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-xxxxxxxxxx" \
  -d '{
    "model": "claude-sonnet-4-5-20250929",
    "messages": [
      {
        "role": "user",
        "content": "Hello, how are you?"
      }
    ]
  }'

{
  "input_tokens": 14
}

​
高级用例

​
带工具定义的计算

curl -X POST "https://llm.ai-nebula.com/v1/messages/count_tokens" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-xxxxxxxxxx" \
  -d '{
    "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"]
        }
      }
    ]
  }'

​
多模态内容计算

curl -X POST "https://llm.ai-nebula.com/v1/messages/count_tokens" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-xxxxxxxxxx" \
  -d '{
    "model": "claude-sonnet-4-5-20250929",
    "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 数量以预估成本： 
# 批量计算成本
messages_batch = [...]  # 批量消息
total_tokens = 0

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

# 根据定价计算总成本
cost = total_tokens * price_per_token
print(f"预估成本: ${cost:.4f}")

​
2. 上下文窗口管理

检查消息是否超过模型的上下文窗口限制： 
MAX_CONTEXT_WINDOW = 200000  # Claude Sonnet 4.5 的上下文窗口

response = client.messages.count_tokens(
    model="claude-sonnet-4-5-20250929",
    messages=long_conversation
)

if response.input_tokens > MAX_CONTEXT_WINDOW:
    print(f"警告：消息 token 数 ({response.input_tokens}) 超过上下文窗口限制")
    # 执行消息截断或摘要

​
3. 优化提示词

比较不同提示词的 token 消耗： 
prompts = [
    "简洁版提示词...",
    "详细版提示词...",
    "超详细版提示词..."
]

for prompt in prompts:
    response = client.messages.count_tokens(
        model="claude-sonnet-4-5-20250929",
        system=prompt,
        messages=[{"role": "user", "content": "测试"}]
    )
    print(f"{len(prompt)} 字符 -> {response.input_tokens} tokens")

​
注意事项

  • 图片 token 使用固定估算值（约 1000 tokens），实际可能因分辨率不同而变化
  • 不包括 max_tokens 等输出相关参数，仅计算输入 token 数
  • 此端点不会发起实际的 AI 请求，不消耗配额

​
错误处理

​
缺少必需参数

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

​
无效的 API Key

{
  "error": {
    "message": "无效的 token",
    "type": "invalid_request_error"
  }
}

​
相关资源