Jetonları anlama ve sayma

Gemini ve diğer üretken yapay zeka modelleri, giriş ve çıkışı jeton adı verilen bir ayrıntı düzeyinde işler.

Gemini modellerinde bir jeton yaklaşık 4 karaktere eşittir. 100 jeton yaklaşık 60-80 İngilizce kelimeye eşittir.

Jetonlar hakkında

Jetonlar, z gibi tek karakterler veya cat gibi tam kelimeler olabilir. Uzun kelimeler birkaç jetona ayrılır. Model tarafından kullanılan tüm jetonlar kümesine kelime dağarcığı, metni jetonlara bölme işlemine ise jetonlaştırma adı verilir.

Faturalandırma etkinleştirildiğinde Gemini API'ye yapılan bir çağrının maliyeti kısmen giriş ve çıkış jetonlarının sayısına göre belirlenir. Bu nedenle, jetonları nasıl sayacağınızı bilmek faydalı olabilir.

Colab'imizde jeton saymayı deneyebilirsiniz.

ai.google.dev'de görüntüle Colab not defterini deneyin Not defterini GitHub'da görüntüleyin

Parça sayma

Gemini API'ye yapılan tüm girişler ve API'den alınan tüm çıkışlar (metin, resim dosyaları ve metin dışı diğer biçimler dahil) jetonlaştırılır.

Jetonları aşağıdaki şekillerde sayabilirsiniz:

  • İsteğin girişiyle count_tokens işlevini çağırın.
    Bu işlev, yalnızca giriş bölümündeki toplam jeton sayısını döndürür. Bu çağrıyı, isteklerinizin boyutunu kontrol etmek için girişi modele göndermeden önce yapabilirsiniz.

  • generate_content işlevi çağrıldıktan sonra response nesnesinde usage_metadata özelliğini kullanın.
    Bu işlev, hem girişte hem de çıkışta toplam jeton sayısını döndürür: total_token_count.
    Ayrıca giriş ve çıkışın jeton sayılarını ayrı ayrı döndürür: prompt_token_count (giriş jetonları) ve candidates_token_count (çıkış jetonları).

    Düşünme modeli kullanıyorsanız düşünme sürecinde kullanılan jetonlar thoughts_token_count içinde döndürülür. Bağlamı önbelleğe alma özelliğini kullanıyorsanız önbelleğe alınan jeton sayısı cached_content_token_count içinde yer alır.

Metin jetonlarını sayma

count_tokens işlevini yalnızca metin içeren bir girişle çağırırsanız yalnızca girişteki metnin jeton sayısını (total_tokens) döndürür. İsteklerinizin boyutunu kontrol etmek için generate_content işlevini çağırmadan önce bu çağrıyı yapabilirsiniz.

Diğer bir seçenek ise generate_content'ı arayıp usage_metadata özelliğini response nesnesinde kullanarak aşağıdakileri elde etmektir:

  • Giriş (prompt_token_count), önbelleğe alınmış içerik (cached_content_token_count) ve çıkışın (candidates_token_count) ayrı jeton sayıları
  • Düşünme süreci için jeton sayısı (thoughts_token_count)

  • Hem girişte hem de çıkışta toplam jeton sayısı (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-flash-preview", contents=prompt
)
print("total_tokens: ", total_tokens)

response = client.models.generate_content(
    model="gemini-3-flash-preview", 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-flash-preview",
    contents: prompt,
  });
  console.log(countTokensResponse.totalTokens);

  const generateResponse = await ai.models.generateContent({
    model: "gemini-3-flash-preview",
    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-flash-preview", contents, nil)
if err != nil {
  return err
}
fmt.Println("total_tokens:", countResp.TotalTokens)

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

Çok adımlı (sohbet) jetonlarını sayma

Sohbet geçmişiyle count_tokens işlevini çağırırsanız sohbetteki her rolden gelen metnin toplam jeton sayısını (total_tokens) döndürür.

Diğer bir seçenek ise send_message'ı arayıp usage_metadata özelliğini response nesnesinde kullanarak aşağıdakileri elde etmektir:

  • Giriş (prompt_token_count), önbelleğe alınmış içerik (cached_content_token_count) ve çıkışın (candidates_token_count) ayrı jeton sayıları
  • Düşünme süreci için jeton sayısı (thoughts_token_count)
  • Hem girişte hem de çıkışta toplam jeton sayısı (total_token_count)

Bir sonraki etkileşiminizin ne kadar büyük olacağını anlamak için count_tokens işlevini çağırdığınızda bunu geçmişe eklemeniz gerekir.

Python

from google import genai
from google.genai import types

client = genai.Client()

chat = client.chats.create(
    model="gemini-3-flash-preview",
    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-flash-preview", 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-flash-preview", 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-flash-preview",
    history: history,
  });

  const countTokensResponse = await ai.models.countTokens({
    model: "gemini-3-flash-preview",
    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-flash-preview",
    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-flash-preview", nil, history)
if err != nil {
  log.Fatal(err)
}

firstTokenResp, err := client.Models.CountTokens(ctx, "gemini-3-flash-preview", 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-flash-preview", hist, nil)
if err != nil {
  log.Fatal(err)
}
fmt.Println(secondTokenResp.TotalTokens)

Çok formatlı parçaları sayma

Metin, resim dosyaları ve diğer metin dışı biçimler de dahil olmak üzere Gemini API'ye yapılan tüm girişler jetonlaştırılır. Gemini API tarafından işleme sırasında çok formatlı girişin jetonlaştırılmasıyla ilgili aşağıdaki üst düzey önemli noktaları göz önünde bulundurun:

  • Her iki boyutu da <=384 piksel olan resim girişleri 258 jeton olarak sayılır. Bir veya iki boyutta daha büyük olan resimler, gerektiğinde 768x768 piksellik parçalar halinde kırpılır ve ölçeklendirilir. Bu parçaların her biri 258 jeton olarak sayılır.

  • Video ve ses dosyaları, aşağıdaki sabit oranlarda jetonlara dönüştürülür: Video: Saniyede 263 jeton, ses: saniyede 32 jeton.

Medya çözünürlükleri

Gemini 3 Pro ve 3 Flash önizleme modelleri, media_resolution parametresiyle çok formatlı görüntü işleme üzerinde ayrıntılı kontrol sağlar. media_resolution parametresi, giriş resim veya video karesi başına ayrılan maksimum jeton sayısını belirler. Daha yüksek çözünürlükler, modelin küçük metinleri okuma veya küçük ayrıntıları tanımlama becerisini artırır ancak jeton kullanımını ve gecikmeyi de artırır.

Parametre ve jeton hesaplamalarını nasıl etkileyebileceği hakkında daha fazla bilgi için medya çözünürlüğü kılavuzuna bakın.

Resim dosyaları

count_tokens işlevini metin ve resim girişiyle çağırırsanız yalnızca girişte (total_tokens) metin ve resmin birleştirilmiş jeton sayısını döndürür. İsteklerinizin boyutunu kontrol etmek için generate_content işlevini çağırmadan önce bu çağrıyı yapabilirsiniz. İsteğe bağlı olarak metin ve dosya üzerinde ayrı ayrı count_tokens işlevini de çağırabilirsiniz.

Diğer bir seçenek ise generate_content'ı arayıp usage_metadata özelliğini response nesnesinde kullanarak aşağıdakileri elde etmektir:

  • Giriş (prompt_token_count), önbelleğe alınmış içerik (cached_content_token_count) ve çıkışın (candidates_token_count) ayrı jeton sayıları
  • Düşünme süreci için jeton sayısı (thoughts_token_count)
  • Hem girişte hem de çıkışta toplam jeton sayısı (total_token_count)

File API'den yüklenen bir görüntünün kullanıldığı örnek:

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-flash-preview", contents=[prompt, your_image_file]
    )
)

response = client.models.generate_content(
    model="gemini-3-flash-preview", 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-flash-preview",
    contents: createUserContent([
      prompt,
      createPartFromUri(organ.uri, organ.mimeType),
    ]),
  });
  console.log(countTokensResponse.totalTokens);

  const generateResponse = await ai.models.generateContent({
    model: "gemini-3-flash-preview",
    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-flash-preview", contents, nil)
if err != nil {
  log.Fatal(err)
}
fmt.Println("Multimodal image token count:", tokenResp.TotalTokens)

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

Resmi satır içi veri olarak sağlayan örnek:

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-flash-preview", contents=[prompt, your_image_file]
    )
)

response = client.models.generate_content(
    model="gemini-3-flash-preview", 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-flash-preview",
    contents: contents,
  });
  console.log(countTokensResponse.totalTokens);

  const generateResponse = await ai.models.generateContent({
    model: "gemini-3-flash-preview",
    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-flash-preview", contents, nil)
if err != nil {
  log.Fatal(err)
}
fmt.Println("Multimodal image token count:", tokenResp.TotalTokens)

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

Video veya ses dosyaları

Ses ve video, aşağıdaki sabit oranlarda jetonlara dönüştürülür:

  • Video: Saniyede 263 jeton
  • Ses: Saniyede 32 jeton

count_tokens işlevini metin ve video/ses girişiyle çağırırsanız yalnızca girişteki metin ve video/ses dosyasının birleştirilmiş jeton sayısını döndürür (total_tokens). İsteklerinizin boyutunu kontrol etmek için generate_content işlevini çağırmadan önce bu çağrıyı yapabilirsiniz. İsterseniz metni ve dosyayı ayrı ayrı count_tokens ile de çağırabilirsiniz.

Diğer bir seçenek ise generate_content'ı arayıp usage_metadata özelliğini response nesnesinde kullanarak aşağıdakileri elde etmektir:

  • Giriş (prompt_token_count), önbelleğe alınmış içerik (cached_content_token_count) ve çıkışın (candidates_token_count) ayrı jeton sayıları
  • Düşünme süreci için jeton sayısı (thoughts_token_count)

  • Hem girişte hem de çıkışta toplam jeton sayısıdır (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-flash-preview", contents=[prompt, your_file]
    )
)

response = client.models.generate_content(
    model="gemini-3-flash-preview", 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-flash-preview",
    contents: createUserContent([
      prompt,
      createPartFromUri(videoFile.uri, videoFile.mimeType),
    ]),
  });
  console.log(countTokensResponse.totalTokens);

  const generateResponse = await ai.models.generateContent({
    model: "gemini-3-flash-preview",
    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-flash-preview", 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-flash-preview", contents, nil)
if err != nil {
  log.Fatal(err)
}
usageMetadata, err := json.MarshalIndent(response.UsageMetadata, "", "  ")
if err != nil {
  log.Fatal(err)
}
fmt.Println(string(usageMetadata))

Bağlam pencereleri

Gemini API aracılığıyla kullanılabilen modellerin bağlam pencereleri, jetonlarla ölçülür. Bağlam penceresi, ne kadar giriş sağlayabileceğinizi ve modelin ne kadar çıkış oluşturabileceğini tanımlar. models.get uç noktasını çağırarak veya modeller belgelerine bakarak bağlam penceresinin boyutunu belirleyebilirsiniz.

Python

from google import genai

client = genai.Client()
model_info = client.models.get(model="gemini-3-flash-preview")
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-flash-preview'});
  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-flash-preview")
if err != nil {
  log.Fatal(err)
}
fmt.Println("input token limit:", modelInfo.InputTokenLimit)
fmt.Println("output token limit:", modelInfo.OutputTokenLimit)