Claude Messages Count Tokens API Application and Usage

The Claude Messages Count Tokens API can calculate the input token count of a message without actually creating the message, including the token count of tools, images, and documents. This is very useful when estimating costs or checking if the input exceeds the model's context limits.

This document mainly describes the usage process of the Claude Messages Count Tokens API.

Application Process

To use the Claude Messages Count Tokens API, first go to the 辰汐ai Console to obtain your API Token for backup.

If you are not logged in or registered, you will be automatically redirected to the login page inviting you to register and log in, and will automatically return to the current page after completion.

One API Token can call all services on the platform without needing to apply separately for each service. The first application will grant a free quota for a free experience; when the quota is insufficient, you can recharge the general balance in the console.

📘 Complete documentation: Claude Messages Count Tokens API →

Basic Usage

The request path for the Claude Messages Count Tokens API is /v1/messages/count_tokens, consistent with the Anthropic official API. We need to provide at least two required parameters:

  • model: Select the Claude model to use, such as claude-opus-4-8, claude-sonnet-4-6, etc.
  • messages: An array of input messages, each containing role and content.

Common optional parameters:

  • system: System prompt, which will be included in the token count.
  • tools: Tool definitions, which will be included in the token count.
  • thinking: Extended thinking configuration.
  • tool_choice: Tool selection configuration.
  • cache_control: Top-level or content block-level cache control configuration.

The usage of messages, system, tool call playback, URL images, and document/PDF content blocks follows the same stable request structure as the Messages API.

cURL Example

curl -X POST 'https://api.acedata.cloud/v1/messages/count_tokens' \
  -H 'accept: application/json' \
  -H 'authorization: Bearer {token}' \
  -H 'content-type: application/json' \
  -d '{
    "model": "claude-opus-4-8",
    "messages": [
      {
        "role": "user",
        "content": "Hello, Claude"
      }
    ]
  }'

Python Example

import httpx

url = "https://api.acedata.cloud/v1/messages/count_tokens"
headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json",
}
payload = {
    "model": "claude-opus-4-8",
    "messages": [
        {
            "role": "user",
            "content": "Hello, Claude"
        }
    ],
}
response = httpx.post(url, headers=headers, json=payload)
print(response.json())

Example of return result:

{
  "input_tokens": 11
}

Using Anthropic SDK

The Claude Messages Count Tokens API accepts the stable request structure of the Anthropic SDK and can be called using the anthropic library. The current return value is calculated by 辰汐ai's local estimator and is not the precise result of Anthropic's official tokenizer; the actual token numbers for multimodal, tools, and different Claude models may vary.

from anthropic import Anthropic

client = Anthropic(
    api_key="{token}",
    base_url="https://api.acedata.cloud",
)

result = client.messages.count_tokens(
    model="claude-opus-4-8",
    messages=[
        {
            "role": "user",
            "content": "Hello, Claude"
        }
    ],
)
print(result.input_tokens)

Token Count Including Tools

If your request includes tool definitions, these tools will also be included in the token count:

result = client.messages.count_tokens(
    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"]
            }
        }
    ],
)
print(result.input_tokens)

Token Count Including System Prompts

System prompts will also be included in the token count:

result = client.messages.count_tokens(
    model="claude-opus-4-8",
    system="You are a helpful assistant that speaks Chinese.",
    messages=[
        {
            "role": "user",
            "content": "Hello"
        }
    ],
)
print(result.input_tokens)

Notes

  • This API only calculates the input token count and does not produce any model output.
  • The token count result can be used for a rough estimate of input size and should not be used as a basis for precise billing, context window access, or model tokenizer comparisons.
  • The current estimator does not accurately calculate visual/document tokens for images and PDFs, nor can it reflect the differences in official tokenizers of different Claude models.
  • This API is completely free and does not consume any quota.