Gemini などの生成 AI モデルは、入力と出力をトークンという粒度で処理します。
トークンについて
トークンは、z
などの単一の文字や、cat
などの単語全体にすることができます。長い単語は複数のトークンに分割されます。モデルで使用されるすべてのトークンのセットは語彙と呼ばれ、テキストをトークンに分割するプロセスはトークン化と呼ばれます。
Gemini モデルの場合、1 個のトークンは約 4 文字に相当します。100 個のトークンは、約 60 ~ 80 ワード(英語)に相当します。
課金が有効になっている場合、Gemini API の呼び出しの費用は、入力トークンと出力トークンの数によって決まるため、トークンのカウント方法を把握しておくと便利です。
トークンのカウント
Gemini API の入出力はすべてトークン化されます。これには、テキスト、画像ファイル、その他のテキスト以外のモダリティが含まれます。
トークンは次の方法でカウントできます。
リクエストの入力を指定して
countTokens
を呼び出します。
入力のみのトークンの合計数を返します。モデルに入力を送信する前にこの呼び出しを行うと、リクエストのサイズを確認できます。generate_content
を呼び出した後に、response
オブジェクトのusageMetadata
属性を使用します。
入力と出力の両方のトークンの合計数totalTokenCount
を返します。
また、入力と出力のトークン数(promptTokenCount
(入力トークン)とcandidatesTokenCount
(出力トークン))も個別に返します。
テキスト トークンをカウントする
テキストのみの入力で countTokens
を呼び出すと、入力のみのテキストのトークン数(totalTokens
)が返されます。generateContent
を呼び出す前にこの呼び出しを行うと、リクエストのサイズを確認できます。
別の方法として、generateContent
を呼び出して、response
オブジェクトの usageMetadata
属性を使用して、次のように取得することもできます。
- 入力(
promptTokenCount
)と出力(candidatesTokenCount
)の個別のトークン数 - 入力と出力の両方のトークンの合計数(
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
)と出力(candidatesTokenCount
)の個別のトークン数 - 入力と出力の両方のトークンの合計数(
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 個のトークンが使用されていました。
動画ファイルと音声ファイルは、動画は 263 トークン / 秒、音声は 32 トークン / 秒の固定レートでトークンに変換されます。
画像ファイル
テキストと画像の入力で countTokens
を呼び出すと、テキストと画像の合計トークン数が入力のみで返されます(totalTokens
)。generateContent
を呼び出す前にこの呼び出しを行うと、リクエストのサイズを確認できます。必要に応じて、テキストとファイルで countTokens
を個別に呼び出すこともできます。
別の方法として、generateContent
を呼び出して、response
オブジェクトの usageMetadata
属性を使用して、次のように取得することもできます。
- 入力(
promptTokenCount
)と出力(candidatesTokenCount
)の個別のトークン数 - 入力と出力の両方のトークンの合計数(
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
)と出力(candidatesTokenCount
)の個別のトークン数 - 入力と出力の両方のトークンの合計数(
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
の数が加算されます。