Gemini 中文指南
获取 API 密钥 ↗

理解与统计 token

↓ 下载 Markdown

Gemini 和其他生成式 AI 模型以称为“粒度”的粒度处理输入和输出 token.

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

关于token #

token可以是单个字符,例如 z 或整个单词,如 cat。长字被分成几个token。模型使用的所有token的集合称为词汇表,将文本拆分为token的过程称为 代币化.

启用计费后, 呼叫 Gemini API 的费用 部分由输入和输出 token 的数量决定,因此了解如何计算 token 会很有帮助。

您可以尝试在我们的 Colab 中计算 token。

尝试 Colab 笔记本

在 GitHub 上查看笔记本

计数 token #

Gemini API 的所有输入和输出均被标记化,包括文本、图像文件和其他非文本模式。

您可以通过以下方式统计token:

  • 致电 count_tokens 与请求的输入。
    这将返回 token 的总数 仅输入。您可以在将输入发送到模型之前进行此调用,以检查请求的大小。

  • 使用 usage_metadata 属性上的 response 调用后的对象 generate_content.
    这将返回 token 的总数 输入和输出: total_token_count.
    它还分别返回输入和输出的 token 计数: prompt_token_count (输入 token)和 candidates_token_count (输出 token)。

如果您使用的是 思维模型,思考过程中使用的token返回于 thoughts_token_count。如果你正在使用 上下文缓存,缓存的 token 计数将在 cached_content_token_count.

计数文本 token #

如果你打电话 count_tokens 对于纯文本输入,它返回 token 中文本的计数 仅输入 (total_tokens)。您可以在拨打电话之前拨打此电话 generate_content 检查您的请求的大小。

另一种选择是致电 generate_content 然后使用 usage_metadata 属性上的 response 对象获得以下内容:

  • 输入的单独 token 计数(prompt_token_count)、缓存内容(cached_content_token_count)和输出(candidates_token_count)

  • token 计算思维过程(thoughts_token_count)

  • token 总数 输入和输出 (total_token_count)

python
  from google import genai

  client = genai.Client()
  prompt = "The quick brown fox jumps over the lazy dog."

  total_tokens = client.models.count_tokens(
      model="gemini-4-hydrogen", contents=prompt
  )
  print("total_tokens: ", total_tokens)

  response = client.models.generate_content(
      model="gemini-4-hydrogen", contents=prompt
  )

  print(response.usage_metadata)

计数多轮(聊天)token #

如果你打电话 count_tokens 与聊天历史记录一起,它返回聊天中每个角色的文本总数 token (total_tokens).

另一种选择是致电 send_message 然后使用 usage_metadata 属性上的 response 对象获得以下内容:

  • 输入的单独 token 计数(prompt_token_count)、缓存内容(cached_content_token_count)和输出(candidates_token_count)

  • token 计算思维过程(thoughts_token_count)

  • token 总数 输入和输出 (total_token_count)

要了解您的下一个对话轮次有多大,您需要在致电时将其附加到历史记录中 count_tokens.

python
  from google import genai
  from google.genai import types

  client = genai.Client()

  chat = client.chats.create(
      model="gemini-4-hydrogen",
      history=[
          types.Content(
              role="user", parts=[types.Part(text="Hi my name is Bob")]
          ),
          types.Content(role="model", parts=[types.Part(text="Hi Bob!")]),
      ],
  )

  print(
      client.models.count_tokens(
          model="gemini-4-hydrogen", contents=chat.get_history()
      )
  )

  response = chat.send_message(
      message="In one sentence, explain how a computer works to a young child."
  )
  print(response.usage_metadata)

  extra = types.UserContent(
      parts=[
          types.Part(
              text="What is the meaning of life?",
          )
      ]
  )
  history = [*chat.get_history(), extra]
  print(client.models.count_tokens(model="gemini-4-hydrogen", contents=history))

计数多式联运 token #

Gemini API 的所有输入均被标记化,包括文本、图像文件和其他非文本模式。请注意以下有关 Gemini API 处理过程中多模态输入标记化的高级要点:

  • 两个尺寸 <=384 像素的图像输入被计为 258 token。一维或二维较大的图像将根据需要裁剪并缩放为 768x768 像素的图块,每个图块均计为 258 token。

  • 视频和音频文件按以下固定速率转换为 token:视频为每秒 263 token,音频为每秒 32 token。该速率适用于静态处理(默认)。对于智能体处理,token 的用法有所不同。参见 视频 token 按处理模式的使用情况.

媒体决议 #

Gemini 3型号 引入对多模态视觉处理的粒度控制 media_resolution 参数。的 media_resolution 参数决定了 每个输入图像或视频帧分配的 token 的最大数量。 更高的分辨率可以提高模型读取精细文本或识别小细节的能力,但会增加 token 的使用率和延迟。

有关该参数及其如何影响 token 计算的更多详细信息,请参阅 媒体分辨率 指导。

图像文件 #

如果你打电话 count_tokens 对于文本和图像输入,它返回文本和图像的组合 token 计数 仅输入 (total_tokens)。您可以在拨打电话之前拨打此电话 generate_content 检查您的请求的大小。您还可以选择致电 count_tokens 分别在文本和文件上。

另一种选择是致电 generate_content 然后使用 usage_metadata 属性上的 response 对象获得以下内容:

  • 输入的单独 token 计数(prompt_token_count)、缓存内容(cached_content_token_count)和输出(candidates_token_count)

  • token 计算思维过程(thoughts_token_count)

  • token 总数 输入和输出 (total_token_count)

使用从文件 API 上传的图像的示例:

python
  from google import genai

  client = genai.Client()
  prompt = "Tell me about this image"
  your_image_file = client.files.upload(file=media / "organ.jpg")

  print(
      client.models.count_tokens(
          model="gemini-4-hydrogen", contents=[prompt, your_image_file]
      )
  )

  response = client.models.generate_content(
      model="gemini-4-hydrogen", contents=[prompt, your_image_file]
  )
  print(response.usage_metadata)

提供图像作为内联数据的示例:

python
  from google import genai
  import PIL.Image

  client = genai.Client()
  prompt = "Tell me about this image"
  your_image_file = PIL.Image.open(media / "organ.jpg")

  print(
      client.models.count_tokens(
          model="gemini-4-hydrogen", contents=[prompt, your_image_file]
      )
  )

  response = client.models.generate_content(
      model="gemini-4-hydrogen", contents=[prompt, your_image_file]
  )
  print(response.usage_metadata)

视频或音频文件 #

视频的Token计算取决于处理模式:

加工方式采样帧数每秒token数60 年代视频的代币
静止的 (默认)1 FPS(所有帧)~100(默认低分辨率)/~300(高分辨率)~6,000(默认)/~18,000(高)
智能体动态(按需)变量(最多减少 88%)通常为 1,500 至 3,000

有关设置处理模式的详细信息,请参见 智能体视频理解.

音频和视频均按以下固定速率转换为 token:

  • 视频:每秒263 token(静态模式)
  • 音频:每秒 32 token

如果你打电话 count_tokens 对于文本和视频/音频输入,它返回文本和视频/音频文件的组合 token 计数 仅输入 (total_tokens)。您可以在拨打电话之前拨打此电话 generate_content 检查您的请求的大小。您还可以选择致电 count_tokens 分别在文本和文件上。

另一种选择是致电 generate_content 然后使用 usage_metadata 属性上的 response 对象检查 token 使用情况。在 UsageMetadata、智能体视频 token 在以下字段中报告:

  • 初始提示 (视频参考+用户提示): prompt_token_count
  • 导航思维: thoughts_token_count
  • 按需加载文字记录、帧和音频: tool_use_prompt_token_count
  • 最终答案: candidates_token_count
js
  import { GoogleGenAI } from '@google/genai';

  const ai = new GoogleGenAI({});
  const prompt = "The quick brown fox jumps over the lazy dog.";

  async function main() {
    const countTokensResponse = await ai.models.countTokens({
      model: "gemini-4-hydrogen",
      contents: prompt,
    });
    console.log(countTokensResponse.totalTokens);

    const generateResponse = await ai.models.generateContent({
      model: "gemini-4-hydrogen",
      contents: prompt,
    });
    console.log(generateResponse.usageMetadata);
  }

  await main();

计思token #

当你打开思维时,响应定价是输出 token 和思维 token 的总和。您可以从以下位置检索生成思维 token 的总数: thoughtsTokenCount 字段(或 SDK 等效字段)。

js
  import { GoogleGenAI } from '@google/genai';

  const ai = new GoogleGenAI({});
  const prompt = "The quick brown fox jumps over the lazy dog.";

  async function main() {
    const countTokensResponse = await ai.models.countTokens({
      model: "gemini-4-hydrogen",
      contents: prompt,
    });
    console.log(countTokensResponse.totalTokens);

    const generateResponse = await ai.models.generateContent({
      model: "gemini-4-hydrogen",
      contents: prompt,
    });
    console.log(generateResponse.usageMetadata);
  }

  await main();

思维模型产生完整的想法,提高最终响应的质量,然后输出 摘要 提供对思维过程的洞察。因此,API 的定价基于模型生成的完整想法 token 以创建摘要,即使 API 仅输出摘要。

您可以了解有关如何配置思维的更多信息 Gemini 思考能力 指导。

上下文窗口 #

通过 Gemini API 提供的模型具有在 token 中测量的上下文窗口。 上下文窗口定义您可以提供多少输入以及模型可以生成多少输出。您可以通过调用来确定上下文窗口的大小 models.get 终点 或者通过查看 模型文档.

  • Gemini 4 型号(gemini-4-carbon, gemini-4-argon, 和 gemini-4-hydrogen): 共享单个 1M-token 上下文窗口 (1,048,576 token)跨越输入、思维和输出 token。单个请求的上限为 65,536 输出 token 开启 gemini-4-hydrogen (流媒体和非流媒体)和流媒体(streamGenerateContent)对于 gemini-4-carbon 和 gemini-4-argon (32,768 直接非流式输出 token generateContent 对于碳和氩),或者您可以生成最多 1,048,576 token 使用 长解码。如果你输入token加上 max_output_tokens 超过 1,048,576 token 时,API 自动将输出限制限制为上下文窗口中的剩余空间(1,048,576 减去您的输入 token)。
  • Gemini 3 和 2.5 型号: 使用单独的输入(1,048,576 token)和输出(65,536 token) 预算。
js
  import { GoogleGenAI } from '@google/genai';

  const ai = new GoogleGenAI({});
  const prompt = "The quick brown fox jumps over the lazy dog.";

  async function main() {
    const countTokensResponse = await ai.models.countTokens({
      model: "gemini-4-hydrogen",
      contents: prompt,
    });
    console.log(countTokensResponse.totalTokens);

    const generateResponse = await ai.models.generateContent({
      model: "gemini-4-hydrogen",
      contents: prompt,
    });
    console.log(generateResponse.usageMetadata);
  }

  await main();

搜索标题、API 名称或正文内容