Zrozumienie i liczenie tokenów

Gemini i inne modele generatywnej AI przetwarzają dane wejściowe i wyjściowe w jednostkach zwanych tokenami.

W przypadku modeli Gemini token odpowiada około 4 znakom. 100 tokenów to około 60–80 słów w języku angielskim.

Informacje o tokenach

Tokeny mogą być pojedynczymi znakami, np. z, lub całymi słowami, np. cat. Długie słowa są dzielone na kilka tokenów. Zbiór wszystkich tokenów używanych przez model nazywa się słownikiem, a proces dzielenia tekstu na tokeny to tokenizacja.

Gdy płatności są włączone, koszt wywołania interfejsu Gemini API zależy częściowo od liczby tokenów wejściowych i wyjściowych, więc wiedza o tym, jak je zliczać, może być przydatna.

Liczba tokenów

Wszystkie dane wejściowe i wyjściowe interfejsu Gemini API są tokenizowane, w tym tekst, pliki obrazów i inne formaty nietekstowe.

Tokeny możesz zliczać na te sposoby:

Wywołaj funkcję countTokens, podając dane wejściowe żądania.
Zwraca łączną liczbę tokenów tylko w danych wejściowych. Możesz wykonać to wywołanie przed wysłaniem danych wejściowych do modelu, aby sprawdzić rozmiar żądań.
Użyj atrybutu usageMetadata w obiekcie response po wywołaniu funkcji generate_content.
Zwraca łączną liczbę tokenów zarówno wejściowych, jak i wyjściowych: totalTokenCount.
Zwraca też oddzielnie liczbę tokenów wejściowych i wyjściowych: promptTokenCount (tokeny wejściowe) i candidatesTokenCount (tokeny wyjściowe). Jeśli używasz pamięci podręcznej kontekstu, liczba tokenów w pamięci podręcznej będzie podana w cachedContentTokenCount.

Jeśli używasz modelu myślącego, takiego jak modele 2.5, tokeny użyte w procesie myślenia są zwracane w thoughtsTokenCount.

Zliczanie tokenów tekstowych

Jeśli wywołasz funkcję countTokens z wejściem tekstowym, zwróci ona liczbę tokenów tekstu tylko w danych wejściowych (totalTokens). Możesz wywołać tę funkcję przed wywołaniem funkcji generateContent, aby sprawdzić rozmiar żądań.

Inną opcją jest wywołanie generateContent, a następnie użycie atrybutu usageMetadata w obiekcie response, aby uzyskać te informacje:

Osobne liczby tokenów dla danych wejściowych (promptTokenCount), treści w pamięci podręcznej (cachedContentTokenCount) i danych wyjściowych (candidatesTokenCount).
Liczba tokenów w procesie myślowym (thoughtsTokenCount)
Łączna liczba tokenów zarówno wejściowych, jak i wyjściowych (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

Zliczanie tokenów w przypadku promptów wieloetapowych (czat)

Jeśli wywołasz countTokens z historią czatu, zwróci ona łączną liczbę tokenów tekstu z każdej roli na czacie (totalTokens).

Inną opcją jest wywołanie sendMessage, a następnie użycie atrybutu usageMetadata w obiekcie response, aby uzyskać te informacje:

Osobne liczby tokenów dla danych wejściowych (promptTokenCount), treści w pamięci podręcznej (cachedContentTokenCount) i danych wyjściowych (candidatesTokenCount).
Liczba tokenów w procesie myślowym (thoughtsTokenCount)
Łączna liczba tokenów zarówno wejściowych, jak i wyjściowych (totalTokenCount)

Aby dowiedzieć się, jak duża będzie kolejna tura rozmowy, musisz dodać ją do historii, gdy wywołujesz funkcję 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,
);count_tokens.js

Zliczanie tokenów multimodalnych

Wszystkie dane wejściowe do Gemini API są tokenizowane, w tym tekst, pliki graficzne i inne formaty nietekstowe. Podczas przetwarzania danych wejściowych multimodalnych przez interfejs Gemini API weź pod uwagę te kluczowe informacje o tokenizacji:

W przypadku Gemini 2.0 dane wejściowe w postaci obrazów, których oba wymiary są mniejsze lub równe 384 pikselom, są liczone jako 258 tokenów. Obrazy większe w jednym lub obu wymiarach są przycinane i skalowane w razie potrzeby do rozmiaru 768 x 768 pikseli. Każdy taki fragment jest liczony jako 258 tokenów. Przed wprowadzeniem Gemini 2.0 obrazy wykorzystywały stałą liczbę 258 tokenów.
Pliki wideo i audio są konwertowane na tokeny według tych stałych stawek: wideo – 263 tokeny na sekundę, audio – 32 tokeny na sekundę.

Rozdzielczości multimediów

Wersja podglądowa Gemini 3 Pro wprowadza szczegółową kontrolę nad przetwarzaniem obrazu multimodalnego za pomocą parametru media_resolution. Parametr media_resolution określa maksymalną liczbę tokenów przydzielonych na obraz wejściowy lub klatkę filmu. Wyższe rozdzielczości zwiększają zdolność modelu do odczytywania drobnego tekstu lub rozpoznawania małych szczegółów, ale zwiększają zużycie tokenów i opóźnienie.

Więcej informacji o tym parametrze i jego wpływie na obliczenia tokenów znajdziesz w przewodniku rozdzielczość multimediów.

Pliki graficzne

Jeśli wywołasz funkcję countTokens z tekstem i obrazem, zwróci ona łączną liczbę tokenów tekstu i obrazu tylko w danych wejściowych (totalTokens). Możesz wywołać tę funkcję przed wywołaniem funkcji generateContent, aby sprawdzić rozmiar żądań. Opcjonalnie możesz też wywołać funkcję countTokens osobno w przypadku tekstu i pliku.

Inną opcją jest wywołanie generateContent, a następnie użycie atrybutu usageMetadata w obiekcie response, aby uzyskać te informacje:

Osobne liczby tokenów dla danych wejściowych (promptTokenCount), treści w pamięci podręcznej (cachedContentTokenCount) i danych wyjściowych (candidatesTokenCount).
Liczba tokenów w procesie myślowym (thoughtsTokenCount)
Łączna liczba tokenów zarówno wejściowych, jak i wyjściowych (totalTokenCount)

Przykład, który korzysta z przesłanego obrazu z interfejsu 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

Przykład, w którym obraz jest podany jako dane w treści:

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

pliki wideo lub audio,

Dźwięk i obraz są przeliczane na tokeny według tych stałych stawek:

Wideo: 263 tokeny na sekundę
Audio: 32 tokeny na sekundę

Jeśli wywołasz funkcję countTokens z tekstowym i wideo/audio danymi wejściowymi, zwróci ona łączną liczbę tokenów tekstu i pliku wideo/audio tylko w danych wejściowych (totalTokens). Możesz wywołać tę funkcję przed wywołaniem funkcji generateContent, aby sprawdzić rozmiar żądań. Możesz też opcjonalnie wywołać funkcję countTokens na tekście i pliku osobno.

Inną opcją jest wywołanie generateContent, a następnie użycie atrybutu usageMetadata w obiekcie response, aby uzyskać te informacje:

Osobne liczby tokenów dla danych wejściowych (promptTokenCount), treści w pamięci podręcznej (cachedContentTokenCount) i danych wyjściowych (candidatesTokenCount).
Liczba tokenów w procesie myślowym (thoughtsTokenCount)
Łączna liczba tokenów zarówno wejściowych, jak i wyjściowych (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

Instrukcje i narzędzia systemowe

Instrukcje i narzędzia systemowe są również wliczane do łącznej liczby tokenów wejściowych.

Jeśli używasz instrukcji systemowych, liczba totalTokens wzrośnie, aby odzwierciedlić dodanie systemInstruction.

Jeśli używasz wywoływania funkcji, liczba totalTokens wzrośnie, aby odzwierciedlić dodanie tools.