了解并统计 token 数量
Gemini 和其他生成式 AI 模型会以一种称为“token”的粒度处理输入和输出。
对于 Gemini 模型，一个 token 大致相当于 4 个字符。 100 个 token 大约相当于 60-80 个英文单词。
令牌简介
词元可以是单个字符（例如 z），也可以是整个字词（例如 cat）。长字词会被拆分为多个 token。模型使用的所有 token 的集合称为词汇，将文本拆分为 token 的过程称为 词元化。
启用结算功能后，对 Gemini API 的调用费用部分取决于输入和输出令牌的数量，因此了解如何计算令牌数量会很有帮助。
统计 token 数量
Gemini API 的所有输入和输出内容（包括文本、图片文件和其他非文本模态）都会进行分词。
您可以通过以下方式统计令牌数量：
使用请求的输入调用
count_tokens。返回仅限输入内容中的词元总数。在发送输入之前调用此方法，以检查请求的大小。在互动响应中使用
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-flash-preview",
contents=prompt
)
print("total_tokens:", total_tokens.total_tokens)
# Get usage from interaction
interaction = client.interactions.create(
model="gemini-3-flash-preview",
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-flash-preview",
contents: prompt,
});
console.log(countResponse.totalTokens);
// Get usage from interaction
const interaction = await client.interactions.create({
model: "gemini-3-flash-preview",
input: prompt,
});
console.log(interaction.usage);
REST
# Specifies the API revision to avoid breaking changes when they become default
curl -X POST "https://generativelanguage.googleapis.com/v1beta/models/gemini-3-flash-preview:countTokens" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-H "Content-Type: application/json" \
-H "Api-Revision: 2026-05-20" \
-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-flash-preview",
input="Hi, my name is Bob"
)
# Second interaction continues the conversation
interaction2 = client.interactions.create(
model="gemini-3-flash-preview",
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-flash-preview",
input: "Hi, my name is Bob"
});
// Second interaction continues the conversation
const interaction2 = await client.interactions.create({
model: "gemini-3-flash-preview",
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}`);
统计多模态 token
Gemini API 的所有输入内容（包括图片、视频和音频）都会被分词。 有关分词的关键点：
- 图片：如果图片的两个尺寸均小于或等于 384 像素，则按 258 个 token 计算。较大的图片会被平铺为 768x768 像素的图块，每个图块计为 258 个 token。
- 视频：每秒 263 个 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-flash-preview",
contents=["Tell me about this image", uploaded_file]
)
print(f"Total tokens: {total_tokens}")
# Generate with image
interaction = client.interactions.create(
model="gemini-3-flash-preview",
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-flash-preview",
contents: [
{ text: "Tell me about this image" },
{ fileData: { fileUri: uploadedFile.uri, mimeType: uploadedFile.mimeType } }
]
});
console.log(countResponse.totalTokens);
内嵌数据示例：
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-flash-preview",
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 263 * 60 = 15,780 tokens
total_tokens = client.models.count_tokens(
model="gemini-3-flash-preview",
contents=["Summarize this video", video_file]
)
print(f"Total tokens: {total_tokens}")
# Generate with video
interaction = client.interactions.create(
model="gemini-3-flash-preview",
input=[
{"type": "text", "text": "Summarize this video"},
{"type": "video", "uri": video_file.uri, "mime_type": video_file.mime_type}
]
)
print(interaction.usage)
音频令牌
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-flash-preview",
contents=["Transcribe this audio", audio_file]
)
print(f"Total tokens: {total_tokens}")
# Generate with audio
interaction = client.interactions.create(
model="gemini-3-flash-preview",
input=[
{"type": "text", "text": "Transcribe this audio"},
{"type": "audio", "uri": audio_file.uri, "mime_type": audio_file.mime_type}
]
)
print(interaction.usage)
统计系统指令 token 数量
系统指令计为输入令牌的一部分：
Python
# This will only work for SDK newer than 2.0.0
interaction = client.interactions.create(
model="gemini-3-flash-preview",
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-flash-preview",
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 的总限制。
以编程方式获取上下文窗口大小
Python
# This will only work for SDK newer than 2.0.0
model_info = client.models.get(model="gemini-3-flash-preview")
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-flash-preview" });
console.log(`Input token limit: ${modelInfo.inputTokenLimit}`);
console.log(`Output token limit: ${modelInfo.outputTokenLimit}`);
在模型页面上查找上下文窗口大小。