Tokens verstehen und zählen

Gemini und andere generative KI-Modelle verarbeiten Ein- und Ausgabe auf einer Granularitätsebene, die als Token bezeichnet wird.

Bei Gemini-Modellen entspricht ein Token etwa vier Zeichen. 100 Tokens entsprechen etwa 60–80 Wörtern.

Tokens

Tokens können einzelne Zeichen wie z oder ganze Wörter wie cat sein. Lange Wörter werden in mehrere Tokens aufgeteilt. Die Menge aller vom Modell verwendeten Tokens wird als Vokabular bezeichnet. Der Vorgang, Text in Tokens aufzuteilen, wird als Tokenisierung bezeichnet.

Wenn die Abrechnung aktiviert ist, werden die Kosten eines Aufrufs der Gemini API unter anderem durch die Anzahl der Eingabe- und Ausgabetokens bestimmt. Es kann also hilfreich sein, zu wissen, wie Tokens gezählt werden.


Tokens zählen

Alle Ein- und Ausgaben der Gemini API werden tokenisiert, einschließlich Text, Bilddateien und anderer nicht textbasierter Modalitäten.

Sie können Tokens auf folgende Weise zählen:

  • Rufen Sie countTokens mit der Eingabe der Anfrage auf.
     Gibt die Gesamtzahl der Tokens nur in der Eingabe zurück. Sie können diesen Aufruf vor dem Senden der Eingabe an das Modell ausführen, um die Größe Ihrer Anfragen zu prüfen.

  • Verwenden Sie das usageMetadata-Attribut für das response-Objekt, nachdem Sie generate_content aufgerufen haben.
     Gibt die Gesamtzahl der Tokens sowohl in der Eingabe als auch in der Ausgabe zurück: totalTokenCount.
     Außerdem werden die Tokenanzahlen der Eingabe und Ausgabe separat zurückgegeben: promptTokenCount (Eingabetokens) und candidatesTokenCount (Ausgabetokens). Wenn Sie Kontext-Caching verwenden, wird die Anzahl der im Cache gespeicherten Tokens in cachedContentTokenCount angezeigt.

    Wenn Sie ein Denkmodell wie die 2.5-Modelle verwenden, werden die während des Denkprozesses verwendeten Tokens in thoughtsTokenCount zurückgegeben.

Text-Tokens zählen

Wenn Sie countTokens mit einer reinen Texteingabe aufrufen, wird die Anzahl der Tokens des Texts nur in der Eingabe (totalTokens) zurückgegeben. Sie können diesen Aufruf vor dem Aufrufen von generateContent ausführen, um die Größe Ihrer Anfragen zu prüfen.

Eine weitere Möglichkeit besteht darin, generateContent aufzurufen und dann das Attribut usageMetadata für das response-Objekt zu verwenden, um Folgendes abzurufen:

  • Die separaten Tokenzahlen der Eingabe (promptTokenCount), der im Cache gespeicherten Inhalte (cachedContentTokenCount) und der Ausgabe (candidatesTokenCount)
  • Die Tokenanzahl für den Denkprozess (thoughtsTokenCount)
  • Die Gesamtzahl der Tokens sowohl in der Eingabe als auch in der Ausgabe (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);
count_tokens.js

Tokens für wechselseitige Chats zählen

Wenn Sie countTokens mit dem Chatverlauf aufrufen, wird die Gesamtzahl der Tokens des Texts für jede Rolle im Chat (totalTokens) zurückgegeben.

Eine weitere Möglichkeit besteht darin, sendMessage aufzurufen und dann das Attribut usageMetadata für das response-Objekt zu verwenden, um Folgendes abzurufen:

  • Die separaten Tokenzahlen der Eingabe (promptTokenCount), der im Cache gespeicherten Inhalte (cachedContentTokenCount) und der Ausgabe (candidatesTokenCount)
  • Die Tokenanzahl für den Denkprozess (thoughtsTokenCount)
  • Die Gesamtzahl der Tokens sowohl in der Eingabe als auch in der Ausgabe (totalTokenCount)

Um zu sehen, wie umfangreich der nächste Gesprächsbeitrag sein wird, müssen Sie ihn an den Verlauf anhängen, wenn Sie countTokens aufrufen.

// 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,
);
count_tokens.js

Multimodale Tokens zählen

Alle Eingaben für die Gemini API werden tokenisiert, einschließlich Text, Bilddateien und anderer nicht textbasierter Modalitäten. Hier sind einige wichtige Punkte zur Tokenisierung multimodaler Eingaben bei der Verarbeitung durch die Gemini API:

  • Bei Gemini 2.0 werden Bildeingaben mit beiden Dimensionen <=384 Pixel als 258 Tokens gezählt. Bilder, die in einer oder beiden Dimensionen größer sind, werden nach Bedarf in Kacheln mit 768 × 768 Pixeln zugeschnitten und skaliert. Jede Kachel wird als 258 Tokens gezählt. Vor Gemini 2.0 wurden für Bilder immer 258 Tokens verwendet.

  • Video- und Audiodateien werden zu den folgenden festen Raten in Tokens umgewandelt: Video mit 263 Tokens pro Sekunde und Audio mit 32 Tokens pro Sekunde.

Media-Auflösungen

Mit der Vorabversion von Gemini 3 Pro wird die detaillierte Steuerung der multimodalen Bildverarbeitung mit dem Parameter media_resolution eingeführt. Der Parameter media_resolution bestimmt die maximale Anzahl von Tokens, die pro Eingabebild oder Videoframes zugewiesen werden. Höhere Auflösungen verbessern die Fähigkeit des Modells, feinen Text zu lesen oder kleine Details zu erkennen, erhöhen aber die Tokennutzung und die Latenz.

Weitere Informationen zum Parameter und dazu, wie er sich auf die Tokenberechnung auswirken kann, finden Sie im Leitfaden zur Media-Auflösung.

Bilddateien

Wenn Sie countTokens mit einer Text- und Bildeingabe aufrufen, wird die kombinierte Anzahl der Tokens für den Text und das Bild nur in der Eingabe (totalTokens) zurückgegeben. Sie können diesen Aufruf vor dem Aufrufen von generateContent ausführen, um die Größe Ihrer Anfragen zu prüfen. Optional können Sie countTokens auch separat für den Text und die Datei aufrufen.

Eine weitere Möglichkeit besteht darin, generateContent aufzurufen und dann das Attribut usageMetadata für das response-Objekt zu verwenden, um Folgendes abzurufen:

  • Die separaten Tokenzahlen der Eingabe (promptTokenCount), der im Cache gespeicherten Inhalte (cachedContentTokenCount) und der Ausgabe (candidatesTokenCount)
  • Die Tokenanzahl für den Denkprozess (thoughtsTokenCount)
  • Die Gesamtzahl der Tokens sowohl in der Eingabe als auch in der Ausgabe (totalTokenCount)

Beispiel mit einem hochgeladenen Bild aus der 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);
count_tokens.js

Beispiel, in dem das Bild als Inline-Daten bereitgestellt wird:

// 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);
count_tokens.js

Video- oder Audiodateien

Audio und Video werden zu den folgenden festen Raten in Tokens umgewandelt:

  • Video: 263 Tokens pro Sekunde
  • Audio: 32 Tokens pro Sekunde

Wenn Sie countTokens mit einer Text- und Video-/Audioeingabe aufrufen, wird die kombinierte Anzahl von Tokens des Texts und der Video-/Audiodatei nur in der Eingabe (totalTokens) zurückgegeben. Sie können diesen Aufruf vor dem Aufrufen von generateContent ausführen, um die Größe Ihrer Anfragen zu prüfen. Optional können Sie countTokens auch separat für den Text und die Datei aufrufen.

Eine weitere Möglichkeit besteht darin, generateContent aufzurufen und dann das Attribut usageMetadata für das response-Objekt zu verwenden, um Folgendes abzurufen:

  • Die separaten Tokenzahlen der Eingabe (promptTokenCount), der im Cache gespeicherten Inhalte (cachedContentTokenCount) und der Ausgabe (candidatesTokenCount)
  • Die Tokenanzahl für den Denkprozess (thoughtsTokenCount)
  • Die Gesamtzahl der Tokens sowohl in der Eingabe als auch in der Ausgabe (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);
count_tokens.js

Systemanweisungen und Tools

Systemanweisungen und Tools werden ebenfalls auf die Gesamtzahl der Tokens für die Eingabe angerechnet.

Wenn Sie Systemanweisungen verwenden, erhöht sich die Anzahl der totalTokens, um die Hinzufügung von systemInstruction zu berücksichtigen.

Wenn Sie Funktionsaufrufe verwenden, erhöht sich die Anzahl von totalTokens, um die Hinzufügung von tools zu berücksichtigen.