Memahami dan menghitung token


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

Tentang token

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

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

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

Menghitung token

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

Anda dapat menghitung token dengan cara berikut:

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

  • Gunakan atribut usageMetadata pada objek response setelah memanggil generate_content.
    Tindakan 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).

Menghitung token teks

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

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

  • Jumlah token terpisah dari input (promptTokenCount) dan output (candidatesTokenCount)
  • Jumlah total token dalam 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-giliran (chat)

Jika Anda memanggil countTokens dengan histori chat, tindakan ini akan menampilkan jumlah total token 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) dan output (candidatesTokenCount)
  • Jumlah total token dalam input dan output (totalTokenCount)

Untuk memahami seberapa besar giliran percakapan Anda berikutnya, Anda harus menambahkannya ke histori saat 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 ditokenisasi, 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 ubin berukuran 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 kecepatan 263 token per detik dan audio dengan kecepatan 32 token per detik.

File gambar

Jika Anda memanggil countTokens dengan input teks dan gambar, countTokens akan menampilkan jumlah token gabungan teks dan gambar di input saja (totalTokens). Anda dapat melakukan panggilan ini sebelum memanggil generateContent untuk memeriksa ukuran permintaan Anda. Anda juga dapat 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) dan output (candidatesTokenCount)
  • Jumlah total token dalam 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 tarif tetap berikut:

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

Jika Anda memanggil countTokens dengan input teks dan video/audio, metode ini akan menampilkan jumlah token gabungan dari teks dan file video/audio dalam input saja (totalTokens). Anda dapat melakukan panggilan ini sebelum memanggil generateContent untuk memeriksa ukuran permintaan. Secara opsional, Anda juga dapat 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) dan output (candidatesTokenCount)
  • Jumlah total token dalam 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 total jumlah 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.