Repository Public
1Gemini and other generative AI models process input and output at a granularity2called a *token*.34**For Gemini models, a token is equivalent to about 4 characters.5100 tokens is equal to about 60-80 English words.**67## About tokens89Tokens can be single characters like `z` or whole words like `cat`. Long words10are broken up into several tokens. The set of all tokens used by the model is11called the vocabulary, and the process of splitting text into tokens is called12*tokenization*.1314When billing is enabled, the [cost of a call to the Gemini API](https://ai.google.dev/pricing) is15determined in part by the number of input and output tokens, so knowing how to16count tokens can be helpful.1718## Count tokens1920All input to and output from the Gemini API is tokenized, including text, image21files, and other non-text modalities.2223You can count tokens in the following ways:2425- **Call `count_tokens` with the input of the request.** Returns the total26 number of tokens in *the input only*. Make this call before sending input27 to check the size of your requests.2829- **Use the `usage` on the interaction response.** Returns token30 counts for input (`total_input_tokens`), output (`total_output_tokens`),31 thinking (`total_thought_tokens`), cached content32 (`total_cached_tokens`), tool use (`total_tool_use_tokens`),33 and total (`total_tokens`).3435### Count text tokens3637### Python3839 # This will only work for SDK newer than 2.0.040 from google import genai4142 client = genai.Client()43 prompt = "The quick brown fox jumps over the lazy dog."4445 # Count tokens before sending46 total_tokens = client.models.count_tokens(47 model="gemini-3.8-flash",48 contents=prompt49 )50 print("total_tokens:", total_tokens.total_tokens)5152 # Get usage from interaction53 interaction = client.interactions.create(54 model="gemini-3.8-flash",55 input=prompt56 )57 print(interaction.usage)5859### JavaScript6061 // This will only work for SDK newer than 2.0.062 import { GoogleGenAI } from '@google/genai';6364 const client = new GoogleGenAI({});65 const prompt = "The quick brown fox jumps over the lazy dog.";6667 // Count tokens before sending68 const countResponse = await client.models.countTokens({69 model: "gemini-3.8-flash",70 contents: prompt,71 });72 console.log(countResponse.totalTokens);7374 // Get usage from interaction75 const interaction = await client.interactions.create({76 model: "gemini-3.8-flash",77 input: prompt,78 });79 console.log(interaction.usage);8081### Java8283 import com.google.genai.Client;84 import com.google.genai.gaos.models.interactions.CreateModelInteraction;85 import com.google.genai.gaos.models.interactions.Interaction;86 import com.google.genai.gaos.models.interactions.InteractionsInput;87 import com.google.genai.gaos.models.interactions.Model;88 import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;89 import com.google.genai.types.CountTokensResponse;9091 Client client = new Client();92 String prompt = "The quick brown fox jumps over the lazy dog.";9394 // Count tokens before sending95 CountTokensResponse countResponse =96 client.models.countTokens("gemini-3.8-flash", prompt, null);97 System.out.println("total_tokens: " + countResponse.totalTokens().orElse(0));9899 // Get usage from interaction100 CreateModelInteraction params =101 CreateModelInteraction.builder()102 .model(Model.of("gemini-3.8-flash"))103 .input(InteractionsInput.of(prompt))104 .build();105106 Interaction interaction =107 client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();108 System.out.println(interaction.usage().orElse(null));109110### REST111112 # Specifies the API revision to avoid breaking changes when they become default113 curl -X POST "https://generativelanguage.googleapis.com/v1beta/models/gemini-3.8-flash:countTokens" \114 -H "x-goog-api-key: $GEMINI_API_KEY" \115 -H "Content-Type: application/json" \116 -d '{"contents": [{"parts": [{"text": "The quick brown fox."}]}]}'117118### Count multi-turn tokens119120Count tokens across conversation history using `previous_interaction_id`:121122### Python123124 # This will only work for SDK newer than 2.0.0125 # First interaction126 interaction1 = client.interactions.create(127 model="gemini-3.8-flash",128 input="Hi, my name is Bob"129 )130131 # Second interaction continues the conversation132 interaction2 = client.interactions.create(133 model="gemini-3.8-flash",134 input="What's my name?",135 previous_interaction_id=interaction1.id136 )137138 # Usage includes tokens from both turns139 print(f"Input tokens: {interaction2.usage.total_input_tokens}")140 print(f"Output tokens: {interaction2.usage.total_output_tokens}")141 print(f"Total tokens: {interaction2.usage.total_tokens}")142143### JavaScript144145 // This will only work for SDK newer than 2.0.0146 // First interaction147 const interaction1 = await client.interactions.create({148 model: "gemini-3.8-flash",149 input: "Hi, my name is Bob"150 });151152 // Second interaction continues the conversation153 const interaction2 = await client.interactions.create({154 model: "gemini-3.8-flash",155 input: "What's my name?",156 previous_interaction_id: interaction1.id157 });158159 console.log(`Input tokens: ${interaction2.usage.total_input_tokens}`);160 console.log(`Output tokens: ${interaction2.usage.total_output_tokens}`);161162### Java163164 import com.google.genai.Client;165 import com.google.genai.gaos.models.interactions.CreateModelInteraction;166 import com.google.genai.gaos.models.interactions.Interaction;167 import com.google.genai.gaos.models.interactions.InteractionsInput;168 import com.google.genai.gaos.models.interactions.Model;169 import com.google.genai.gaos.models.interactions.Usage;170 import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;171172 Client client = new Client();173174 // First interaction175 CreateModelInteraction params1 =176 CreateModelInteraction.builder()177 .model(Model.of("gemini-3.8-flash"))178 .input(InteractionsInput.of("Hi, my name is Bob"))179 .build();180181 Interaction interaction1 =182 client.interactions.create(CreateInteractionRequestBody.of(params1)).interaction().get();183184 // Second interaction continues the conversation185 CreateModelInteraction params2 =186 CreateModelInteraction.builder()187 .model(Model.of("gemini-3.8-flash"))188 .input(InteractionsInput.of("What's my name?"))189 .previousInteractionId(interaction1.id().orElse(""))190 .build();191192 Interaction interaction2 =193 client.interactions.create(CreateInteractionRequestBody.of(params2)).interaction().get();194195 // Usage includes tokens from both turns196 if (interaction2.usage().isPresent()) {197 Usage usage = interaction2.usage().get();198 System.out.println("Input tokens: " + usage.totalInputTokens().orElse(0));199 System.out.println("Output tokens: " + usage.totalOutputTokens().orElse(0));200 System.out.println("Total tokens: " + usage.totalTokens().orElse(0));201 }202203### Count multimodal tokens204205All input to the Gemini API is tokenized, including images, video, and audio.206Key points about tokenization:207208- **Images**: Images ≤384 pixels in both dimensions count as 258 tokens. Larger images are tiled into 768x768 pixel tiles, each counting as 258 tokens.209- **Video** : 263 tokens per second (applies to static processing). For agentic processing, token usage varies. See [Video token usage by processing mode](https://ai.google.dev/gemini-api/docs/tokens#video-token-usage).210- **Audio**: 32 tokens per second211212#### Image tokens213214### Python215216 # This will only work for SDK newer than 2.0.0217 uploaded_file = client.files.upload(file="path/to/image.jpg")218219 # Count tokens for image + text220 total_tokens = client.models.count_tokens(221 model="gemini-3.8-flash",222 contents=["Tell me about this image", uploaded_file]223 )224 print(f"Total tokens: {total_tokens}")225226 # Generate with image227 interaction = client.interactions.create(228 model="gemini-3.8-flash",229 input=[230 {"type": "text", "text": "Tell me about this image"},231 {"type": "image", "uri": uploaded_file.uri, "mime_type": uploaded_file.mime_type}232 ]233 )234 print(interaction.usage)235236### JavaScript237238 // This will only work for SDK newer than 2.0.0239 const uploadedFile = await client.files.upload({240 file: "path/to/image.jpg",241 config: { mimeType: "image/jpeg" }242 });243244 // Count tokens245 const countResponse = await client.models.countTokens({246 model: "gemini-3.8-flash",247 contents: [248 { text: "Tell me about this image" },249 { fileData: { fileUri: uploadedFile.uri, mimeType: uploadedFile.mimeType } }250 ]251 });252 console.log(countResponse.totalTokens);253254### Java255256 import com.google.genai.Client;257 import com.google.genai.gaos.models.interactions.CreateModelInteraction;258 import com.google.genai.gaos.models.interactions.ImageContent;259 import com.google.genai.gaos.models.interactions.ImageContentMimeType;260 import com.google.genai.gaos.models.interactions.Interaction;261 import com.google.genai.gaos.models.interactions.InteractionsInput;262 import com.google.genai.gaos.models.interactions.Model;263 import com.google.genai.gaos.models.interactions.TextContent;264 import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;265 import com.google.genai.types.Content;266 import com.google.genai.types.CountTokensResponse;267 import com.google.genai.types.File;268 import com.google.genai.types.Part;269 import com.google.genai.types.UploadFileConfig;270 import java.util.Arrays;271272 Client client = new Client();273274 File uploadedFile =275 client.files.upload(276 new java.io.File("path/to/image.jpg"),277 UploadFileConfig.builder().mimeType("image/jpeg").build());278279 // Count tokens for image + text280 CountTokensResponse countResponse =281 client.models.countTokens(282 "gemini-3.8-flash",283 Arrays.asList(284 Content.fromParts(285 Part.fromText("Tell me about this image"),286 Part.fromUri(287 uploadedFile.uri().orElse(""), uploadedFile.mimeType().orElse("image/jpeg")))),288 null);289 System.out.println("Total tokens: " + countResponse.totalTokens().orElse(0));290291 // Generate with image292 CreateModelInteraction params =293 CreateModelInteraction.builder()294 .model(Model.of("gemini-3.8-flash"))295 .input(296 InteractionsInput.ofContent(297 Arrays.asList(298 TextContent.builder().text("Tell me about this image").build(),299 ImageContent.builder()300 .uri(uploadedFile.uri().orElse(""))301 .mimeType(302 ImageContentMimeType.of(uploadedFile.mimeType().orElse("image/jpeg")))303 .build())))304 .build();305306 Interaction interaction =307 client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();308 System.out.println(interaction.usage().orElse(null));309310**Inline data example:**311312### Python313314 # This will only work for SDK newer than 2.0.0315 import base64316317 with open('image.jpg', 'rb') as f:318 image_bytes = f.read()319320 interaction = client.interactions.create(321 model="gemini-3.8-flash",322 input=[323 {"type": "text", "text": "Describe this image"},324 {325 "type": "image",326 "data": base64.b64encode(image_bytes).decode('utf-8'),327 "mime_type": "image/jpeg"328 }329 ]330 )331 print(interaction.usage)332333#### Video tokens334335### Python336337 # This will only work for SDK newer than 2.0.0338 import time339340 video_file = client.files.upload(file="path/to/video.mp4")341342 while not video_file.state or video_file.state.name != "ACTIVE":343 print("Processing video...")344 time.sleep(5)345 video_file = client.files.get(name=video_file.name)346347 # A 60-second video is approximately 100 * 60 = 6,000 tokens348 total_tokens = client.models.count_tokens(349 model="gemini-3.8-flash",350 contents=["Summarize this video", video_file]351 )352 print(f"Total tokens: {total_tokens}")353354 # Generate with video355 interaction = client.interactions.create(356 model="gemini-3.8-flash",357 input=[358 {"type": "text", "text": "Summarize this video"},359 {"type": "video", "uri": video_file.uri, "mime_type": video_file.mime_type}360 ]361 )362 print(interaction.usage)363364#### Video token usage by processing mode365366Token usage for video depends on the processing mode:367368| **Processing mode** | **Token calculation** | **Typical usage** |369|---|---|---|370| **Static** (default) | \~100 tokens/second by default (low resolution) or \~300 tokens/second (high resolution). All frames sampled at 1 FPS. | Predictable, proportional to video duration. |371| **Agentic** | Varies by content complexity. The model loads only the transcript and/or frames and/or audio needed to answer the prompt. | Up to 88% fewer tokens for long-form content. |372373With agentic processing, a 1-hour lecture that would use \~1.08M tokens in374static mode might use \~108K tokens, depending on the prompt and content.375376> [!NOTE]377> **Note:** For static processing, token calculations assume the default sampling rate of 1 FPS. If you set a [custom frame rate](https://ai.google.dev/gemini-api/docs/generate-content/video-understanding#custom-frame-rate) in the GenerateContent API, token usage scales proportionally with the configured FPS.378379To check actual token usage for a request, inspect `interaction.usage`. Agentic video tokens are reported across the following fields:380381- **Initial prompt** (video reference + user prompt): `total_input_tokens`382- **Navigation thinking** : `total_thought_tokens`383- **Transcript, frames, and audio loaded on demand** : `total_tool_use_tokens`384- **Final answer** : `total_output_tokens`385386#### Audio tokens387388### Python389390 # This will only work for SDK newer than 2.0.0391 audio_file = client.files.upload(file="path/to/audio.mp3")392393 # A 60-second audio clip is approximately 32 * 60 = 1,920 tokens394 total_tokens = client.models.count_tokens(395 model="gemini-3.8-flash",396 contents=["Transcribe this audio", audio_file]397 )398 print(f"Total tokens: {total_tokens}")399400 # Generate with audio401 interaction = client.interactions.create(402 model="gemini-3.8-flash",403 input=[404 {"type": "text", "text": "Transcribe this audio"},405 {"type": "audio", "uri": audio_file.uri, "mime_type": audio_file.mime_type}406 ]407 )408 print(interaction.usage)409410### Count system instruction tokens411412System instructions are counted as part of the input tokens:413414### Python415416 # This will only work for SDK newer than 2.0.0417 interaction = client.interactions.create(418 model="gemini-3.8-flash",419 input="Hello!",420 system_instruction="You are a helpful assistant who speaks like a pirate."421 )422423 # system_instruction tokens included in total_input_tokens424 print(f"Input tokens: {interaction.usage.total_input_tokens}")425426### Count tool tokens427428Tools (functions, code execution, Google Search) are also counted:429430### Python431432 # This will only work for SDK newer than 2.0.0433 tools = [434 {435 "type": "function",436 "name": "get_weather",437 "description": "Get current weather",438 "parameters": {439 "type": "object",440 "properties": {441 "location": {"type": "string"}442 }443 }444 }445 ]446447 interaction = client.interactions.create(448 model="gemini-3.8-flash",449 input="What's the weather in Tokyo?",450 tools=tools451 )452453 print(f"Input tokens: {interaction.usage.total_input_tokens}")454 print(f"Tool use tokens: {interaction.usage.total_tool_use_tokens}")455456## Context window457458Each Gemini model has a maximum number of tokens it can handle. The context459window defines the combined limit of input and output tokens.460461### Get context window size programmatically462463### Python464465 # This will only work for SDK newer than 2.0.0466 model_info = client.models.get(model="gemini-3.8-flash")467 print(f"Input token limit: {model_info.input_token_limit}")468 print(f"Output token limit: {model_info.output_token_limit}")469470### JavaScript471472 // This will only work for SDK newer than 2.0.0473 const modelInfo = await client.models.get({ model: "gemini-3.8-flash" });474 console.log(`Input token limit: ${modelInfo.inputTokenLimit}`);475 console.log(`Output token limit: ${modelInfo.outputTokenLimit}`);476477### Java478479 import com.google.genai.Client;480 import com.google.genai.types.Model;481482 Client client = new Client();483484 Model modelInfo = client.models.get("gemini-3.8-flash", null);485 System.out.println("Input token limit: " + modelInfo.inputTokenLimit().orElse(0));486 System.out.println("Output token limit: " + modelInfo.outputTokenLimit().orElse(0));487488Find context window sizes on the [models](https://ai.google.dev/gemini-api/docs/models) page.489490## What's next491492- [Text generation](https://ai.google.dev/gemini-api/docs/text-generation): Generation basics493- [Caching](https://ai.google.dev/gemini-api/docs/caching): Reduce costs with caching494- [Pricing](https://ai.google.dev/gemini-api/docs/pricing): Understand costs