Skip to main content

​
Set up

Wrap an instance of GoogleGenAI from @google/genai, Google’s Gen AI SDK. The SDK recognizes it automatically.
Both models.generateContent and models.generateContentStream are covered. A streamed call is reported once, when the stream finishes.

​
Chats: wrap each chat as well

Gemini has two ways to call a model: one-shot calls through ai.models, and conversations through ai.chats. A chat keeps its own reference to the original, unwrapped client, so calls made through a chat are not metered by wrapping the client alone. Wrap each chat you create too:
Both sendMessage and sendMessageStream are covered. Nothing is counted twice if you wrap both the client and a chat, because a chat never goes through the wrapped client.

​
Automatic function calling: stream the call

When you give Gemini a function it can call, Google’s SDK can run the tool loop for you: one generateContent call can make up to ten model calls, and returns only the last response. Without streaming, the usage of the earlier calls is not in that response, so it cannot be reported. The SDK reports what it can see, tags the event with gemini_afc_rounds, and reports the shortfall to onError. To meter every round, either stream the call, or set automaticFunctionCalling: { disable: true } and run the loop yourself, so each model call goes through the wrapped client. See Google’s function calling guide.

​
Requested usage

To check each call against its output limit instead of a requested usage of 1, use the opt-in estimateFromMaxOutputTokens(tokensPerUnit) estimate. It reads config.maxOutputTokens from the call.

​
What is reported

Every Gemini response includes a usageMetadata object: the number of tokens the call used, split into the prompt, the response, tokens served from the cache, thinking tokens and tool-use prompt tokens, with a total. The wrapper reads these and reports them to Stigg under Gemini’s own names. For details on each field, see Google’s UsageMetadata reference and token counting guide.
Gemini’s counters overlap in both directions. promptTokenCount already includes cachedContentTokenCount, so pricing both bills cached tokens twice. thoughtsTokenCount and toolUsePromptTokenCount are not included in the prompt or response counts, so if you leave them out of your pricing, a reasoning model’s thinking tokens are free. promptTokenCount, candidatesTokenCount, thoughtsTokenCount and toolUsePromptTokenCount add up to totalTokenCount. Price the total, or the parts, but never both.
To avoid working this out, use the normalized metrics. They count Gemini’s cached tokens once, and its thinking and tool-use tokens as output and input. Every usage field Gemini returns is also included, with a raw. prefix. See How usage is reported.

​
Not covered

Only text generation is metered. Embeddings (models.embedContent), image and video generation, countTokens, batch jobs, cache management and the Live API are billable but count in different units, so they are passed through without checks or reporting. To meter one of them, write your own recipe.