Gemini 和其他生成式 AI 模型以一种称为“token”的粒度处理输入和输出。
对于 Gemini 模型，一个 token 大致相当于 4 个字符。 100 个 token 大致相当于 60-80 个英文单词。
关于 token
token 可以是单个字符（例如 z），也可以是整个单词（例如 cat）。长单词会被拆分为多个 token。模型使用的所有
token 的集合称为词汇，将文本拆分为 token 的过程称为 token 化。
启用结算功能后，调用 Gemini API 的费用部分取决于输入和输出 token 的数量，因此了解如何 统计 token 数量可能会有所帮助。
统计 token 数量
Gemini API 的所有输入和输出都会进行 token 化，包括文本、图片文件和其他非文本模态。
您可以通过以下方式统计 token 数量：
使用请求的输入调用
count_tokens。返回 仅输入中的 token 总数。在发送输入之前进行此调用，以检查请求的大小。在互动响应中使用
usage。返回输入 (total_input_tokens)、输出 (total_output_tokens)、思考 (total_thought_tokens)、缓存内容 (total_cached_tokens)、工具使用 (total_tool_use_tokens) 和总计 (total_tokens) 的 token 计数。
统计文本 token 数量
Python
# This will only work for SDK newer than 2.0.0
from google import genai
client = genai.Client()
prompt = "The quick brown fox jumps over the lazy dog."
# Count tokens before sending
total_tokens = client.models.count_tokens(
model="gemini-3.8-flash",
contents=prompt
)
print("total_tokens:", total_tokens.total_tokens)
# Get usage from interaction
interaction = client.interactions.create(
model="gemini-3.8-flash",
input=prompt
)
print(interaction.usage)
JavaScript
// This will only work for SDK newer than 2.0.0
import { GoogleGenAI } from '@google/genai';
const client = new GoogleGenAI({});
const prompt = "The quick brown fox jumps over the lazy dog.";
// Count tokens before sending
const countResponse = await client.models.countTokens({
model: "gemini-3.8-flash",
contents: prompt,
});
console.log(countResponse.totalTokens);
// Get usage from interaction
const interaction = await client.interactions.create({
model: "gemini-3.8-flash",
input: prompt,
});
console.log(interaction.usage);
Java
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Model;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import com.google.genai.types.CountTokensResponse;
Client client = new Client();
String prompt = "The quick brown fox jumps over the lazy dog.";
// Count tokens before sending
CountTokensResponse countResponse =
client.models.countTokens("gemini-3.8-flash", prompt, null);
System.out.println("total_tokens: " + countResponse.totalTokens().orElse(0));
// Get usage from interaction
CreateModelInteraction params =
CreateModelInteraction.builder()
.model(Model.of("gemini-3.8-flash"))
.input(InteractionsInput.of(prompt))
.build();
Interaction interaction =
client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();
System.out.println(interaction.usage().orElse(null));
REST
# Specifies the API revision to avoid breaking changes when they become default
curl -X POST "https://generativelanguage.googleapis.com/v1beta/models/gemini-3.8-flash:countTokens" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-H "Content-Type: application/json" \
-d '{"contents": [{"parts": [{"text": "The quick brown fox."}]}]}'
统计多轮对话 token 数量
使用 previous_interaction_id 统计整个对话记录中的 token 数量：
Python
# This will only work for SDK newer than 2.0.0
# First interaction
interaction1 = client.interactions.create(
model="gemini-3.8-flash",
input="Hi, my name is Bob"
)
# Second interaction continues the conversation
interaction2 = client.interactions.create(
model="gemini-3.8-flash",
input="What's my name?",
previous_interaction_id=interaction1.id
)
# Usage includes tokens from both turns
print(f"Input tokens: {interaction2.usage.total_input_tokens}")
print(f"Output tokens: {interaction2.usage.total_output_tokens}")
print(f"Total tokens: {interaction2.usage.total_tokens}")
JavaScript
// This will only work for SDK newer than 2.0.0
// First interaction
const interaction1 = await client.interactions.create({
model: "gemini-3.8-flash",
input: "Hi, my name is Bob"
});
// Second interaction continues the conversation
const interaction2 = await client.interactions.create({
model: "gemini-3.8-flash",
input: "What's my name?",
previous_interaction_id: interaction1.id
});
console.log(`Input tokens: ${interaction2.usage.total_input_tokens}`);
console.log(`Output tokens: ${interaction2.usage.total_output_tokens}`);
Java
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Model;
import com.google.genai.gaos.models.interactions.Usage;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
Client client = new Client();
// First interaction
CreateModelInteraction params1 =
CreateModelInteraction.builder()
.model(Model.of("gemini-3.8-flash"))
.input(InteractionsInput.of("Hi, my name is Bob"))
.build();
Interaction interaction1 =
client.interactions.create(CreateInteractionRequestBody.of(params1)).interaction().get();
// Second interaction continues the conversation
CreateModelInteraction params2 =
CreateModelInteraction.builder()
.model(Model.of("gemini-3.8-flash"))
.input(InteractionsInput.of("What's my name?"))
.previousInteractionId(interaction1.id().orElse(""))
.build();
Interaction interaction2 =
client.interactions.create(CreateInteractionRequestBody.of(params2)).interaction().get();
// Usage includes tokens from both turns
if (interaction2.usage().isPresent()) {
Usage usage = interaction2.usage().get();
System.out.println("Input tokens: " + usage.totalInputTokens().orElse(0));
System.out.println("Output tokens: " + usage.totalOutputTokens().orElse(0));
System.out.println("Total tokens: " + usage.totalTokens().orElse(0));
}
统计多模态 token 数量
Gemini API 的所有输入都会进行 token 化，包括图片、视频和音频。 关于 token 化的要点：
- 图片：如果图片的两个尺寸均小于或等于 384 像素，则计为 258 个 token。较大的图片会被平铺为 768x768 像素的图块，每个图块计为 258 个 token。
- 视频：每秒 263 个 token（适用于静态处理）。对于智能体处理，token 使用量会有所不同。请参阅 按处理模式划分的视频 token 使用量。
- 音频：每秒 32 个 token
图片 token
Python
# This will only work for SDK newer than 2.0.0
uploaded_file = client.files.upload(file="path/to/image.jpg")
# Count tokens for image + text
total_tokens = client.models.count_tokens(
model="gemini-3.8-flash",
contents=["Tell me about this image", uploaded_file]
)
print(f"Total tokens: {total_tokens}")
# Generate with image
interaction = client.interactions.create(
model="gemini-3.8-flash",
input=[
{"type": "text", "text": "Tell me about this image"},
{"type": "image", "uri": uploaded_file.uri, "mime_type": uploaded_file.mime_type}
]
)
print(interaction.usage)
JavaScript
// This will only work for SDK newer than 2.0.0
const uploadedFile = await client.files.upload({
file: "path/to/image.jpg",
config: { mimeType: "image/jpeg" }
});
// Count tokens
const countResponse = await client.models.countTokens({
model: "gemini-3.8-flash",
contents: [
{ text: "Tell me about this image" },
{ fileData: { fileUri: uploadedFile.uri, mimeType: uploadedFile.mimeType } }
]
});
console.log(countResponse.totalTokens);
Java
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.ImageContent;
import com.google.genai.gaos.models.interactions.ImageContentMimeType;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Model;
import com.google.genai.gaos.models.interactions.TextContent;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import com.google.genai.types.Content;
import com.google.genai.types.CountTokensResponse;
import com.google.genai.types.File;
import com.google.genai.types.Part;
import com.google.genai.types.UploadFileConfig;
import java.util.Arrays;
Client client = new Client();
File uploadedFile =
client.files.upload(
new java.io.File("path/to/image.jpg"),
UploadFileConfig.builder().mimeType("image/jpeg").build());
// Count tokens for image + text
CountTokensResponse countResponse =
client.models.countTokens(
"gemini-3.8-flash",
Arrays.asList(
Content.fromParts(
Part.fromText("Tell me about this image"),
Part.fromUri(
uploadedFile.uri().orElse(""), uploadedFile.mimeType().orElse("image/jpeg")))),
null);
System.out.println("Total tokens: " + countResponse.totalTokens().orElse(0));
// Generate with image
CreateModelInteraction params =
CreateModelInteraction.builder()
.model(Model.of("gemini-3.8-flash"))
.input(
InteractionsInput.ofContent(
Arrays.asList(
TextContent.builder().text("Tell me about this image").build(),
ImageContent.builder()
.uri(uploadedFile.uri().orElse(""))
.mimeType(
ImageContentMimeType.of(uploadedFile.mimeType().orElse("image/jpeg")))
.build())))
.build();
Interaction interaction =
client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();
System.out.println(interaction.usage().orElse(null));
内嵌数据示例：
Python
# This will only work for SDK newer than 2.0.0
import base64
with open('image.jpg', 'rb') as f:
image_bytes = f.read()
interaction = client.interactions.create(
model="gemini-3.8-flash",
input=[
{"type": "text", "text": "Describe this image"},
{
"type": "image",
"data": base64.b64encode(image_bytes).decode('utf-8'),
"mime_type": "image/jpeg"
}
]
)
print(interaction.usage)
视频 token
Python
# This will only work for SDK newer than 2.0.0
import time
video_file = client.files.upload(file="path/to/video.mp4")
while not video_file.state or video_file.state.name != "ACTIVE":
print("Processing video...")
time.sleep(5)
video_file = client.files.get(name=video_file.name)
# A 60-second video is approximately 100 * 60 = 6,000 tokens
total_tokens = client.models.count_tokens(
model="gemini-3.8-flash",
contents=["Summarize this video", video_file]
)
print(f"Total tokens: {total_tokens}")
# Generate with video
interaction = client.interactions.create(
model="gemini-3.8-flash",
input=[
{"type": "text", "text": "Summarize this video"},
{"type": "video", "uri": video_file.uri, "mime_type": video_file.mime_type}
]
)
print(interaction.usage)
按处理模式划分的视频 token 使用量
视频的 token 使用量取决于处理模式：
| 处理模式 | token 计算 | 典型使用量 |
|---|---|---|
| 静态 （默认） | 默认情况下，每秒约 100 个 token（低分辨率）或每秒约 300 个 token（高分辨率）。所有帧均以 1 FPS 的速率进行采样。 | 可预测，与视频时长成正比。 |
| 智能体 | 因内容复杂性而异。模型仅加载回答提示所需的转写内容和/或帧和/或音频。 | 长视频内容的 token 使用量最多可减少 88%。 |
在智能体处理模式下，一段 1 小时的讲座在静态模式下会使用约 108 万个 token，而在智能体模式下可能会使用约 10.8 万个 token，具体取决于提示和内容。
如需检查请求的实际 token 使用量，请检查 interaction.usage。智能体视频 token 会在以下字段中报告：
- 初始提示 （视频参考 + 用户提示）：
total_input_tokens - 导航思考:
total_thought_tokens - 按需加载的转写内容、帧和音频：
total_tool_use_tokens - 最终回答：
total_output_tokens
音频 token
Python
# This will only work for SDK newer than 2.0.0
audio_file = client.files.upload(file="path/to/audio.mp3")
# A 60-second audio clip is approximately 32 * 60 = 1,920 tokens
total_tokens = client.models.count_tokens(
model="gemini-3.8-flash",
contents=["Transcribe this audio", audio_file]
)
print(f"Total tokens: {total_tokens}")
# Generate with audio
interaction = client.interactions.create(
model="gemini-3.8-flash",
input=[
{"type": "text", "text": "Transcribe this audio"},
{"type": "audio", "uri": audio_file.uri, "mime_type": audio_file.mime_type}
]
)
print(interaction.usage)
统计系统说明 token 数量
系统说明计为输入 token 的一部分：
Python
# This will only work for SDK newer than 2.0.0
interaction = client.interactions.create(
model="gemini-3.8-flash",
input="Hello!",
system_instruction="You are a helpful assistant who speaks like a pirate."
)
# system_instruction tokens included in total_input_tokens
print(f"Input tokens: {interaction.usage.total_input_tokens}")
统计工具 token 数量
工具（函数、代码执行、Google 搜索）也会被统计：
Python
# This will only work for SDK newer than 2.0.0
tools = [
{
"type": "function",
"name": "get_weather",
"description": "Get current weather",
"parameters": {
"type": "object",
"properties": {
"location": {"type": "string"}
}
}
}
]
interaction = client.interactions.create(
model="gemini-3.8-flash",
input="What's the weather in Tokyo?",
tools=tools
)
print(f"Input tokens: {interaction.usage.total_input_tokens}")
print(f"Tool use tokens: {interaction.usage.total_tool_use_tokens}")
上下文窗口
每个 Gemini 模型都有其可以处理的 token 数量上限。上下文窗口定义了输入和输出 token 的总限制。
以编程方式获取上下文窗口大小
Python
# This will only work for SDK newer than 2.0.0
model_info = client.models.get(model="gemini-3.8-flash")
print(f"Input token limit: {model_info.input_token_limit}")
print(f"Output token limit: {model_info.output_token_limit}")
JavaScript
// This will only work for SDK newer than 2.0.0
const modelInfo = await client.models.get({ model: "gemini-3.8-flash" });
console.log(`Input token limit: ${modelInfo.inputTokenLimit}`);
console.log(`Output token limit: ${modelInfo.outputTokenLimit}`);
Java
import com.google.genai.Client;
import com.google.genai.types.Model;
Client client = new Client();
Model modelInfo = client.models.get("gemini-3.8-flash", null);
System.out.println("Input token limit: " + modelInfo.inputTokenLimit().orElse(0));
System.out.println("Output token limit: " + modelInfo.outputTokenLimit().orElse(0));
在模型页面上查找上下文窗口大小。