Gemini API：关于 Token 的一切

本教程深入讲解 Gemini API 中 token 的概念、计算方式及实际应用。通过交互式示例，开发者将学会使用 count_tokens 端点估算文本和多模态输入的 token 数，理解上下文窗口限制，并掌握通过 usage 字段监控实际消耗的方法。内容涵盖文本、图像、音频等模态的 token 计算规则，以及 Files API 的使用。教程还提供了环境配置、代码解析和常见问题排查，帮助开发者优化 API 调用成本与性能。

技术背景

在大型语言模型（LLM）的应用中，token 是模型处理文本的基本单位，直接影响 API 的计费、上下文窗口限制和响应质量。Gemini API 作为 Google 提供的多模态生成模型接口，其 token 机制与传统的字符或单词计数不同，理解 token 的生成规则和计算方式对于控制成本、优化提示词和避免超出上下文限制至关重要。本教程面向有编程基础的开发者，旨在通过实践掌握 Gemini API 的 token 管理。

核心原理

Token 是模型词汇表中的最小单元，可以是字符、子词或整个单词。Gemini 模型使用子词分词算法，平均每个 token 约 4 个字符，100 个 token 约对应 60-80 个英文单词。模型具有以 token 衡量的上下文窗口，分为输入和输出限制。API 提供 count_tokens 端点，可预先计算请求的 token 数，而实际调用后可通过 usage 字段获取精确计数。多模态输入（如图像、音频）按固定规则转换：图像按固定 token 数（与尺寸无关），音频按每秒约 32 个 token 计算。

架构分析

教程采用客户端-服务器架构，通过 Python SDK（google-genai）与 Gemini API 交互。核心组件包括：1) 客户端初始化（genai.Client），使用 API 密钥认证；2) 模型信息查询（client.models.get），获取上下文窗口限制；3) token 计数端点（client.models.count_tokens），支持文本和多模态输入；4) 交互式生成（client.interactions.create），返回包含 usage 元数据的响应。设计上，SDK 统一了不同模态的输入处理，通过 types.Part 封装文本、文件 URI 等，简化了多模态请求的构建。

完整实战教程

##### 版权所有 2026 Google LLC。

# @title Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# https://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.

Gemini API：关于 Token 的一切

理解 token 是使用 Gemini API 的核心。本指南将交互式地介绍什么是 token，以及它们在 Gemini API 中如何使用。

关于 token

LLM 会将输入和输出分解为比单词更小、但比单个字符或码点更大的粒度。

这些 token 可以是单个字符（如 z），也可以是整个单词（如 the）。长单词可能会被拆分成多个 token。模型使用的所有 token 的集合称为词汇表，将文本分解为 token 的过程称为分词。

对于 Gemini 模型，一个 token 大约相当于 4 个字符。100 个 token 大约对应 60-80 个英文单词。

当启用计费时，付费请求的价格由输入和输出 token 的数量控制，因此了解如何计算 token 数量非常重要。

注意： 本笔记本使用 Interactions API，这是与 Gemini 模型交互的最新方式。正在寻找 generateContent 版本？请查看 归档分支。

设置

安装 SDK

从 PyPI 安装 SDK。

%pip install -U -q "google-genai>=2.9.0"  # 2.0 for Interactions API

设置你的 API 密钥

要运行以下单元格，你的 API 密钥必须存储在名为 GEMINI_API_KEY 的 Colab Secret 中。如果你还没有 API 密钥，或者不确定如何创建 Colab Secret，请参阅 身份验证 获取详细指南。

from google.colab import userdata

GEMINI_API_KEY = userdata.get('GEMINI_API_KEY')

初始化 SDK 客户端

使用新版 SDK，你现在只需使用 API 密钥（或如果使用 Vertex AI 则使用 OAuth）初始化一个客户端即可。模型现在在每次调用中设置。

from google import genai

client = genai.Client(api_key=GEMINI_API_KEY)

Gemini API 中的 Tokens

上下文窗口

通过 Gemini API 提供的模型具有以 token 衡量的上下文窗口。这些定义了您可以提供的输入量以及模型可以生成的输出量，两者合称为“上下文窗口”。此信息可直接通过 API 和 模型 文档获取。

在此示例中，您可以看到 gemini-3.7-flash 模型具有 1M token 的上下文窗口。如果您需要更多，Pro 模型具有更大的 2M token 上下文窗口。

MODEL_ID = "gemini-3.7-flash"

model_info = client.models.get(model=MODEL_ID)

print("Context window:",model_info.input_token_limit, "tokens")
print("Max output window:",model_info.output_token_limit, "tokens")

计算令牌数

API 提供了一个端点用于计算请求中的令牌数：client.models.count_tokens。你传入与 client.models.interactions.create 相同的参数，服务将返回该请求中的令牌数。

选择您在本指南中要使用的模型：

MODEL_ID = "gemini-3.7-flash" # @param ["gemini-3.1-pro-preview", "gemini-3.7-flash", "gemini-3.5-flash-lite", "gemini-2.5-pro"] {"allow-input":true, isTemplate: true}

文本令牌

response = client.models.count_tokens(
    model=MODEL_ID,
    contents="What's the highest mountain in Africa?",
)
print("Prompt tokens:",response.total_tokens)

当你调用 client.interactions.create 时，响应对象中会包含一个 usage 字段，其中包含令牌计数信息。

interaction = client.interactions.create(
    model=MODEL_ID,
    input="The quick brown fox jumps over the lazy dog."
)
print(interaction.steps[-1].content[0].text)

# Note: The exact field names may differ in Interactions API
# Check interaction.usage for token information
print(interaction.usage)

如果你使用了上下文缓存，缓存 token 的数量会在 response.usage_metadata.cached_content_token_count 中显示。

多模态令牌

所有输入到 API 的内容都会被令牌化，包括图像或其他非文本模态。

图像被视为固定大小，因此无论其显示尺寸或文件大小如何，它们都会消耗固定数量的令牌。

视频和音频文件按固定的每秒速率转换为令牌。

当前的速率和令牌大小可以在文档中找到。

内联内容

你可以直接通过 URL 传递媒体：

from google.genai import types

response = client.models.count_tokens(
    model=MODEL_ID,
    contents=[
        types.Part(
            file_data=types.FileData(
                file_uri="https://storage.googleapis.com/generativeai-downloads/images/organ.jpg",
                mime_type="image/jpeg",
            )
        )
    ],
)

print("Prompt with image tokens:", response.total_tokens)

你可以尝试使用不同的图像，并且应该总是得到相同数量的令牌，这与它们的显示或文件大小无关。请注意，似乎会额外添加一个令牌，代表空提示。

Files API

如果你通过 Files API 上传提示词的部分内容，模型看到的 token 是相同的：

from google.genai import types\n\nresponse = client.models.count_tokens(\n    model=MODEL_ID,\n    contents=types.Part.from_uri(\n        file_uri="https://storage.googleapis.com/generativeai-downloads/images/organ.jpg",\n        mime_type="image/jpeg",\n    ),\n)\n\nprint("Prompt with image tokens:", response.total_tokens)

音频和视频分别以每分钟固定数量的token转换为token。

import subprocess\nfrom google.genai import types\n\nurl = "https://storage.googleapis.com/generativeai-downloads/data/State_of_the_Union_Address_30_January_1961.mp3"\n\n# Compute duration programmatically\ncmd = [\n    "ffprobe",\n    "-v",\n    "error",\n    "-show_entries",\n    "format=duration",\n    "-of",\n    "default=noprint_wrappers=1:nokey=1",\n    url,\n]\nduration = float(subprocess.check_output(cmd).decode().strip())\n\nresponse = client.models.count_tokens(\n    model=MODEL_ID,\n    contents=types.Part.from_uri(\n        file_uri=url,\n        mime_type="audio/mp3",\n    ),\n)\n\nprint("Prompt with audio tokens:", response.total_tokens)\nprint("Tokens per second:", response.total_tokens / duration)

如您所见，这大约对应每秒32个音频令牌。

聊天、工具和缓存

目前，统一 SDK 的 count_tokens 方法尚不支持聊天、工具和缓存。本笔记本将在支持时更新。

在此期间，您仍然可以使用响应中的 usage_metadata 来检查调用后使用的令牌。有关示例，请参阅上下文缓存文档。

延伸阅读

有关令牌计数的更多信息，请参阅文档或API参考：

* countTokens REST API参考，

* count_tokens Python API参考。

常见问题

常见错误：1) API 密钥未正确设置，导致认证失败，需确保 GEMINI_API_KEY 环境变量或 Colab Secret 正确配置；2) 模型 ID 拼写错误，导致模型不存在，应参考官方文档；3) 输入超出上下文窗口，导致请求失败，需使用 count_tokens 预检；4) 多模态文件 URI 无效或 mime_type 错误，导致无法加载；5) 音频文件时长计算失败，需确保 ffprobe 已安装。排查方法：检查 API 响应错误信息，使用 print 输出 usage 字段，验证文件 URL 可访问性。

企业应用扩展

生产环境优化：1) 使用上下文缓存减少重复输入的 token 消耗，降低延迟和成本；2) 对于长文档，采用分块处理并利用 count_tokens 估算总 token 数，避免超出限制；3) 监控 usage 字段，建立 token 使用日志，用于成本分析和配额管理；4) 对于多模态应用，优化图像压缩和音频采样率，但注意 token 计算与文件大小无关，主要受内容影响；5) 考虑使用 Vertex AI 环境，利用 OAuth 认证和更细粒度的计费管理。

总结

本教程深入讲解 Gemini API 中 token 的概念、计算方式及实际应用。通过交互式示例，开发者将学会使用 count_tokens 端点估算文本和多模态输入的 token 数，理解上下文窗口限制，并掌握通过 usage 字段监控实际消耗的方法。内容涵盖文本、图像、音频等模态的 token 计算规则，以及 Files API 的使用。教程还提供了环境配置、代码解析和常见问题排查，帮助开发者优化 API 调用成本与性能。

内容来源与验证

继续系统学习

站内还有更多完整实战教程

加入会员，解锁全部教程、完整代码与持续更新内容。

加入会员
查看全部API 与工程实践教程