Count tokens (Gemini)¶
countTokens tells you how many tokens a prompt 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: Google counts for Gemini, and the gateway
counts for everything else, without calling or billing a provider.
What it is¶
POST /v1beta/models/{model}:countTokens, with the same contents (and optionally systemInstruction, tools) as
Generate content. The answer has totalTokens.
| Model behind the name | Who counts |
|---|---|
| Gemini (Google AI Studio, Vertex AI) | Google, as it always does |
| Any other provider's model (OpenAI, Azure, Claude, Bedrock) | The gateway itself, with no call to the provider |
The two settings¶
The same as for Generate content: base address https://<your-gateway>, API version v1beta,
and your Vidai key as the API key.
A minimal call¶
from google import genai
from google.genai import types
client = genai.Client(
api_key="vk_…",
http_options=types.HttpOptions(base_url="https://<your-gateway>", api_version="v1beta"),
)
result = client.models.count_tokens(
model="gemini-3.5-flash",
contents="Summarise our travel policy in three lines.",
)
print(result.total_tokens)
import { GoogleGenAI } from "@google/genai";
const ai = new GoogleGenAI({ apiKey: "vk_…", apiVersion: "v1beta", httpOptions: { baseUrl: "https://<your-gateway>" } });
const result = await ai.models.countTokens({
model: "gemini-3.5-flash",
contents: "Summarise our travel policy in three lines.",
});
console.log(result.totalTokens);
curl "https://<your-gateway>/v1beta/models/gemini-3.5-flash:countTokens" \
-H "x-goog-api-key: $GEMINI_API_KEY" -H "content-type: application/json" \
-d '{"contents":[{"parts":[{"text":"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 |
estimated |
Counted with a near tokenizer: treat it as an estimate and leave some headroom |
No header means Google counted. In Python, read headers from result.sdk_http_response.headers; in TypeScript, from
result.sdkHttpResponse?.headers. x-vidai-request-id is there either way.
Errors¶
In Google's shape, as on Generate content. 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 another provider's model (for example claude-sonnet-4.5) and add -i: a 200 with
totalTokens 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, audio and tools may be counted differently by a near tokenizer; keep a margin when the header says
estimated.