Comprendi e conteggia i token


Gemini e altri modelli di IA generativa elaborano input e output con una granularità chiamata token.

Informazioni sui token

I token possono essere singoli caratteri come z o intere parole come cat. Le parole lunghe vengono suddivise in più token. L'insieme di tutti i token utilizzati dal modello è chiamato vocabolario e il processo di suddivisione del testo in token è chiamato tokenizzazione.

Per i modelli Gemini, un token equivale a circa 4 caratteri. 100 token corrispondono a circa 60-80 parole in inglese.

Quando la fatturazione è attivata, il costo di una chiamata all'API Gemini è determinato in parte dal numero di token di input e di output, quindi sapere come conteggiare i token può essere utile.

Contare i token

Tutti gli input e gli output dell'API Gemini sono tokenizzati, inclusi testo, file di immagini e altre modalità non di testo.

Puoi conteggiare i token nei seguenti modi:

  • Chiama countTokens con i dati della richiesta.
    Restituisce il numero totale di token solo nell'input. Puoi effettuare questa chiamata prima di inviare l'input al modello per controllare le dimensioni delle richieste.

  • Utilizza l'attributo usageMetadata sull'oggetto response dopo aver chiamato generate_content.
    Questo restituisce il numero totale di token sia nell'input che nell'output: totalTokenCount.
    Restituisce anche i conteggi dei token di input e di output separatamente: promptTokenCount (token di input) e candidatesTokenCount (token di output).

Contare i token di testo

Se chiami countTokens con un input di solo testo, viene restituito il conteggio dei token del testo solo nell'input (totalTokens). Puoi effettuare questa chiamata prima di chiamare generateContent per controllare le dimensioni delle richieste.

Un'altra opzione è chiamare generateContent e poi utilizzare l'attributo usageMetadata nell'oggetto response per ottenere quanto segue:

  • I conteggi dei token separati dell'input (promptTokenCount) e dell'output (candidatesTokenCount)
  • Il numero totale di token sia in input che in 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

Contare i token multi-turno (chat)

Se chiami countTokens con la cronologia chat, viene restituito il numero totale di token del testo di ogni ruolo nella chat (totalTokens).

Un'altra opzione è chiamare sendMessage e poi utilizzare l'attributo usageMetadata nell'oggetto response per ottenere quanto segue:

  • I conteggi dei token separati dell'input (promptTokenCount) e dell'output (candidatesTokenCount)
  • Il numero totale di token sia in input che in output (totalTokenCount)

Per capire quanto sarà grande il tuo prossimo turno di conversazione, devi aggiungerlo alla cronologia quando chiami 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

Contare i token multimodali

Tutti gli input all'API Gemini sono tokenizzati, inclusi testo, file immagine e altre modalità non di testo. Tieni presente i seguenti punti chiave di alto livello sulla tokenizzazione dell'input multimodale durante l'elaborazione da parte dell'API Gemini:

  • Con Gemini 2.0, gli input di immagini con entrambe le dimensioni <=384 pixel vengono conteggiati come 258 token. Le immagini più grandi in una o entrambe le dimensioni vengono ritagliate e ridimensionate in base alle esigenze in riquadri di 768 x 768 pixel, ciascuno conteggiato come 258 token. Prima di Gemini 2.0, le immagini utilizzavano 258 token fissi.

  • I file video e audio vengono convertiti in token alle seguenti frequenze fisse: video a 263 token al secondo e audio a 32 token al secondo.

File immagine

Se chiami countTokens con un input di testo e immagine, viene restituito il conteggio combinato dei token del testo e dell'immagine solo nell'input (totalTokens). Puoi effettuare questa chiamata prima di chiamare generateContent per controllare le dimensioni delle richieste. Se vuoi, puoi anche chiamare countTokens sul testo e sul file separatamente.

Un'altra opzione è chiamare generateContent e poi utilizzare l'attributo usageMetadata nell'oggetto response per ottenere quanto segue:

  • I conteggi dei token separati dell'input (promptTokenCount) e dell'output (candidatesTokenCount)
  • Il numero totale di token sia in input che in output (totalTokenCount)

Esempio che utilizza un'immagine caricata dall'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

Esempio che fornisce l'immagine come dati in linea:

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

L'audio e il video vengono convertiti in token alle seguenti tariffe fisse:

  • Video: 263 token al secondo
  • Audio: 32 token al secondo

Se chiami countTokens con un input di testo e video/audio, viene restituito il conteggio combinato dei token del testo e del file video/audio solo nell'input (totalTokens). Puoi effettuare questa chiamata prima di chiamare generateContent per controllare le dimensioni delle richieste. Se vuoi, puoi anche chiamare countTokens sul testo e sul file separatamente.

Un'altra opzione è chiamare generateContent e poi utilizzare l'attributo usageMetadata nell'oggetto response per ottenere quanto segue:

  • I conteggi dei token separati dell'input (promptTokenCount) e dell'output (candidatesTokenCount)
  • Il numero totale di token sia in input che in 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

Istruzioni e strumenti di sistema

Anche le istruzioni e gli strumenti di sistema vengono conteggiati nel conteggio totale dei token per l'input.

Se utilizzi le istruzioni di sistema, il conteggio di totalTokens aumenta per riflettere l'aggiunta di systemInstruction.

Se utilizzi le chiamate di funzione, il conteggio di totalTokens aumenta per riflettere l'aggiunta di tools.