Memahami dan menghitung token

Gemini dan model AI generatif lainnya memproses input dan output pada granularitas 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 kata utuh seperti cat. Kata-kata panjang dipecah menjadi beberapa token. Himpunan semua token yang digunakan oleh model disebut kosakata, dan proses pemisahan teks menjadi token disebut tokenisasi.

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

Anda dapat mencoba menghitung token di Colab kami.

Lihat di ai.google.dev Coba notebook Colab Lihat notebook di GitHub

Menghitung token

Semua input dan output dari API Gemini dienkripsi dengan token, termasuk teks, file gambar, dan modalitas non-teks lainnya.

Anda dapat menghitung token dengan cara-cara berikut:

  • Panggilancount_tokens dengan masukan dari permintaan tersebut.
    Ini mengembalikan jumlah total token dalam input saja. Anda dapat melakukan panggilan ini sebelum mengirim input ke model untuk memeriksa ukuran permintaan Anda.

  • Gunakan atribut usage_metadata pada objek response setelah memanggil generate_content.
    Ini mengembalikan jumlah total token dalam baik input maupun output: total_token_count.
    Fungsi ini juga mengembalikan jumlah token input dan output secara terpisah: prompt_token_count (token input) dan candidates_token_count (token output).

    Jika Anda menggunakan model penalaran, token yang digunakan selama proses penalaran akan ditampilkan di thoughts_token_count. Dan jika Anda menggunakan Context caching, jumlah token yang di-cache akan berada di cached_content_token_count.

Hitung token teks

Jika Anda memanggil count_tokens dengan input hanya teks, fungsi ini akan menampilkan jumlah token teks di input saja (total_tokens). Anda dapat melakukan panggilan ini sebelum memanggil generate_content untuk memeriksa ukuran permintaan Anda.

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

  • Jumlah token input (prompt_token_count), konten yang di-cache (cached_content_token_count), dan output (candidates_token_count) yang terpisah
  • Jumlah token untuk proses berpikir (thoughts_token_count)

  • Jumlah total token di input dan output (total_token_count)

Python

from google import genai

client = genai.Client()
prompt = "The quick brown fox jumps over the lazy dog."

total_tokens = client.models.count_tokens(
    model="gemini-3.8-flash", contents=prompt
)
print("total_tokens: ", total_tokens)

response = client.models.generate_content(
    model="gemini-3.8-flash", contents=prompt
)

print(response.usage_metadata)

JavaScript

import { GoogleGenAI } from '@google/genai';

const ai = new GoogleGenAI({});
const prompt = "The quick brown fox jumps over the lazy dog.";

async function main() {
  const countTokensResponse = await ai.models.countTokens({
    model: "gemini-3.8-flash",
    contents: prompt,
  });
  console.log(countTokensResponse.totalTokens);

  const generateResponse = await ai.models.generateContent({
    model: "gemini-3.8-flash",
    contents: prompt,
  });
  console.log(generateResponse.usageMetadata);
}

await main();

Go

ctx := context.Background()
client, err := genai.NewClient(ctx, nil)

// Convert prompt to a slice of *genai.Content using the helper.
contents := []*genai.Content{
  genai.NewContentFromText(prompt, genai.RoleUser),
}
countResp, err := client.Models.CountTokens(ctx, "gemini-3.8-flash", contents, nil)
if err != nil {
  return err
}
fmt.Println("total_tokens:", countResp.TotalTokens)

response, err := client.Models.GenerateContent(ctx, "gemini-3.8-flash", contents, nil)
if err != nil {
  log.Fatal(err)
}
usageMetadata, err := json.MarshalIndent(response.UsageMetadata, "", "  ")
if err != nil {
  log.Fatal(err)
}
fmt.Println(string(usageMetadata))
    ```

Menghitung token multi-giliran (chat)

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

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

  • Jumlah token input (prompt_token_count), konten yang di-cache (cached_content_token_count), dan output (candidates_token_count) yang terpisah
  • Jumlah token untuk proses berpikir (thoughts_token_count)
  • Jumlah total token di input dan output (total_token_count)

Untuk memahami seberapa besar giliran percakapan Anda berikutnya, Anda perlu menambahkan giliran tersebut ke histori saat Anda memanggil count_tokens.

Python

from google import genai
from google.genai import types

client = genai.Client()

chat = client.chats.create(
    model="gemini-3.8-flash",
    history=[
        types.Content(
            role="user", parts=[types.Part(text="Hi my name is Bob")]
        ),
        types.Content(role="model", parts=[types.Part(text="Hi Bob!")]),
    ],
)

print(
    client.models.count_tokens(
        model="gemini-3.8-flash", contents=chat.get_history()
    )
)

response = chat.send_message(
    message="In one sentence, explain how a computer works to a young child."
)
print(response.usage_metadata)

extra = types.UserContent(
    parts=[
        types.Part(
            text="What is the meaning of life?",
        )
    ]
)
history = [*chat.get_history(), extra]
print(client.models.count_tokens(model="gemini-3.8-flash", contents=history))

JavaScript

import { GoogleGenAI } from '@google/genai';

const ai = new GoogleGenAI({});

async function main() {
  const history = [
    { role: "user", parts: [{ text: "Hi my name is Bob" }] },
    { role: "model", parts: [{ text: "Hi Bob!" }] },
  ];
  const chat = ai.chats.create({
    model: "gemini-3.8-flash",
    history: history,
  });

  const countTokensResponse = await ai.models.countTokens({
    model: "gemini-3.8-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);

  const extraMessage = {
    role: "user",
    parts: [{ text: "What is the meaning of life?" }],
  };
  const combinedHistory = [...chat.getHistory(), extraMessage];
  const combinedCountTokensResponse = await ai.models.countTokens({
    model: "gemini-3.8-flash",
    contents: combinedHistory,
  });
  console.log(
    "Combined history token count:",
    combinedCountTokensResponse.totalTokens,
  );
}

await main();

Go

ctx := context.Background()
client, err := genai.NewClient(ctx, nil)

history := []*genai.Content{
  {Role: genai.RoleUser, Parts: []*genai.Part({Text: "Hi my name is Bob"})},
  {Role: genai.RoleModel, Parts: []*genai.Part({Text: "Hi Bob!"})},
}
chat, err := client.Chats.Create(ctx, "gemini-3.8-flash", nil, history)
if err != nil {
  log.Fatal(err)
}

firstTokenResp, err := client.Models.CountTokens(ctx, "gemini-3.8-flash", chat.History(false), nil)
if err != nil {
  log.Fatal(err)
}
fmt.Println(firstTokenResp.TotalTokens)

resp, err := chat.SendMessage(ctx, genai.NewPartFromText("In one sentence, explain how a computer works to a young child."))
if err != nil {
  log.Fatal(err)
}
fmt.Printf("%#v\n", resp.UsageMetadata)

extra := genai.NewContentFromText("What is the meaning of life?", genai.RoleUser)
hist := chat.History(false)
hist = append(hist, extra)

secondTokenResp, err := client.Models.CountTokens(ctx, "gemini-3.8-flash", hist, nil)
if err != nil {
  log.Fatal(err)
}
fmt.Println(secondTokenResp.TotalTokens)

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:

  • Input gambar dengan kedua dimensi <=384 piksel dihitung sebagai 258 token. Gambar yang lebih besar dalam satu atau kedua dimensinya dipotong dan diskalakan sesuai kebutuhan menjadi ubin berukuran 768x768 piksel, yang masing-masing dihitung sebagai 258 token.

  • File video dan audio dikonversi menjadi token dengan kecepatan tetap berikut: video dengan kecepatan 263 token per detik dan audio dengan kecepatan 32 token per detik. Tarif ini berlaku untuk pemrosesan statis (standar). Untuk pemrosesan berbasis agen, penggunaan token bervariasi. Lihat Penggunaan token video berdasarkan mode pemrosesan.

Resolusi media

Model Gemini 3 memperkenalkan kontrol granular atas pemrosesan visi multimodal dengan parameter media_resolution. Parameter media_resolution menentukan jumlah token maksimum yang dialokasikan per gambar atau bingkai video masukan. 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 count_tokens dengan input teks dan gambar, maka fungsi ini akan mengembalikan jumlah token gabungan dari teks dan gambar dalam input saja (total_tokens). Anda dapat melakukan panggilan ini sebelum memanggil generate_content untuk memeriksa ukuran permintaan Anda. Anda juga dapat secara opsional memanggil count_tokens pada teks dan file secara terpisah.

Opsi lainnya adalah memanggil generate_content dan kemudian menggunakan atribut usage_metadata pada objek response untuk mendapatkan hasil berikut:

  • Jumlah token input (prompt_token_count), konten yang di-cache (cached_content_token_count), dan output (candidates_token_count) yang terpisah
  • Jumlah token untuk proses berpikir (thoughts_token_count)
  • Jumlah total token di input dan output (total_token_count)

Contoh yang menggunakan gambar yang diunggah dari File API:

Python

from google import genai

client = genai.Client()
prompt = "Tell me about this image"
your_image_file = client.files.upload(file=media / "organ.jpg")

print(
    client.models.count_tokens(
        model="gemini-3.8-flash", contents=[prompt, your_image_file]
    )
)

response = client.models.generate_content(
    model="gemini-3.8-flash", contents=[prompt, your_image_file]
)
print(response.usage_metadata)

JavaScript

import { GoogleGenAI } from '@google/genai';

const ai = new GoogleGenAI({});
const prompt = "Tell me about this image";

async function main() {
  const organ = await ai.files.upload({
    file: path.join(media, "organ.jpg"),
    config: { mimeType: "image/jpeg" },
  });

  const countTokensResponse = await ai.models.countTokens({
    model: "gemini-3.8-flash",
    contents: createUserContent([
      prompt,
      createPartFromUri(organ.uri, organ.mimeType),
    ]),
  });
  console.log(countTokensResponse.totalTokens);

  const generateResponse = await ai.models.generateContent({
    model: "gemini-3.8-flash",
    contents: createUserContent([
      prompt,
      createPartFromUri(organ.uri, organ.mimeType),
    ]),
  });
  console.log(generateResponse.usageMetadata);
}

await main();

Go

ctx := context.Background()
client, err := genai.NewClient(ctx, nil)

file, err := client.Files.UploadFromPath(
  ctx, 
  filepath.Join(getMedia(), "organ.jpg"), 
  &genai.UploadFileConfig{
    MIMEType : "image/jpeg",
  },
)
if err != nil {
  log.Fatal(err)
}
parts := []*genai.Part{
  genai.NewPartFromText("Tell me about this image"),
  genai.NewPartFromURI(file.URI, file.MIMEType),
}
contents := []*genai.Content{
  genai.NewContentFromParts(parts, genai.RoleUser),
}

tokenResp, err := client.Models.CountTokens(ctx, "gemini-3.8-flash", contents, nil)
if err != nil {
  log.Fatal(err)
}
fmt.Println("Multimodal image token count:", tokenResp.TotalTokens)

response, err := client.Models.GenerateContent(ctx, "gemini-3.8-flash", contents, nil)
if err != nil {
  log.Fatal(err)
}
usageMetadata, err := json.MarshalIndent(response.UsageMetadata, "", "  ")
if err != nil {
  log.Fatal(err)
}
fmt.Println(string(usageMetadata))

Contoh yang menyajikan gambar sebagai data sebaris:

Python

from google import genai
import PIL.Image

client = genai.Client()
prompt = "Tell me about this image"
your_image_file = PIL.Image.open(media / "organ.jpg")

print(
    client.models.count_tokens(
        model="gemini-3.8-flash", contents=[prompt, your_image_file]
    )
)

response = client.models.generate_content(
    model="gemini-3.8-flash", contents=[prompt, your_image_file]
)
print(response.usage_metadata)

JavaScript

import { GoogleGenAI } from '@google/genai';

const ai = new GoogleGenAI({});
const prompt = "Tell me about this image";
const imageBuffer = fs.readFileSync(path.join(media, "organ.jpg"));

const imageBase64 = imageBuffer.toString("base64");

const contents = createUserContent([
  prompt,
  createPartFromBase64(imageBase64, "image/jpeg"),
]);

async function main() {
  const countTokensResponse = await ai.models.countTokens({
    model: "gemini-3.8-flash",
    contents: contents,
  });
  console.log(countTokensResponse.totalTokens);

  const generateResponse = await ai.models.generateContent({
    model: "gemini-3.8-flash",
    contents: contents,
  });
  console.log(generateResponse.usageMetadata);
}

await main();

Go

ctx := context.Background()
client, err := genai.NewClient(ctx, nil)

imageBytes, err := os.ReadFile("organ.jpg")
if err != nil {
    log.Fatalf("Failed to read image file: %v", err)
}
parts := []*genai.Part{
  genai.NewPartFromText("Tell me about this image"),
  {
        InlineData: &genai.Blob{
              MIMEType: "image/jpeg",
              Data:     imageBytes,
        },
  },
}
contents := []*genai.Content{
  genai.NewContentFromParts(parts, genai.RoleUser),
}

tokenResp, err := client.Models.CountTokens(ctx, "gemini-3.8-flash", contents, nil)
if err != nil {
  log.Fatal(err)
}
fmt.Println("Multimodal image token count:", tokenResp.TotalTokens)

response, err := client.Models.GenerateContent(ctx, "gemini-3.8-flash", contents, nil)
if err != nil {
  log.Fatal(err)
}
usageMetadata, err := json.MarshalIndent(response.UsageMetadata, "", "  ")
if err != nil {
  log.Fatal(err)
}
fmt.Println(string(usageMetadata))

File video atau audio

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

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

Jika Anda memanggil count_tokens dengan input teks dan video/audio, maka fungsi ini akan mengembalikan jumlah token gabungan dari teks dan file video/audio dalam input saja (total_tokens). Anda dapat melakukan panggilan ini sebelum memanggil generate_content untuk memeriksa ukuran permintaan Anda. Anda juga dapat secara opsional memanggil count_tokens pada teks dan file secara terpisah.

Opsi lainnya adalah memanggil generate_content dan kemudian menggunakan atribut usage_metadata pada objek response untuk mendapatkan hasil berikut:

  • Jumlah token input (prompt_token_count), konten yang di-cache (cached_content_token_count), dan output (candidates_token_count) yang terpisah
  • Jumlah token untuk proses berpikir (thoughts_token_count)

  • Jumlah total token dalam baik input maupun output (total_token_count).

Python

from google import genai
import time

client = genai.Client()
prompt = "Tell me about this video"
your_file = client.files.upload(file=media / "Big_Buck_Bunny.mp4")

while not your_file.state or your_file.state.name != "ACTIVE":
    print("Processing video...")
    print("File state:", your_file.state)
    time.sleep(5)
    your_file = client.files.get(name=your_file.name)

print(
    client.models.count_tokens(
        model="gemini-3.8-flash", contents=[prompt, your_file]
    )
)

response = client.models.generate_content(
    model="gemini-3.8-flash", contents=[prompt, your_file]
)
print(response.usage_metadata)

JavaScript

import { GoogleGenAI } from '@google/genai';

const ai = new GoogleGenAI({});
const prompt = "Tell me about this video";

async function main() {
  let videoFile = await ai.files.upload({
    file: path.join(media, "Big_Buck_Bunny.mp4"),
    config: { mimeType: "video/mp4" },
  });

  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-3.8-flash",
    contents: createUserContent([
      prompt,
      createPartFromUri(videoFile.uri, videoFile.mimeType),
    ]),
  });
  console.log(countTokensResponse.totalTokens);

  const generateResponse = await ai.models.generateContent({
    model: "gemini-3.8-flash",
    contents: createUserContent([
      prompt,
      createPartFromUri(videoFile.uri, videoFile.mimeType),
    ]),
  });
  console.log(generateResponse.usageMetadata);
}

await main();

Go

ctx := context.Background()
client, err := genai.NewClient(ctx, nil)

file, err := client.Files.UploadFromPath(
  ctx,
  filepath.Join(getMedia(), "Big_Buck_Bunny.mp4"),
  &genai.UploadFileConfig{
    MIMEType : "video/mp4",
  },
)
if err != nil {
  log.Fatal(err)
}

for file.State == genai.FileStateUnspecified || file.State != genai.FileStateActive {
  fmt.Println("Processing video...")
  fmt.Println("File state:", file.State)
  time.Sleep(5 * time.Second)

  file, err = client.Files.Get(ctx, file.Name, nil)
  if err != nil {
    log.Fatal(err)
  }
}

parts := []*genai.Part{
  genai.NewPartFromText("Tell me about this video"),
  genai.NewPartFromURI(file.URI, file.MIMEType),
}
contents := []*genai.Content{
  genai.NewContentFromParts(parts, genai.RoleUser),
}

tokenResp, err := client.Models.CountTokens(ctx, "gemini-3.8-flash", contents, nil)
if err != nil {
  log.Fatal(err)
}
fmt.Println("Multimodal video/audio token count:", tokenResp.TotalTokens)
response, err := client.Models.GenerateContent(ctx, "gemini-3.8-flash", contents, nil)
if err != nil {
  log.Fatal(err)
}
usageMetadata, err := json.MarshalIndent(response.UsageMetadata, "", "  ")
if err != nil {
  log.Fatal(err)
}
fmt.Println(string(usageMetadata))

Penggunaan token video menurut mode pemrosesan

Penggunaan token untuk video bergantung pada mode pemrosesan:

Mode pemrosesan Perhitungan token Penggunaan umum
Statis (default) Secara default, sekitar 100 token/detik (resolusi rendah) atau sekitar 300 token/detik (resolusi tinggi). Semua frame diambil sampelnya pada 1 FPS. Dapat diprediksi, sebanding dengan durasi video.
Agentic Tingkat kompleksitas konten bervariasi. Model ini hanya memuat transkrip dan/atau frame dan/atau audio yang dibutuhkan untuk menjawab pertanyaan. Hingga 88% lebih sedikit token untuk konten berformat panjang.

Dengan pemrosesan berbasis agen, kuliah selama 1 jam yang biasanya menggunakan sekitar 1,08 juta token dalam mode statis mungkin hanya menggunakan sekitar 108 ribu token, tergantung pada petunjuk dan kontennya.

Untuk memeriksa penggunaan token sebenarnya untuk suatu permintaan, gunakan kolom usage_metadata dalam respons. Dalam UsageMetadata, token video agen dilaporkan di seluruh bidang berikut:

  • Permintaan awal (referensi video + permintaan pengguna): prompt_token_count
  • Pemikiran navigasi: thoughts_token_count
  • Transkrip, bingkai, dan audio dimuat sesuai permintaan: tool_use_prompt_token_count
  • Jawaban akhir: candidates_token_count

Hitung token pemikiran

Jika Anda mengaktifkan penalaran, harga respons adalah jumlah token output dan token penalaran. Anda dapat mengambil total jumlah token pemikiran yang dihasilkan dari kolom thoughtsTokenCount (atau yang setara dengan SDK).

Python

# ...
print("Thoughts tokens:", response.usage_metadata.thoughts_token_count)
print("Output tokens:", response.usage_metadata.candidates_token_count)

JavaScript

// ...
console.log(`Thoughts tokens: ${response.usageMetadata.thoughtsTokenCount}`);
console.log(`Output tokens: ${response.usageMetadata.candidatesTokenCount}`);

Go

// ...
fmt.Println("Thoughts tokens:", response.UsageMetadata.ThoughtsTokenCount)
fmt.Println("Output tokens:", response.UsageMetadata.CandidatesTokenCount)

Model pemikiran menghasilkan pemikiran lengkap untuk meningkatkan kualitas respons akhir, lalu menghasilkan ringkasan untuk memberikan pemahaman tentang proses pemikiran. Jadi, API mendasarkan harga pada token pemikiran penuh yang dihasilkan model untuk membuat ringkasan, meskipun API hanya menghasilkan ringkasan.

Anda dapat mempelajari lebih lanjut cara mengonfigurasi pemikiran di panduan Pemikiran Gemini.

Jendela konteks

Model yang tersedia melalui Gemini API memiliki jendela konteks yang diukur dalam token. Jendela konteks menentukan seberapa banyak input yang dapat Anda berikan dan seberapa banyak output yang dapat dihasilkan model. Anda dapat menentukan ukuran jendela konteks dengan memanggil endpoint models.get atau dengan melihat dokumentasi model.

Python

from google import genai

client = genai.Client()
model_info = client.models.get(model="gemini-3.8-flash")
print(f"{model_info.input_token_limit=}")
print(f"{model_info.output_token_limit=}")

JavaScript

import { GoogleGenAI } from '@google/genai';

const ai = new GoogleGenAI({});

async function main() {
  const modelInfo = await ai.models.get({model: 'gemini-3.8-flash'});
  console.log(modelInfo.inputTokenLimit);
  console.log(modelInfo.outputTokenLimit);
}

await main();

Go

ctx := context.Background()
client, err := genai.NewClient(ctx, nil)
if err != nil {
  log.Fatal(err)
}
modelInfo, err := client.ModelInfo(ctx, "models/gemini-3.8-flash")
if err != nil {
  log.Fatal(err)
}
fmt.Println("input token limit:", modelInfo.InputTokenLimit)
fmt.Println("output token limit:", modelInfo.OutputTokenLimit)