このページは Cloud Translation API によって翻訳されました。

CountTokens API

CountTokens API は、Gemini API にリクエストを送信する前に入力トークンの数を計算します。

CountTokens API を使用して、リクエストがモデルのコンテキストウィンドウを超えないようにし、課金対象の文字またはトークンに基づいて潜在的な費用を見積もります。

CountTokens API では、Gemini API 推論リクエストと同じ contents パラメータを使用できます。

サポートされているモデル

パラメータリスト

このクラスは、role と parts という 2 つの主要なプロパティで構成されています。role プロパティはコンテンツを生成している個人を表し、parts プロパティには複数の要素が含まれます。各要素はメッセージ内のデータセグメントを表します。

パラメータ

パラメータ
`role`	省略可: `string` メッセージを作成するエンティティの ID。文字列を次のいずれかに設定します。 `user`: メッセージが実際のユーザーから送信されたことを示します。たとえば、ユーザーが生成したメッセージなどです。 `model`: メッセージがモデルによって生成されたことを示します。 `model` 値は、マルチターンの会話中にモデルからのメッセージを会話に挿入するために使用されます。マルチターンではない会話の場合、このフィールドは空白のままにするか、未設定のままにできます。
`parts`	`part` 1 つのメッセージを構成する順序付きのパーツのリスト。パーツによって IANA MIME タイプが異なる場合があります。

role

省略可: string

メッセージを作成するエンティティの ID。文字列を次のいずれかに設定します。

user: メッセージが実際のユーザーから送信されたことを示します。たとえば、ユーザーが生成したメッセージなどです。
model: メッセージがモデルによって生成されたことを示します。

model 値は、マルチターンの会話中にモデルからのメッセージを会話に挿入するために使用されます。

マルチターンではない会話の場合、このフィールドは空白のままにするか、未設定のままにできます。

parts

part

1 つのメッセージを構成する順序付きのパーツのリスト。パーツによって IANA MIME タイプが異なる場合があります。

`Part`

マルチパート Content メッセージの一部であるメディアを含むデータ型。

パラメータ

パラメータ
`text`	省略可: `string` テキストプロンプトまたはコードスニペット。
`inline_data`	省略可: `Blob` 未加工バイトのデータがインラインに含まれます。
`file_data`	省略可: `FileData` ファイルに保存されたデータ。

text

省略可: string

テキストプロンプトまたはコードスニペット。

inline_data

省略可: Blob

未加工バイトのデータがインラインに含まれます。

file_data

省略可: FileData

ファイルに保存されたデータ。

`Blob`

コンテンツ blob。可能であれば、元のバイトではなくテキストとして送信します。

パラメータ

パラメータ
`mime_type`	`string` データの IANA MIME タイプ。
`data`	`bytes` 元のバイト。

mime_type

string

データの IANA MIME タイプ。

data

bytes

元のバイト。

`FileData`

URI ベースのデータ。

パラメータ

パラメータ
`mime_type`	`string` データの IANA MIME タイプ。
`file_uri`	`string` データを格納するファイルの Cloud Storage URI。

mime_type

string

データの IANA MIME タイプ。

file_uri

string

データを格納するファイルの Cloud Storage URI。

`system_instruction`

このフィールドは、ユーザーが指定した system_instructions 用です。contents と同じですが、サポートされるコンテンツタイプが限定されています。

パラメータ

パラメータ
`role`	`string` データの IANA MIME タイプ。このフィールドは内部では無視されます。
`parts`	`Part` テキストのみ。ユーザーがモデルに渡す指示。

role

string

データの IANA MIME タイプ。このフィールドは内部では無視されます。

parts

Part

テキストのみ。ユーザーがモデルに渡す指示。

`FunctionDeclaration`

OpenAPI 3.0 仕様で定義されている関数宣言の構造化表現。モデルが JSON 入力を生成できる関数を表します。

パラメータ
`name`	`string` 呼び出す関数の名前。
`description`	省略可: `string` 関数の説明と目的。
`parameters`	省略可: `Schema` 関数のパラメータを OpenAPI JSON スキーマオブジェクト形式（OpenAPI 3.0 仕様）で記述します。
`response`	省略可: `Schema` 関数からの出力を OpenAPI JSON スキーマオブジェクト形式（OpenAPI 3.0 仕様）で記述します。

例

テキストプロンプトからトークン数を取得する

この例では、単一のテキストプロンプトのトークンをカウントします。

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 メソッドと URL:

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 リファレンスドキュメントをご覧ください。

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=9
# 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 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 リファレンスドキュメントをご覧ください。

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.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

リクエストのデータを使用する前に、次のように置き換えます。

LOCATION: リクエストを処理するリージョン。使用できる選択肢は以下のとおりです。
クリックして、利用可能なリージョンの一部を開く
- us-central1
- us-west4
- northamerica-northeast1
- us-east4
- us-west1
- asia-northeast3
- asia-southeast1
- asia-northeast1
PROJECT_ID:
MODEL_ID: 使用するマルチモーダルモデルのモデル ID。
ROLE: コンテンツに関連付けられた会話におけるロール。単一ターンのユースケースでも、ロールの指定が必要です。指定できる値は以下のとおりです。
- USER: 送信するコンテンツを指定します。
TEXT: プロンプトに含める指示のテキスト。
FILE_URI: プロンプトに含めるファイルの URI または URL。指定できる値は以下のとおりです。
- Cloud Storage バケット URI: オブジェクトは一般公開されているか、リクエストを送信するプロジェクトと同じ Google Cloud プロジェクトに存在している必要があります。gemini-2.0-flash と gemini-2.0-flash-lite の場合、サイズの上限は 2 GB です。
- HTTP URL: ファイルの URL は一般公開されている必要があります。リクエストごとに 1 つの動画ファイル、1 つの音声ファイル、最大 10 個の画像ファイルを指定できます。音声ファイル、動画ファイル、ドキュメントのサイズは 15 MB 以下にする必要があります。
- YouTube 動画の URL: YouTube 動画は、 Google Cloud コンソールのログインに使用したアカウントが所有しているか、公開されている必要があります。リクエストごとにサポートされる YouTube 動画の URL は 1 つだけです。
fileURI を指定する場合は、ファイルのメディアタイプ（mimeType）も指定する必要があります。VPC Service Controls が有効になっている場合、fileURI のメディアファイル URL の指定はサポートされていません。
MIME_TYPE: data フィールドまたは fileUri フィールドで指定されたファイルのメディアタイプ。指定できる値は以下のとおりです。
クリックして MIME タイプを開く
- application/pdf
- audio/mpeg
- audio/mp3
- audio/wav
- image/png
- image/jpeg
- image/webp
- text/plain
- video/mov
- video/mpeg
- video/mp4
- video/mpg
- video/avi
- video/wmv
- video/mpegps
- video/flv

HTTP メソッドと URL:

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

リクエストの本文（JSON）:

{
  "contents": [{
    "role": "ROLE",
    "parts": [
      {
        "file_data": {
          "file_uri": "FILE_URI",
          "mime_type": "MIME_TYPE"
        }
      },
      {
        "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 レスポンスが返されます。

レスポンス

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

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 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 リファレンスドキュメントをご覧ください。

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();
    }
  }
}

次のステップ

詳細については、Gemini API をご覧ください。

CountTokens API コレクションでコンテンツを整理 必要に応じて、コンテンツの保存と分類を行います。

サポートされているモデル

パラメータ リスト

Part

Blob

FileData

system_instruction

FunctionDeclaration

例

テキスト プロンプトからトークン数を取得する

REST

curl

PowerShell

レスポンス

Python

インストール

Go

Node.js

インストール

Java

メディア プロンプトからトークン数を取得する

REST

curl

PowerShell

レスポンス

Python

インストール

Go

Node.js

インストール

Java

次のステップ

CountTokens API

パラメータリスト

`Part`

`Blob`

`FileData`

`system_instruction`

`FunctionDeclaration`

テキストプロンプトからトークン数を取得する

メディアプロンプトからトークン数を取得する