统计 Gemini 模型的词元数

Gemini 模型以“token”为单位处理输入和输出。

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

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

每个模型具有在提示和响应中可以处理的词元数上限。了解提示的 token 数量有助于您了解是否已超出此限制。此外，请求的费用部分取决于输入和输出 token 的数量，因此了解如何统计 token 数量会很有帮助。

支持的模型

  • gemini-4-argon
  • gemini-3.8-flash（以及旧版 gemini-3.7-flash、gemini-3.6-flash 和 gemini-3.5-flash）
  • gemini-3.5-flash-lite（以及旧版 gemini-3.1-flash-lite）
  • gemini-nano-banana-2.1 (Nano Banana 2.1)
  • gemini-3.1-flash-image (Nano Banana 2)
  • gemini-3.1-flash-lite-image (Nano Banana 2 Lite)
  • gemini-3-pro-image (Nano Banana Pro)
  • gemini-3.1-flash-tts-preview

gemini-3.1-pro-preview 以及通用和图片生成 Gemini 2.5 模型（已弃用）也支持此功能。

用于统计 token 数量的选项

Gemini API 的所有输入和输出都会被词元化，包括文本、图片文件和其他非文本模态。以下是计算 token 的选项：

仅检查请求的词元数（在将请求发送到模型之前）。
在将请求发送到模型之前，使用请求的输入调用 countTokens。此操作会返回：
  • total_tokens：仅输入的 token 数量
检查请求和回答的 token 数量。
访问响应对象上的 usageMetadata 属性。其中包括：
  • prompt_token_count：仅输入的 token 数量
  • candidates_token_count：仅输出内容的 token 数量（不包括思考 token）
  • thoughts_token_count：用于生成回答的所有思考 token 的数量
  • total_token_count：输入和输出的 token 总数（包括所有思考 token）

流式传输输出时，usageMetadata 属性仅出现在流的最后一个分块中。对于中间分块，此值为 nil。

请注意以下有关上述选项的事项：

  • 它们不会统计输入图片的数量，也不会统计视频或音频输入文件的秒数。不过，每种模态的 token 数量都与这些值相关。
  • 输入 token 数量包括提示（文本和任何输入文件）以及任何系统指令和工具。
  • 输出 token 数量不包含任何思考 token，这些 token 会在单独的字段中提供。
  • 请参阅本页面后面部分中针对每种请求类型的其他信息。
  • Gemini Live API 模型不支持 countTokens。此外，Firebase AI Logic 尚不支持 Live API 模型回答中的 usageMetadata 属性，但很快就会支持！

这些选项的价格

  • 调用 countTokens：调用 countTokens（Count Tokens API）不收取任何费用。Count Tokens API 的最大配额为每分钟 3000 个请求 (RPM)。

  • 使用 usageMetadata 属性：此属性始终作为响应的一部分返回，不会产生任何 token 或费用。

其他信息

以下是处理特定类型请求时的一些额外信息。

统计文本输入 token 数

没有其他信息。

统计多轮（对话）token 数量

使用聊天功能时，请注意以下有关调用 countTokens 的事项：

  • 如果您使用聊天记录调用 countTokens，它会返回聊天中两个角色 (total_tokens) 的总 token 数量。
  • 如需了解下一个对话轮次的大小，您需要在调用 countTokens 时将其附加到历史记录中。

统计多模态输入 token 数量

请注意以下关于使用多模态输入统计 token 的事项：

  • 您可以选择分别对文本和文件调用 countTokens。
  • 对于这两种 token 计数选项，无论您是以内嵌数据形式还是使用其网址提供文件，都会获得相同的 token 计数。

图片输入文件

图片输入文件会根据其尺寸转换为 token：

  • 两个维度均小于或等于 384 像素的图片输入：每张图片计为 258 个 token。
  • 一个或两个维度较大的图片输入：每张图片都会根据需要剪裁并缩放为 768x768 像素的图块，然后每个图块计为 258 个 token。

视频和音频输入文件

视频和音频输入文件会按以下固定速率转换为 token：

  • 视频：每秒按 263 个 token 计算
  • 音频：每秒 32 个 token

文档（例如 PDF）输入文件

PDF 输入文件被视为图片，因此 PDF 文件的每页都会以与图片相同的方式进行词元化。