Comprendre et compter les jetons


Gemini et d'autres modèles d'IA générative traitent les entrées et les sorties à une granularité appelée jeton.

À propos des jetons

Les jetons peuvent être des caractères uniques comme z ou des mots entiers comme cat. Les mots longs sont divisés en plusieurs jetons. L'ensemble de tous les jetons utilisés par le modèle est appelé "vocabulaire", et le processus de division du texte en jetons est appelé tokenisation.

Pour les modèles Gemini, un jeton équivaut à environ quatre caractères. 100 jetons correspondent à environ 60-80 mots en anglais.

Lorsque la facturation est activée, le coût d'un appel à l'API Gemini est déterminé en partie par le nombre de jetons d'entrée et de sortie. Il peut donc être utile de savoir compter les jetons.

Compter les jetons

Toutes les entrées et sorties de l'API Gemini sont tokenisées, y compris le texte, les fichiers image et les autres modalités non textuelles.

Vous pouvez compter les jetons de différentes manières:

  • Appelez countTokens avec l'entrée de la requête.
    Cette valeur renvoie le nombre total de jetons dans l'entrée uniquement. Vous pouvez effectuer cet appel avant d'envoyer l'entrée au modèle pour vérifier la taille de vos requêtes.

  • Utilisez l'attribut usageMetadata sur l'objet response après avoir appelé generate_content.
    Cette fonction renvoie le nombre total de jetons dans l'entrée et la sortie : totalTokenCount.
    Il renvoie également les nombres de jetons d'entrée et de sortie séparément : promptTokenCount (jetons d'entrée) et candidatesTokenCount (jetons de sortie).

Compter les jetons de texte

Si vous appelez countTokens avec une entrée textuelle uniquement, il renvoie le nombre de jetons du texte dans l'entrée uniquement (totalTokens). Vous pouvez effectuer cet appel avant d'appeler generateContent pour vérifier la taille de vos requêtes.

Vous pouvez également appeler generateContent, puis utiliser l'attribut usageMetadata sur l'objet response pour obtenir ce qui suit:

  • Nombres de jetons distincts de l'entrée (promptTokenCount) et de la sortie (candidatesTokenCount)
  • Nombre total de jetons dans l'entrée et la sortie (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

Compter les jetons multitours (chat)

Si vous appelez countTokens avec l'historique des discussions, il renvoie le nombre total de jetons du texte de chaque rôle dans la discussion (totalTokens).

Vous pouvez également appeler sendMessage, puis utiliser l'attribut usageMetadata sur l'objet response pour obtenir ce qui suit:

  • Nombres de jetons distincts de l'entrée (promptTokenCount) et de la sortie (candidatesTokenCount)
  • Nombre total de jetons dans l'entrée et la sortie (totalTokenCount)

Pour comprendre la taille de votre prochaine prise de parole, vous devez l'ajouter à l'historique lorsque vous appelez 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

Compter les jetons multimodales

Toutes les entrées de l'API Gemini sont tokenisées, y compris le texte, les fichiers image et les autres modalités non textuelles. Notez les points clés suivants concernant la tokenisation des entrées multimodales lors du traitement par l'API Gemini:

  • Avec Gemini 2.0, les entrées d'images dont les deux dimensions sont inférieures ou égales à 384 pixels sont comptabilisées comme 258 jetons. Les images dont une ou les deux dimensions sont plus grandes sont recadrées et redimensionnées si nécessaire en tuiles de 768 x 768 pixels, chacune comptant pour 258 jetons. Avant Gemini 2.0, les images utilisaient 258 jetons fixes.

  • Les fichiers vidéo et audio sont convertis en jetons aux débits fixes suivants : 263 jetons par seconde pour la vidéo et 32 jetons par seconde pour l'audio.

Fichiers image

Si vous appelez countTokens avec une entrée texte et image, il renvoie le nombre de jetons combinés du texte et de l'image dans l'entrée uniquement (totalTokens). Vous pouvez effectuer cet appel avant d'appeler generateContent pour vérifier la taille de vos requêtes. Vous pouvez également appeler countTokens sur le texte et le fichier séparément.

Vous pouvez également appeler generateContent, puis utiliser l'attribut usageMetadata sur l'objet response pour obtenir ce qui suit:

  • Nombres de jetons distincts de l'entrée (promptTokenCount) et de la sortie (candidatesTokenCount)
  • Nombre total de jetons dans l'entrée et la sortie (totalTokenCount)

Exemple utilisant une image importée à partir de l'API File:

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

Exemple d'image fournie en tant que données intégrées:

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

Fichiers audio ou vidéo

L'audio et la vidéo sont convertis en jetons aux tarifs fixes suivants:

  • Vidéo: 263 jetons par seconde
  • Audio: 32 jetons par seconde

Si vous appelez countTokens avec une entrée texte et vidéo/audio, il renvoie le nombre de jetons combinés du texte et du fichier vidéo/audio dans l'entrée uniquement (totalTokens). Vous pouvez effectuer cet appel avant d'appeler generateContent pour vérifier la taille de vos requêtes. Vous pouvez également appeler countTokens sur le texte et le fichier séparément.

Vous pouvez également appeler generateContent, puis utiliser l'attribut usageMetadata sur l'objet response pour obtenir ce qui suit:

  • Nombres de jetons distincts de l'entrée (promptTokenCount) et de la sortie (candidatesTokenCount)
  • Nombre total de jetons dans l'entrée et la sortie (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

Instructions et outils système

Les instructions et outils système sont également comptabilisés dans le nombre total de jetons pour l'entrée.

Si vous utilisez des instructions système, le nombre de totalTokens augmente pour refléter l'ajout de systemInstruction.

Si vous utilisez l'appel de fonction, le nombre de totalTokens augmente pour refléter l'ajout de tools.