Gemini 和其他生成式 AI 模型會以稱為「符記」的精細程度處理輸入和輸出內容。
關於符記
符記可以是單一字元 (例如 z
),也可以是整個字詞 (例如 cat
)。長字詞會拆分為多個字元。模型使用的所有符記集合稱為詞彙,將文字分割為符記的程序稱為符記化。
對於 Gemini 模型,一個符號約等於 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 個符記。圖片的一個或兩個尺寸大於 768 x 768 像素時,系統會視需要裁剪及縮放圖片,使其成為 768 x 768 像素的圖塊,每個圖塊會計為 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);
影片或音訊檔案
音訊和影片會以下列固定費率轉換為符記:
- 影片:每秒 263 個符記
- 音訊:每秒 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);
系統指令和工具
系統指令和工具也會計入輸入內容的符記總數。
如果您使用系統指令,totalTokens
計數會增加,以反映 systemInstruction
的新增數量。
如果您使用函式呼叫,totalTokens
計數就會增加,以反映 tools
的增加。