Count tokens (Anthropic)¶
POST /v1/messages/count_tokens tells you how many input tokens a message will use before you send it, to stay under
a context window or a budget. Through the gateway it works whatever model the name points to: Anthropic counts for
Claude, and the gateway counts for everything else, without calling or billing a provider.
What it is¶
Anthropic's token-counting endpoint. It takes the same body as Messages (model, messages, and
optionally system, tools, thinking) and answers {"input_tokens": N}. It costs nothing at Anthropic, and the
gateway's own count costs nothing at all.
| Model behind the name | Who counts |
|---|---|
| Claude on Anthropic | Anthropic, as it always does |
| Any other provider's model (OpenAI, Azure, Gemini on Google AI Studio or Vertex AI) | The gateway itself, with no call to the provider |
| Claude on Amazon Bedrock or Vertex AI | The gateway itself, with no call to the provider: an estimate, marked x-vidai-token-count: estimated |
The two settings¶
The same as for Messages: ANTHROPIC_BASE_URL (base_url, baseURL) set to https://<your-gateway>,
and ANTHROPIC_API_KEY (api_key, apiKey) set to your Vidai key.
A minimal call¶
import anthropic
client = anthropic.Anthropic()
count = client.messages.count_tokens(
model="claude-sonnet-4.5",
messages=[{"role": "user", "content": "Summarise our travel policy in three lines."}],
)
print(count.input_tokens)
import Anthropic from "@anthropic-ai/sdk";
const client = new Anthropic();
const count = await client.messages.countTokens({
model: "claude-sonnet-4.5",
messages: [{ role: "user", content: "Summarise our travel policy in three lines." }],
});
console.log(count.input_tokens);
curl https://<your-gateway>/v1/messages/count_tokens \
-H "x-api-key: $ANTHROPIC_API_KEY" -H "anthropic-version: 2023-06-01" \
-H "content-type: application/json" \
-d '{"model":"claude-sonnet-4.5",
"messages":[{"role":"user","content":"Summarise our travel policy in three lines."}]}'
Reading what the gateway did¶
When the gateway answered the count itself, the response carries x-vidai-token-count:
| Value | Meaning |
|---|---|
tokenizer-match |
Counted with the tokenizer of the model's own family: close to what the provider will charge |
estimated |
Counted with a near tokenizer: treat it as an estimate and leave some headroom |
No header means the provider counted. Read it with client.messages.with_raw_response.count_tokens(...) in Python, or
.withResponse() in TypeScript, as on Messages. x-vidai-request-id is
there either way.
Errors¶
In Anthropic's shape, as on Messages: model_not_found, model_not_allowed and the key codes
apply here too. Match on x-vidai-error-code.
Model names¶
Any name your key may call, as listed under Models in the Control room.
Check it works in a minute¶
Run the curl above with a model of another provider (for example gpt-4.1) and add -i: a 200 with
{"input_tokens": …} and an x-vidai-token-count header means the gateway counted it.
Good to know¶
- A gateway count is for planning, not billing: what you're charged is what the provider reports on the real call, which you find in Request logs.
- Images, documents and tools add tokens that a near tokenizer may count differently; keep a margin when the header
says
estimated.