使用 Count Tokens API

本頁面說明如何使用 countTokens API 取得提示的權杖數量和可計費字元數。

支援的模型

下列多模態模型支援預估提示詞權杖數量：

如要進一步瞭解模型版本，請參閱「Gemini 模型版本和生命週期」。

取得提示的權杖數量

您可以使用 Vertex AI API，估算提示的權杖數量和可計費字元數。

控制台

如要使用Google Cloud 控制台中的 Vertex AI Studio 取得提示的權杖數量，請按照下列步驟操作：

  1. 在 Google Cloud 控制台的 Vertex AI 專區中，前往「Vertex AI Studio」頁面。

    前往 Vertex AI Studio

  2. 按一下「開啟 Freeform」或「開啟對話」。
  3. 在「提示」窗格中輸入內容時，系統會計算並顯示權杖數量。包括任何輸入檔案中的權杖數量。
  4. 如要查看更多詳細資料，請按一下「<count> 個權杖」開啟「提示權杖化工具」。
  • 如要查看文字提示中的詞元，這些詞元會以不同顏色醒目顯示，標示各詞元 ID 的分界，請按一下「詞元 ID 對應文字」。不支援媒體權杖。
  • 如要查看權杖 ID，請按一下「權杖 ID」。

    如要關閉權杖化工具窗格，請按一下「X」X，或按一下窗格外部。

Python

安裝

pip install --upgrade google-genai

詳情請參閱 SDK 參考說明文件。

設定環境變數，透過 Vertex AI 使用 Gen AI SDK： 

# 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=10 # cached_content_token_count=None

Go

瞭解如何安裝或更新 Go。

詳情請參閱 SDK 參考說明文件。

設定環境變數，透過 Vertex AI 使用 Gen AI SDK： 

# 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 參考說明文件。

設定環境變數，透過 Vertex AI 使用 Gen AI SDK： 

# 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 ai = new GoogleGenAI({     vertexai: true,     project: projectId,     location: location,   });    const response = await ai.models.countTokens({     model: 'gemini-2.5-flash',     contents: 'What is the highest mountain in Africa?',   });    console.log(response);    return response.totalTokens; }

Java

瞭解如何安裝或更新 Java。

詳情請參閱 SDK 參考說明文件。

設定環境變數，透過 Vertex AI 使用 Gen AI SDK： 

# 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 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 取得提示的權杖數和可計費字元數，請將 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

將要求主體儲存在名為 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

將要求主體儲存在名為 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 回應。

文字搭配圖片或影片的範例：

Python

安裝

pip install --upgrade google-genai

詳情請參閱 SDK 參考說明文件。

設定環境變數，透過 Vertex AI 使用 Gen AI SDK： 

# 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 參考說明文件。

設定環境變數，透過 Vertex AI 使用 Gen AI SDK： 

# 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 參考說明文件。

設定環境變數，透過 Vertex AI 使用 Gen AI SDK： 

# 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 ai = 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 ai.models.countTokens({     model: 'gemini-2.5-flash',     contents: [video, 'Provide a description of the video.'],   });    console.log(response);    return response.totalTokens; }

Java

瞭解如何安裝或更新 Java。

詳情請參閱 SDK 參考說明文件。

設定環境變數，透過 Vertex AI 使用 Gen AI SDK： 

# 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 取得提示的權杖數和可計費字元數，請將 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 的配額上限為每分鐘 3,000 項要求。

後續步驟