Skip to content

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.