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.


Parça sayma

Metin, resim dosyaları ve metin dışı diğer formatlar da dahil olmak üzere Gemini API'ye yapılan tüm girişler ve API'den alınan tüm çıkışlar jetonlaştırılır.

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

  • İsteğin girişiyle countTokens işlevini çağırın.
    Bu işlev, yalnızca girişlerdeki toplam jeton sayısını döndürür. İsteklerinizin boyutunu kontrol etmek için girişi modele göndermeden önce bu aramayı yapabilirsiniz.

  • generate_content çağrıldıktan sonra response nesnesinde usageMetadata özelliğini kullanın.
    Bu işlev, hem giriş hem de çıkıştaki toplam jeton sayısını döndürür: totalTokenCount.
    Ayrıca, giriş ve çıkışın jeton sayılarını ayrı ayrı döndürür: promptTokenCount (giriş jetonları) ve candidatesTokenCount (çıkış jetonları). Bağlam önbelleğe alma özelliğini kullanıyorsanız önbelleğe alınan jeton sayısı cachedContentTokenCount içinde yer alır.

    2.5 gibi bir düşünme modelini kullanıyorsanız düşünme sürecinde kullanılan jetonlar thoughtsTokenCount içinde döndürülür.

Metin jetonlarını sayma

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

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

  • Giriş (promptTokenCount), önbelleğe alınmış içerik (cachedContentTokenCount) ve çıkışın (candidatesTokenCount) ayrı jeton sayıları
  • Düşünme süreci için jeton sayısı (thoughtsTokenCount)
  • Hem girişte hem de çıkışta toplam jeton sayısı (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

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

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

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

  • Giriş (promptTokenCount), önbelleğe alınmış içerik (cachedContentTokenCount) ve çıkışın (candidatesTokenCount) ayrı jeton sayıları
  • Düşünme süreci için jeton sayısı (thoughtsTokenCount)
  • Hem girişte hem de çıkışta toplam jeton sayısı (totalTokenCount)

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

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

Ç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:

  • Gemini 2.0 ile 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ıp ölçeklendirilir. Her parça 258 jeton olarak sayılır. Gemini 2.0'dan önce, görüntülerde sabit 258 jeton kullanılıyordu.

  • 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 Önizleme, media_resolution parametresiyle çok formatlı görüntü işleme üzerinde ayrıntılı kontrol sunar. media_resolution parametresi, giriş resmi 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ı

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

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

  • Giriş (promptTokenCount), önbelleğe alınmış içerik (cachedContentTokenCount) ve çıkışın (candidatesTokenCount) ayrı jeton sayıları
  • Düşünme süreci için jeton sayısı (thoughtsTokenCount)
  • Hem girişte hem de çıkışta toplam jeton sayısı (totalTokenCount)

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

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

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

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

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

countTokens 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 (totalTokens). İsteklerinizin boyutunu kontrol etmek için generateContent işlevini çağırmadan önce bu çağrıyı yapabilirsiniz. İsterseniz metni ve dosyayı ayrı ayrı countTokens on fonksiyonunu kullanarak da çağırabilirsiniz.

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

  • Giriş (promptTokenCount), önbelleğe alınmış içerik (cachedContentTokenCount) ve çıkışın (candidatesTokenCount) ayrı jeton sayıları
  • Düşünme süreci için jeton sayısı (thoughtsTokenCount)
  • Hem girişte hem de çıkışta toplam jeton sayısı (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

Sistem talimatları ve araçları

Sistem talimatları ve araçları da girişin toplam jeton sayısına dahil edilir.

Sistem talimatlarını kullanırsanız totalTokens sayısı, systemInstruction eklenmesini yansıtacak şekilde artar.

İşlev çağrısı kullanıyorsanız totalTokens sayısı, tools eklenmesini yansıtacak şekilde artar.