Repository Public
1# Understand and count tokens23> [!NOTE]4> **Note** : This version of the page covers the new [Interactions API](https://ai.google.dev/gemini-api/docs/interactions/interactions-overview), which is currently in Beta. 5> For stable production deployments, we recommend you continue to use the `generateContent` API. You can use the toggle on this page to switch between the versions.67Gemini and other generative AI models process input and output at a granularity8called a *token*.910**For Gemini models, a token is equivalent to about 4 characters.11100 tokens is equal to about 60-80 English words.**1213## About tokens1415Tokens can be single characters like `z` or whole words like `cat`. Long words16are broken up into several tokens. The set of all tokens used by the model is17called the vocabulary, and the process of splitting text into tokens is called18*tokenization*.1920When billing is enabled, the [cost of a call to the Gemini API](https://ai.google.dev/pricing) is21determined in part by the number of input and output tokens, so knowing how to22count tokens can be helpful.2324## Count tokens2526All input to and output from the Gemini API is tokenized, including text, image27files, and other non-text modalities.2829You can count tokens in the following ways:3031- **Call `count_tokens` with the input of the request.** Returns the total32 number of tokens in *the input only*. Make this call before sending input33 to check the size of your requests.3435- **Use the `usage` on the interaction response.** Returns token36 counts for input (`total_input_tokens`), output (`total_output_tokens`),37 thinking (`total_thought_tokens`), cached content38 (`total_cached_tokens`), tool use (`total_tool_use_tokens`),39 and total (`total_tokens`).4041### Count text tokens4243### Python4445 # This will only work for SDK newer than 2.0.046 from google import genai4748 client = genai.Client()49 prompt = "The quick brown fox jumps over the lazy dog."5051 # Count tokens before sending52 total_tokens = client.models.count_tokens(53 model="gemini-3.5-flash",54 contents=prompt55 )56 print("total_tokens:", total_tokens.total_tokens)5758 # Get usage from interaction59 interaction = client.interactions.create(60 model="gemini-3.5-flash",61 input=prompt62 )63 print(interaction.usage)6465### JavaScript6667 // This will only work for SDK newer than 2.0.068 import { GoogleGenAI } from '@google/genai';6970 const client = new GoogleGenAI({});71 const prompt = "The quick brown fox jumps over the lazy dog.";7273 // Count tokens before sending74 const countResponse = await client.models.countTokens({75 model: "gemini-3.5-flash",76 contents: prompt,77 });78 console.log(countResponse.totalTokens);7980 // Get usage from interaction81 const interaction = await client.interactions.create({82 model: "gemini-3.5-flash",83 input: prompt,84 });85 console.log(interaction.usage);8687### REST8889 # Specifies the API revision to avoid breaking changes when they become default90 curl -X POST "https://generativelanguage.googleapis.com/v1beta/models/gemini-3.5-flash:countTokens" \91 -H "x-goog-api-key: $GEMINI_API_KEY" \92 -H "Content-Type: application/json" \93 -H "Api-Revision: 2026-05-20" \94 -d '{"contents": [{"parts": [{"text": "The quick brown fox."}]}]}'9596### Count multi-turn tokens9798Count tokens across conversation history using `previous_interaction_id`:99100### Python101102 # This will only work for SDK newer than 2.0.0103 # First interaction104 interaction1 = client.interactions.create(105 model="gemini-3.5-flash",106 input="Hi, my name is Bob"107 )108109 # Second interaction continues the conversation110 interaction2 = client.interactions.create(111 model="gemini-3.5-flash",112 input="What's my name?",113 previous_interaction_id=interaction1.id114 )115116 # Usage includes tokens from both turns117 print(f"Input tokens: {interaction2.usage.total_input_tokens}")118 print(f"Output tokens: {interaction2.usage.total_output_tokens}")119 print(f"Total tokens: {interaction2.usage.total_tokens}")120121### JavaScript122123 // This will only work for SDK newer than 2.0.0124 // First interaction125 const interaction1 = await client.interactions.create({126 model: "gemini-3.5-flash",127 input: "Hi, my name is Bob"128 });129130 // Second interaction continues the conversation131 const interaction2 = await client.interactions.create({132 model: "gemini-3.5-flash",133 input: "What's my name?",134 previous_interaction_id: interaction1.id135 });136137 console.log(`Input tokens: ${interaction2.usage.total_input_tokens}`);138 console.log(`Output tokens: ${interaction2.usage.total_output_tokens}`);139140### Count multimodal tokens141142All input to the Gemini API is tokenized, including images, video, and audio.143Key points about tokenization:144145- **Images**: Images ≤384 pixels in both dimensions count as 258 tokens. Larger images are tiled into 768x768 pixel tiles, each counting as 258 tokens.146- **Video**: 263 tokens per second147- **Audio**: 32 tokens per second148149#### Image tokens150151### Python152153 # This will only work for SDK newer than 2.0.0154 uploaded_file = client.files.upload(file="path/to/image.jpg")155156 # Count tokens for image + text157 total_tokens = client.models.count_tokens(158 model="gemini-3.5-flash",159 contents=["Tell me about this image", uploaded_file]160 )161 print(f"Total tokens: {total_tokens}")162163 # Generate with image164 interaction = client.interactions.create(165 model="gemini-3.5-flash",166 input=[167 {"type": "text", "text": "Tell me about this image"},168 {"type": "image", "uri": uploaded_file.uri, "mime_type": uploaded_file.mime_type}169 ]170 )171 print(interaction.usage)172173### JavaScript174175 // This will only work for SDK newer than 2.0.0176 const uploadedFile = await client.files.upload({177 file: "path/to/image.jpg",178 config: { mimeType: "image/jpeg" }179 });180181 // Count tokens182 const countResponse = await client.models.countTokens({183 model: "gemini-3.5-flash",184 contents: [185 { text: "Tell me about this image" },186 { fileData: { fileUri: uploadedFile.uri, mimeType: uploadedFile.mimeType } }187 ]188 });189 console.log(countResponse.totalTokens);190191**Inline data example:**192193### Python194195 # This will only work for SDK newer than 2.0.0196 import base64197198 with open('image.jpg', 'rb') as f:199 image_bytes = f.read()200201 interaction = client.interactions.create(202 model="gemini-3.5-flash",203 input=[204 {"type": "text", "text": "Describe this image"},205 {206 "type": "image",207 "data": base64.b64encode(image_bytes).decode('utf-8'),208 "mime_type": "image/jpeg"209 }210 ]211 )212 print(interaction.usage)213214#### Video tokens215216### Python217218 # This will only work for SDK newer than 2.0.0219 import time220221 video_file = client.files.upload(file="path/to/video.mp4")222223 while not video_file.state or video_file.state.name != "ACTIVE":224 print("Processing video...")225 time.sleep(5)226 video_file = client.files.get(name=video_file.name)227228 # A 60-second video is approximately 263 * 60 = 15,780 tokens229 total_tokens = client.models.count_tokens(230 model="gemini-3.5-flash",231 contents=["Summarize this video", video_file]232 )233 print(f"Total tokens: {total_tokens}")234235 # Generate with video236 interaction = client.interactions.create(237 model="gemini-3.5-flash",238 input=[239 {"type": "text", "text": "Summarize this video"},240 {"type": "video", "uri": video_file.uri, "mime_type": video_file.mime_type}241 ]242 )243 print(interaction.usage)244245#### Audio tokens246247### Python248249 # This will only work for SDK newer than 2.0.0250 audio_file = client.files.upload(file="path/to/audio.mp3")251252 # A 60-second audio clip is approximately 32 * 60 = 1,920 tokens253 total_tokens = client.models.count_tokens(254 model="gemini-3.5-flash",255 contents=["Transcribe this audio", audio_file]256 )257 print(f"Total tokens: {total_tokens}")258259 # Generate with audio260 interaction = client.interactions.create(261 model="gemini-3.5-flash",262 input=[263 {"type": "text", "text": "Transcribe this audio"},264 {"type": "audio", "uri": audio_file.uri, "mime_type": audio_file.mime_type}265 ]266 )267 print(interaction.usage)268269### Count system instruction tokens270271System instructions are counted as part of the input tokens:272273### Python274275 # This will only work for SDK newer than 2.0.0276 interaction = client.interactions.create(277 model="gemini-3.5-flash",278 input="Hello!",279 system_instruction="You are a helpful assistant who speaks like a pirate."280 )281282 # system_instruction tokens included in total_input_tokens283 print(f"Input tokens: {interaction.usage.total_input_tokens}")284285### Count tool tokens286287Tools (functions, code execution, Google Search) are also counted:288289### Python290291 # This will only work for SDK newer than 2.0.0292 tools = [293 {294 "type": "function",295 "name": "get_weather",296 "description": "Get current weather",297 "parameters": {298 "type": "object",299 "properties": {300 "location": {"type": "string"}301 }302 }303 }304 ]305306 interaction = client.interactions.create(307 model="gemini-3.5-flash",308 input="What's the weather in Tokyo?",309 tools=tools310 )311312 print(f"Input tokens: {interaction.usage.total_input_tokens}")313 print(f"Tool use tokens: {interaction.usage.total_tool_use_tokens}")314315## Context window316317Each Gemini model has a maximum number of tokens it can handle. The context318window defines the combined limit of input and output tokens.319320### Get context window size programmatically321322### Python323324 # This will only work for SDK newer than 2.0.0325 model_info = client.models.get(model="gemini-3.5-flash")326 print(f"Input token limit: {model_info.input_token_limit}")327 print(f"Output token limit: {model_info.output_token_limit}")328329### JavaScript330331 // This will only work for SDK newer than 2.0.0332 const modelInfo = await client.models.get({ model: "gemini-3.5-flash" });333 console.log(`Input token limit: ${modelInfo.inputTokenLimit}`);334 console.log(`Output token limit: ${modelInfo.outputTokenLimit}`);335336Find context window sizes on the [models](https://ai.google.dev/gemini-api/docs/models) page.337338## What's next339340- [Text generation](https://ai.google.dev/gemini-api/docs/interactions/text-generation): Generation basics341- [Caching](https://ai.google.dev/gemini-api/docs/interactions/caching): Reduce costs with caching342- [Pricing](https://ai.google.dev/gemini-api/docs/pricing): Understand costs