Memahami dan menghitung token

Gemini dan model AI generatif lainnya memproses input dan output pada perincian yang disebut token.

Untuk model Gemini, satu token setara dengan sekitar 4 karakter. 100 token setara dengan sekitar 60-80 kata dalam bahasa Inggris.

Tentang token

Token dapat berupa karakter tunggal seperti z atau seluruh kata seperti cat. Kata-kata panjang dipecah menjadi beberapa token. Kumpulan semua token yang digunakan oleh model disebut kosakata, dan proses membagi teks menjadi token disebut tokenisasi.

Jika penagihan diaktifkan, biaya panggilan ke Gemini API ditentukan sebagian oleh jumlah token input dan output, jadi mengetahui cara menghitung token dapat membantu.


Menjumlahkan token

Semua input ke dan output dari Gemini API di-tokenisasi, termasuk teks, file gambar, dan modalitas non-teks lainnya.

Anda dapat menghitung token dengan cara berikut:

  • Panggil countTokens dengan input permintaan.
    Ini menampilkan jumlah total token dalam input saja. Anda dapat melakukan panggilan ini sebelum mengirim input ke model untuk memeriksa ukuran permintaan Anda.

  • Gunakan atribut usageMetadata pada objek response setelah memanggil generate_content.
    Ini menampilkan jumlah total token dalam input dan output: totalTokenCount.
    Fungsi ini juga menampilkan jumlah token input dan output secara terpisah: promptTokenCount (token input) dan candidatesTokenCount (token output). Jika Anda menggunakan Context caching, jumlah token yang di-cache akan ada di cachedContentTokenCount.

    Jika Anda menggunakan model penalaran seperti model 2.5, token yang digunakan selama proses penalaran akan ditampilkan di thoughtsTokenCount.

Menghitung token teks

Jika Anda memanggil countTokens dengan input khusus teks, fungsi ini akan menampilkan jumlah token teks di input saja (totalTokens). Anda dapat melakukan panggilan ini sebelum memanggil generateContent untuk memeriksa ukuran permintaan Anda.

Opsi lainnya adalah memanggil generateContent, lalu menggunakan atribut usageMetadata pada objek response untuk mendapatkan hal berikut:

  • Jumlah token terpisah dari input (promptTokenCount), konten yang di-cache (cachedContentTokenCount), dan output (candidatesTokenCount)
  • Jumlah token untuk proses berpikir (thoughtsTokenCount)
  • Jumlah total token di input dan output (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

Menghitung token multi-turn (chat)

Jika Anda memanggil countTokens dengan histori chat, fungsi ini akan menampilkan jumlah token total teks dari setiap peran dalam chat (totalTokens).

Opsi lainnya adalah memanggil sendMessage, lalu menggunakan atribut usageMetadata pada objek response untuk mendapatkan hal berikut:

  • Jumlah token terpisah dari input (promptTokenCount), konten yang di-cache (cachedContentTokenCount), dan output (candidatesTokenCount)
  • Jumlah token untuk proses berpikir (thoughtsTokenCount)
  • Jumlah total token di input dan output (totalTokenCount)

Untuk memahami seberapa besar giliran percakapan Anda berikutnya, Anda perlu menambahkan giliran tersebut ke histori saat Anda memanggil 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

Menghitung token multimodal

Semua input ke Gemini API di-tokenisasi, termasuk teks, file gambar, dan modalitas non-teks lainnya. Perhatikan poin-poin penting tingkat tinggi berikut tentang tokenisasi input multimodal selama pemrosesan oleh Gemini API:

  • Dengan Gemini 2.0, input gambar dengan kedua dimensi <=384 piksel dihitung sebagai 258 token. Gambar yang lebih besar dalam satu atau kedua dimensi akan dipangkas dan diskalakan sesuai kebutuhan menjadi petak 768x768 piksel, yang masing-masing dihitung sebagai 258 token. Sebelum Gemini 2.0, gambar menggunakan 258 token tetap.

  • File video dan audio dikonversi menjadi token dengan tarif tetap berikut: video dengan 263 token per detik dan audio dengan 32 token per detik.

Resolusi media

Pratinjau Gemini 3 Pro memperkenalkan kontrol terperinci atas pemrosesan visi multimodal dengan parameter media_resolution. Parameter media_resolution menentukan jumlah maksimum token yang dialokasikan per gambar input atau frame video. Resolusi yang lebih tinggi meningkatkan kemampuan model untuk membaca teks kecil atau mengidentifikasi detail kecil, tetapi meningkatkan penggunaan token dan latensi.

Untuk mengetahui detail selengkapnya tentang parameter dan pengaruhnya terhadap penghitungan token, lihat panduan resolusi media.

File gambar

Jika Anda memanggil countTokens dengan input teks dan gambar, fungsi ini akan menampilkan jumlah token gabungan dari teks dan gambar hanya dalam input (totalTokens). Anda dapat melakukan panggilan ini sebelum memanggil generateContent untuk memeriksa ukuran permintaan Anda. Anda juga dapat memanggil countTokens secara opsional pada teks dan file secara terpisah.

Opsi lainnya adalah memanggil generateContent, lalu menggunakan atribut usageMetadata pada objek response untuk mendapatkan hal berikut:

  • Jumlah token terpisah dari input (promptTokenCount), konten yang di-cache (cachedContentTokenCount), dan output (candidatesTokenCount)
  • Jumlah token untuk proses berpikir (thoughtsTokenCount)
  • Jumlah total token di input dan output (totalTokenCount)

Contoh yang menggunakan gambar yang diupload dari 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

Contoh yang menyediakan gambar sebagai data inline:

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

File video atau audio

Audio dan video masing-masing dikonversi menjadi token dengan rasio tetap berikut:

  • Video: 263 token per detik
  • Audio: 32 token per detik

Jika Anda memanggil countTokens dengan input teks dan video/audio, fungsi ini akan menampilkan jumlah token gabungan dari teks dan file video/audio hanya di input (totalTokens). Anda dapat melakukan panggilan ini sebelum memanggil generateContent untuk memeriksa ukuran permintaan Anda. Anda juga dapat secara opsional memanggil countTokens pada teks dan file secara terpisah.

Opsi lainnya adalah memanggil generateContent, lalu menggunakan atribut usageMetadata pada objek response untuk mendapatkan hal berikut:

  • Jumlah token terpisah dari input (promptTokenCount), konten yang di-cache (cachedContentTokenCount), dan output (candidatesTokenCount)
  • Jumlah token untuk proses berpikir (thoughtsTokenCount)
  • Jumlah total token di input dan output (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

Petunjuk dan alat sistem

Petunjuk dan alat sistem juga dihitung dalam jumlah total token untuk input.

Jika Anda menggunakan petunjuk sistem, jumlah totalTokens akan bertambah untuk mencerminkan penambahan systemInstruction.

Jika Anda menggunakan panggilan fungsi, jumlah totalTokens akan bertambah untuk mencerminkan penambahan tools.