使用 Count Tokens API

本页面介绍了如何使用 countTokens API 获取提示的token数量。

支持的模型

以下多模态模型支持获取提示token数估计值：

如需详细了解模型版本，请参阅 Gemini 模型版本和生命周期。

获取提示的词元数

您可以使用 Vertex AI API 获取提示的token数估计值。

控制台

如需在Google Cloud 控制台中使用 Vertex AI Studio 获取提示的token数，请执行以下步骤：

在 Google Cloud 控制台的 Vertex AI 部分中，进入 Vertex AI Studio 页面。
进入 Vertex AI Studio
点击打开自由格式模式或打开聊天工具。
系统会在您在 Prompt 窗格中输入内容时计算并显示词元数。其中包含所有输入文件中的词元数。
如需了解更多详情，请点击 <count> 个词元以打开提示词元化器。

如需在文本提示中查看词元（使用不同颜色标记每个词元 ID 的边界进行突出显示），请点击词元 ID 转换为文本。不支持媒体词元。
如需查看词元 ID，请点击词元 ID。
要关闭词元化器工具窗格，请点击 X，或点击窗格外部。

Python

安装

pip install --upgrade google-genai

如需了解详情，请参阅 SDK 参考文档。

设置环境变量以将 Gen AI SDK 与 Vertex AI 搭配使用：

# Replace the `GOOGLE_CLOUD_PROJECT` and `GOOGLE_CLOUD_LOCATION` values # with appropriate values for your project. export GOOGLE_CLOUD_PROJECT=GOOGLE_CLOUD_PROJECT export GOOGLE_CLOUD_LOCATION=global export GOOGLE_GENAI_USE_VERTEXAI=True

from google import genai from google.genai.types import HttpOptions  client = genai.Client(http_options=HttpOptions(api_version="v1")) response = client.models.count_tokens(     model="gemini-2.5-flash",     contents="What's the highest mountain in Africa?", ) print(response) # Example output: # total_tokens=9 # cached_content_token_count=None

Go

了解如何安装或更新 Go。

如需了解详情，请参阅 SDK 参考文档。

设置环境变量以将 Gen AI SDK 与 Vertex AI 搭配使用：

# Replace the `GOOGLE_CLOUD_PROJECT` and `GOOGLE_CLOUD_LOCATION` values # with appropriate values for your project. export GOOGLE_CLOUD_PROJECT=GOOGLE_CLOUD_PROJECT export GOOGLE_CLOUD_LOCATION=global export GOOGLE_GENAI_USE_VERTEXAI=True

import ( 	"context" 	"fmt" 	"io"  	genai "google.golang.org/genai" )  // countWithTxt shows how to count tokens with text input. func countWithTxt(w io.Writer) error { 	ctx := context.Background()  	client, err := genai.NewClient(ctx, &genai.ClientConfig{ 		HTTPOptions: genai.HTTPOptions{APIVersion: "v1"}, 	}) 	if err != nil { 		return fmt.Errorf("failed to create genai client: %w", err) 	}  	modelName := "gemini-2.5-flash" 	contents := []*genai.Content{ 		{Parts: []*genai.Part{ 			{Text: "What's the highest mountain in Africa?"}, 		}}, 	}  	resp, err := client.Models.CountTokens(ctx, modelName, contents, nil) 	if err != nil { 		return fmt.Errorf("failed to generate content: %w", err) 	}  	fmt.Fprintf(w, "Total: %d\nCached: %d\n", resp.TotalTokens, resp.CachedContentTokenCount)  	// Example response: 	// Total: 9 	// Cached: 0  	return nil }

Node.js

安装

npm install @google/genai

如需了解详情，请参阅 SDK 参考文档。

设置环境变量以将 Gen AI SDK 与 Vertex AI 搭配使用：

# Replace the `GOOGLE_CLOUD_PROJECT` and `GOOGLE_CLOUD_LOCATION` values # with appropriate values for your project. export GOOGLE_CLOUD_PROJECT=GOOGLE_CLOUD_PROJECT export GOOGLE_CLOUD_LOCATION=global export GOOGLE_GENAI_USE_VERTEXAI=True

const {GoogleGenAI} = require('@google/genai');  const GOOGLE_CLOUD_PROJECT = process.env.GOOGLE_CLOUD_PROJECT; const GOOGLE_CLOUD_LOCATION = process.env.GOOGLE_CLOUD_LOCATION || 'global';  async function countTokens(   projectId = GOOGLE_CLOUD_PROJECT,   location = GOOGLE_CLOUD_LOCATION ) {   const client = new GoogleGenAI({     vertexai: true,     project: projectId,     location: location,   });    const response = await client.models.countTokens({     model: 'gemini-2.5-flash',     contents: 'What is the highest mountain in Africa?',   });    console.log(response);    return response.totalTokens; }

Java

了解如何安装或更新 Java。

如需了解详情，请参阅 SDK 参考文档。

设置环境变量以将 Gen AI SDK 与 Vertex AI 搭配使用：

# Replace the `GOOGLE_CLOUD_PROJECT` and `GOOGLE_CLOUD_LOCATION` values # with appropriate values for your project. export GOOGLE_CLOUD_PROJECT=GOOGLE_CLOUD_PROJECT export GOOGLE_CLOUD_LOCATION=global export GOOGLE_GENAI_USE_VERTEXAI=True

 import com.google.genai.Client; import com.google.genai.types.CountTokensResponse; import com.google.genai.types.HttpOptions; import java.util.Optional;  public class CountTokensWithText {    public static void main(String[] args) {     // TODO(developer): Replace these variables before running the sample.     String modelId = "gemini-2.5-flash";     countTokens(modelId);   }    // Counts tokens with text input   public static Optional<Integer> countTokens(String modelId) {     // Initialize client that will be used to send requests. This client only needs to be created     // once, and can be reused for multiple requests.     try (Client client =         Client.builder()             .location("global")             .vertexAI(true)             .httpOptions(HttpOptions.builder().apiVersion("v1").build())             .build()) {        CountTokensResponse response =           client.models.countTokens(modelId, "What's the highest mountain in Africa?", null);        System.out.print(response);       // Example response:       // CountTokensResponse{totalTokens=Optional[9], cachedContentTokenCount=Optional.empty}       return response.totalTokens();     }   } }

REST

如需使用 Vertex AI API 获取提示的token数，请向发布方模型端点发送 POST 请求。

在使用任何请求数据之前，请先进行以下替换：

LOCATION：处理请求的区域。可用的选项包括：
点击即可展开可用区域的部分列表
- us-central1
- us-west4
- northamerica-northeast1
- us-east4
- us-west1
- asia-northeast3
- asia-southeast1
- asia-northeast1
PROJECT_ID：您的项目 ID。
MODEL_ID：您要使用的多模态模型 ID。
ROLE：与内容关联的对话中的角色。即使在单轮应用场景中，也需要指定角色。可接受的值包括：
- USER：指定由您发送的内容。
TEXT：要包含在提示中的文本说明。

HTTP 方法和网址：

POST https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/publishers/google/models/MODEL_ID:countTokens

请求 JSON 正文：

 {   "contents": [{     "role": "ROLE",     "parts": [{       "text": "TEXT"     }]   }] }

如需发送请求，请选择以下方式之一：

curl

注意：以下命令假定您已使用您的用户账号通过运行 gcloud init 或 gcloud auth login 登录 gcloud CLI，或者使用了 Cloud Shell，这会使您自动登录 gcloud CLI。您可以运行 gcloud auth list 来检查当前活跃的账号。

将请求正文保存在名为 request.json 的文件中，然后执行以下命令：

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/publishers/google/models/MODEL_ID:countTokens"

PowerShell

注意：以下命令假定您已使用您的用户账号通过运行 gcloud init 或 gcloud auth login 登录 gcloud CLI。您可以运行 gcloud auth list 来检查当前活跃的账号。

将请求正文保存在名为 request.json 的文件中，然后执行以下命令：

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/publishers/google/models/MODEL_ID:countTokens" | Select-Object -Expand Content

您应该收到类似以下内容的 JSON 响应。

响应

 {   "totalTokens": 31,   "totalBillableCharacters": 96,   "promptTokensDetails": [     {       "modality": "TEXT",       "tokenCount": 31     }   ] }

包含图片或视频的文本的示例：

Python

安装

pip install --upgrade google-genai

如需了解详情，请参阅 SDK 参考文档。

设置环境变量以将 Gen AI SDK 与 Vertex AI 搭配使用：

# Replace the `GOOGLE_CLOUD_PROJECT` and `GOOGLE_CLOUD_LOCATION` values # with appropriate values for your project. export GOOGLE_CLOUD_PROJECT=GOOGLE_CLOUD_PROJECT export GOOGLE_CLOUD_LOCATION=global export GOOGLE_GENAI_USE_VERTEXAI=True

from google import genai from google.genai.types import HttpOptions, Part  client = genai.Client(http_options=HttpOptions(api_version="v1"))  contents = [     Part.from_uri(         file_uri="gs://cloud-samples-data/generative-ai/video/pixel8.mp4",         mime_type="video/mp4",     ),     "Provide a description of the video.", ]  response = client.models.count_tokens(     model="gemini-2.5-flash",     contents=contents, ) print(response) # Example output: # total_tokens=16252 cached_content_token_count=None

Go

了解如何安装或更新 Go。

如需了解详情，请参阅 SDK 参考文档。

设置环境变量以将 Gen AI SDK 与 Vertex AI 搭配使用：

# Replace the `GOOGLE_CLOUD_PROJECT` and `GOOGLE_CLOUD_LOCATION` values # with appropriate values for your project. export GOOGLE_CLOUD_PROJECT=GOOGLE_CLOUD_PROJECT export GOOGLE_CLOUD_LOCATION=global export GOOGLE_GENAI_USE_VERTEXAI=True

import ( 	"context" 	"fmt" 	"io"  	genai "google.golang.org/genai" )  // countWithTxtAndVid shows how to count tokens with text and video inputs. func countWithTxtAndVid(w io.Writer) error { 	ctx := context.Background()  	client, err := genai.NewClient(ctx, &genai.ClientConfig{ 		HTTPOptions: genai.HTTPOptions{APIVersion: "v1"}, 	}) 	if err != nil { 		return fmt.Errorf("failed to create genai client: %w", err) 	}  	modelName := "gemini-2.5-flash" 	contents := []*genai.Content{ 		{Parts: []*genai.Part{ 			{Text: "Provide a description of the video."}, 			{FileData: &genai.FileData{ 				FileURI:  "gs://cloud-samples-data/generative-ai/video/pixel8.mp4", 				MIMEType: "video/mp4", 			}}, 		}, 			Role: "user"}, 	}  	resp, err := client.Models.CountTokens(ctx, modelName, contents, nil) 	if err != nil { 		return fmt.Errorf("failed to generate content: %w", err) 	}  	fmt.Fprintf(w, "Total: %d\nCached: %d\n", resp.TotalTokens, resp.CachedContentTokenCount)  	// Example response: 	// Total: 16252 	// Cached: 0  	return nil }

Node.js

安装

npm install @google/genai

如需了解详情，请参阅 SDK 参考文档。

设置环境变量以将 Gen AI SDK 与 Vertex AI 搭配使用：

# Replace the `GOOGLE_CLOUD_PROJECT` and `GOOGLE_CLOUD_LOCATION` values # with appropriate values for your project. export GOOGLE_CLOUD_PROJECT=GOOGLE_CLOUD_PROJECT export GOOGLE_CLOUD_LOCATION=global export GOOGLE_GENAI_USE_VERTEXAI=True

const {GoogleGenAI} = require('@google/genai');  const GOOGLE_CLOUD_PROJECT = process.env.GOOGLE_CLOUD_PROJECT; const GOOGLE_CLOUD_LOCATION = process.env.GOOGLE_CLOUD_LOCATION || 'global';  async function countTokens(   projectId = GOOGLE_CLOUD_PROJECT,   location = GOOGLE_CLOUD_LOCATION ) {   const client = new GoogleGenAI({     vertexai: true,     project: projectId,     location: location,   });    const video = {     fileData: {       fileUri: 'gs://cloud-samples-data/generative-ai/video/pixel8.mp4',       mimeType: 'video/mp4',     },   };    const response = await client.models.countTokens({     model: 'gemini-2.5-flash',     contents: [video, 'Provide a description of the video.'],   });    console.log(response);    return response.totalTokens; }

Java

了解如何安装或更新 Java。

如需了解详情，请参阅 SDK 参考文档。

设置环境变量以将 Gen AI SDK 与 Vertex AI 搭配使用：

# Replace the `GOOGLE_CLOUD_PROJECT` and `GOOGLE_CLOUD_LOCATION` values # with appropriate values for your project. export GOOGLE_CLOUD_PROJECT=GOOGLE_CLOUD_PROJECT export GOOGLE_CLOUD_LOCATION=global export GOOGLE_GENAI_USE_VERTEXAI=True

 import com.google.genai.Client; import com.google.genai.types.Content; import com.google.genai.types.CountTokensResponse; import com.google.genai.types.HttpOptions; import com.google.genai.types.Part; import java.util.List; import java.util.Optional;  public class CountTokensWithTextAndVideo {    public static void main(String[] args) {     // TODO(developer): Replace these variables before running the sample.     String modelId = "gemini-2.5-flash";     countTokens(modelId);   }    // Counts tokens with text and video inputs   public static Optional<Integer> countTokens(String modelId) {     // Initialize client that will be used to send requests. This client only needs to be created     // once, and can be reused for multiple requests.     try (Client client =         Client.builder()             .location("global")             .vertexAI(true)             .httpOptions(HttpOptions.builder().apiVersion("v1").build())             .build()) {        Content content =           Content.fromParts(               Part.fromText("Provide a description of this video"),               Part.fromUri("gs://cloud-samples-data/generative-ai/video/pixel8.mp4", "video/mp4"));        CountTokensResponse response = client.models.countTokens(modelId, List.of(content), null);        System.out.print(response);       // Example response:       // CountTokensResponse{totalTokens=Optional[16707], cachedContentTokenCount=Optional.empty}       return response.totalTokens();     }   } }

REST

如需使用 Vertex AI API 获取提示的token数，请向发布方模型端点发送 POST 请求。

MODEL_ID="gemini-2.5-flash" PROJECT_ID="my-project" TEXT="Provide a summary with about two sentences for the following article." REGION="us-central1"  curl \ -X POST \ -H "Authorization: Bearer $(gcloud auth print-access-token)" \ -H "Content-Type: application/json" \ https://${REGION}-aiplatform.googleapis.com/v1/projects/${PROJECT_ID}/locations/${REGION}/publishers/google/models/${MODEL_ID}:countTokens -d \ $'{     "contents": [{       "role": "user",       "parts": [         {           "file_data": {             "file_uri": "gs://cloud-samples-data/generative-ai/video/pixel8.mp4",             "mime_type": "video/mp4"           }         },         {           "text": "'"$TEXT"'"         }]     }]  }'

价格和配额

使用 CountTokens API 无需付费或配额限制。CountTokens API 的配额上限为每分钟 3000 个请求。

后续步骤

了解如何使用 Vertex AI SDK for Python 列出和统计token（预览版）
了解如何发送对话提示和生成文本