トークンを理解してカウントする

Gemini などの生成 AI モデルは、入力と出力をトークンという粒度で処理します。

Gemini モデルの場合、1 個のトークンは約 4 文字に相当します。100 個のトークンは、約 60 ~ 80 ワード(英語)に相当します。

トークンについて

トークンは、z などの単一の文字、cat などの単語全体にすることができます。長い単語は複数のトークンに分割されます。モデルで使用されるすべてのトークンのセットを語彙と呼び、テキストをトークンに分割するプロセスをトークン化と呼びます。

課金が有効になっている場合、Gemini API の呼び出し費用は、入力トークンと出力トークンの数によって決まります。そのため、トークンのカウント方法を知っておくと便利です。


トークンのカウント

Gemini API への入力と Gemini API からの出力はすべてトークン化されます。これには、テキスト、画像ファイル、その他のテキスト以外のモダリティが含まれます。

トークンは次の方法でカウントできます。

  • リクエストの入力を使用して countTokens を呼び出します。
    : 入力のみのトークンの合計数を返します。この呼び出しは、リクエストのサイズを確認するために、入力をモデルに送信する前に行うことができます。

  • generate_content を呼び出した後、response オブジェクトの usageMetadata 属性を使用します。
    : 入力と出力の両方のトークンの合計数を返します(totalTokenCount)。
    また、入力トークンと出力トークンのトークン数を別々に返します。promptTokenCount(入力トークン)と candidatesTokenCount(出力トークン)です。コンテキスト キャッシュを使用している場合、キャッシュに保存されたトークンの数は cachedContentTokenCount に含まれます。

    2.5 などの思考モデルを使用している場合、思考プロセスで使用されるトークンは thoughtsTokenCount で返されます。

テキスト トークンをカウントする

テキストのみの入力で countTokens を呼び出すと、入力のみのテキストのトークン数(totalTokens)が返されます。この呼び出しは、generateContent を呼び出してリクエストのサイズを確認する前に行うことができます。

別の方法としては、generateContent を呼び出し、response オブジェクトの usageMetadata 属性を使用して次の情報を取得します。

  • 入力(promptTokenCount)、キャッシュに保存されたコンテンツ(cachedContentTokenCount)、出力(candidatesTokenCount)のトークン数の内訳
  • 思考プロセスのトークン数(thoughtsTokenCount
  • 入力と出力の両方のトークンの合計数(totalTokenCount
// Make sure to include the following import:
// import {GoogleGenAI} from '@google/genai';
const ai = new GoogleGenAI({ apiKey: process.env.GEMINI_API_KEY });
const prompt = "The quick brown fox jumps over the lazy dog.";
const countTokensResponse = await ai.models.countTokens({
  model: "gemini-2.0-flash",
  contents: prompt,
});
console.log(countTokensResponse.totalTokens);

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

マルチターン(チャット)トークンをカウントする

チャット履歴を指定して countTokens を呼び出すと、チャット内の各ロールのテキストの合計トークン数(totalTokens)が返されます。

別の方法としては、sendMessage を呼び出し、response オブジェクトの usageMetadata 属性を使用して次の情報を取得します。

  • 入力(promptTokenCount)、キャッシュに保存されたコンテンツ(cachedContentTokenCount)、出力(candidatesTokenCount)のトークン数の内訳
  • 思考プロセスのトークン数(thoughtsTokenCount
  • 入力と出力の両方のトークンの合計数(totalTokenCount

次の会話ターンのサイズを把握するには、countTokens を呼び出すときに履歴に追加する必要があります。

// Make sure to include the following import:
// import {GoogleGenAI} from '@google/genai';
const ai = new GoogleGenAI({ apiKey: process.env.GEMINI_API_KEY });
// Initial chat history.
const history = [
  { role: "user", parts: [{ text: "Hi my name is Bob" }] },
  { role: "model", parts: [{ text: "Hi Bob!" }] },
];
const chat = ai.chats.create({
  model: "gemini-2.0-flash",
  history: history,
});

// Count tokens for the current chat history.
const countTokensResponse = await ai.models.countTokens({
  model: "gemini-2.0-flash",
  contents: chat.getHistory(),
});
console.log(countTokensResponse.totalTokens);

const chatResponse = await chat.sendMessage({
  message: "In one sentence, explain how a computer works to a young child.",
});
console.log(chatResponse.usageMetadata);

// Add an extra user message to the history.
const extraMessage = {
  role: "user",
  parts: [{ text: "What is the meaning of life?" }],
};
const combinedHistory = chat.getHistory();
combinedHistory.push(extraMessage);
const combinedCountTokensResponse = await ai.models.countTokens({
  model: "gemini-2.0-flash",
  contents: combinedHistory,
});
console.log(
  "Combined history token count:",
  combinedCountTokensResponse.totalTokens,
);

マルチモーダル トークンをカウントする

Gemini API への入力はすべてトークン化されます。これには、テキスト、画像ファイル、その他のテキスト以外のモダリティが含まれます。Gemini API による処理中のマルチモーダル入力のトークン化に関する重要なポイントは次のとおりです。

  • Gemini 2.0 では、両方の寸法が 384 ピクセル以下の画像入力は 258 個のトークンとしてカウントされます。1 つまたは両方の寸法が大きい画像は、必要に応じて 768x768 ピクセルのタイルに切り抜かれ、スケーリングされます。各タイルは 258 個のトークンとしてカウントされます。Gemini 2.0 より前は、画像は固定の 258 個のトークンを使用していました。

  • 動画ファイルと音声ファイルは、次の固定レートでトークンに変換されます。動画は 1 秒あたり 263 トークン、音声は 1 秒あたり 32 トークン。

メディアの解像度

Gemini 3 Pro Preview では、media_resolution パラメータを使用して、マルチモーダル ビジョン処理をきめ細かく制御できます。media_resolution パラメータは、入力画像または動画フレームごとに割り当てられるトークンの最大数を決定します。解像度が高いほど、モデルが細かいテキストを読み取ったり、小さな詳細を識別する能力が向上しますが、トークンの使用量とレイテンシが増加します。

パラメータとそのトークン計算への影響について詳しくは、メディアの解像度ガイドをご覧ください。

画像ファイル

テキストと画像の入力を使用して countTokens を呼び出すと、入力のみのテキストと画像の結合トークン数(totalTokens)が返されます。この呼び出しは、generateContent を呼び出してリクエストのサイズを確認する前に行うことができます。必要に応じて、テキストとファイルに対して countTokens を個別に呼び出すこともできます。

別の方法としては、generateContent を呼び出し、response オブジェクトの usageMetadata 属性を使用して次の情報を取得します。

  • 入力(promptTokenCount)、キャッシュに保存されたコンテンツ(cachedContentTokenCount)、出力(candidatesTokenCount)のトークン数の内訳
  • 思考プロセスのトークン数(thoughtsTokenCount
  • 入力と出力の両方のトークンの合計数(totalTokenCount

File API からアップロードされた画像を使用する例:

// Make sure to include the following import:
// import {GoogleGenAI} from '@google/genai';
const ai = new GoogleGenAI({ apiKey: process.env.GEMINI_API_KEY });
const prompt = "Tell me about this image";
const organ = await ai.files.upload({
  file: path.join(media, "organ.jpg"),
  config: { mimeType: "image/jpeg" },
});

const countTokensResponse = await ai.models.countTokens({
  model: "gemini-2.0-flash",
  contents: createUserContent([
    prompt,
    createPartFromUri(organ.uri, organ.mimeType),
  ]),
});
console.log(countTokensResponse.totalTokens);

const generateResponse = await ai.models.generateContent({
  model: "gemini-2.0-flash",
  contents: createUserContent([
    prompt,
    createPartFromUri(organ.uri, organ.mimeType),
  ]),
});
console.log(generateResponse.usageMetadata);

画像をインライン データとして提供する例:

// Make sure to include the following import:
// import {GoogleGenAI} from '@google/genai';
const ai = new GoogleGenAI({ apiKey: process.env.GEMINI_API_KEY });
const prompt = "Tell me about this image";
const imageBuffer = fs.readFileSync(path.join(media, "organ.jpg"));

// Convert buffer to base64 string.
const imageBase64 = imageBuffer.toString("base64");

// Build contents using createUserContent and createPartFromBase64.
const contents = createUserContent([
  prompt,
  createPartFromBase64(imageBase64, "image/jpeg"),
]);

const countTokensResponse = await ai.models.countTokens({
  model: "gemini-2.0-flash",
  contents: contents,
});
console.log(countTokensResponse.totalTokens);

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

動画ファイルまたは音声ファイル

音声と動画は、次の固定レートでトークンに変換されます。

  • 動画: 1 秒あたり 263 トークン
  • 音声: 1 秒あたり 32 トークン

テキストと動画/音声の入力を使用して countTokens を呼び出すと、テキストと動画/音声ファイルの結合トークン数が入力のみtotalTokens)で返されます。この呼び出しは、generateContent を呼び出してリクエストのサイズを確認する前に行うことができます。必要に応じて、テキストとファイルに対して個別に countTokens を呼び出すこともできます。

別の方法としては、generateContent を呼び出し、response オブジェクトの usageMetadata 属性を使用して次の情報を取得します。

  • 入力(promptTokenCount)、キャッシュに保存されたコンテンツ(cachedContentTokenCount)、出力(candidatesTokenCount)のトークン数の内訳
  • 思考プロセスのトークン数(thoughtsTokenCount
  • 入力と出力の両方のトークンの合計数(totalTokenCount
// Make sure to include the following import:
// import {GoogleGenAI} from '@google/genai';
const ai = new GoogleGenAI({ apiKey: process.env.GEMINI_API_KEY });
const prompt = "Tell me about this video";
let videoFile = await ai.files.upload({
  file: path.join(media, "Big_Buck_Bunny.mp4"),
  config: { mimeType: "video/mp4" },
});

// Poll until the video file is completely processed (state becomes ACTIVE).
while (!videoFile.state || videoFile.state.toString() !== "ACTIVE") {
  console.log("Processing video...");
  console.log("File state: ", videoFile.state);
  await sleep(5000);
  videoFile = await ai.files.get({ name: videoFile.name });
}

const countTokensResponse = await ai.models.countTokens({
  model: "gemini-2.0-flash",
  contents: createUserContent([
    prompt,
    createPartFromUri(videoFile.uri, videoFile.mimeType),
  ]),
});
console.log(countTokensResponse.totalTokens);

const generateResponse = await ai.models.generateContent({
  model: "gemini-2.0-flash",
  contents: createUserContent([
    prompt,
    createPartFromUri(videoFile.uri, videoFile.mimeType),
  ]),
});
console.log(generateResponse.usageMetadata);

システム指示とツール

システムの手順とツールも、入力の合計トークン数にカウントされます。

システム指示を使用すると、systemInstruction の追加を反映して totalTokens のカウントが増加します。

関数呼び出しを使用すると、tools の追加を反映して totalTokens のカウントが増加します。