Comprendi e conteggia i token

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

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

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.

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


Contare i token

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

Puoi contare i token nei seguenti modi:

  • Chiama countTokens con l'input della richiesta.
    Questo valore restituisce il numero totale di token solo nell'input. Puoi effettuare questa chiamata prima di inviare l'input al modello per verificare le dimensioni delle tue richieste.

  • Utilizza l'attributo usageMetadata sull'oggetto response dopo aver chiamato generate_content.
    Restituisce il numero totale di token sia nell'input che nell'output: totalTokenCount.
    Restituisce anche il conteggio dei token di input e output separatamente: promptTokenCount (token di input) e candidatesTokenCount (token di output). Se utilizzi la memorizzazione nella cache del contesto, il conteggio dei token memorizzati nella cache sarà in cachedContentTokenCount.

    Se utilizzi un modello di pensiero come quelli 2.5, i token utilizzati durante il processo di pensiero vengono restituiti in thoughtsTokenCount.

Conteggiare i token di testo

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

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

  • I conteggi separati dei token dell'input (promptTokenCount), dei contenuti memorizzati nella cache (cachedContentTokenCount) e dell'output (candidatesTokenCount)
  • Il conteggio dei token per il processo di pensiero (thoughtsTokenCount)
  • Il numero totale di token sia nell'input che nell'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 della chat, viene restituito il conteggio totale dei 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 separati dei token dell'input (promptTokenCount), dei contenuti memorizzati nella cache (cachedContentTokenCount) e dell'output (candidatesTokenCount)
  • Il conteggio dei token per il processo di pensiero (thoughtsTokenCount)
  • Il numero totale di token sia nell'input che nell'output (totalTokenCount)

Per capire quanto sarà grande il tuo prossimo turno conversazionale, 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 dell'API Gemini vengono tokenizzati, inclusi testo, file immagine e altre modalità non testuali. 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 scalate in base alle necessità in riquadri di 768 x 768 pixel, ognuno dei quali viene 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 tariffe fisse: video a 263 token al secondo e audio a 32 token al secondo.

Risoluzioni dei contenuti multimediali

L'anteprima di Gemini 3 Pro introduce un controllo granulare dell'elaborazione della visione multimodale con il parametro media_resolution. Il parametro media_resolution determina il numero massimo di token allocati per ogni immagine di input o frame video. Risoluzioni più elevate migliorano la capacità del modello di leggere testi piccoli o identificare piccoli dettagli, ma aumentano l'utilizzo di token e la latenza.

Per maggiori dettagli sul parametro e su come può influire sui calcoli dei token, consulta la guida alla risoluzione dei contenuti multimediali.

File immagine

Se chiami countTokens con un input di testo e immagine, restituisce il conteggio dei token combinato del testo e dell'immagine solo nell'input (totalTokens). Puoi effettuare questa chiamata prima di chiamare generateContent per controllare le dimensioni delle tue 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 separati dei token dell'input (promptTokenCount), dei contenuti memorizzati nella cache (cachedContentTokenCount) e dell'output (candidatesTokenCount)
  • Il conteggio dei token per il processo di pensiero (thoughtsTokenCount)
  • Il numero totale di token sia nell'input che nell'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

Audio e 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, restituisce il conteggio dei token combinato del testo e del file video/audio solo nell'input (totalTokens). Puoi effettuare questa chiamata prima di chiamare generateContent per controllare le dimensioni delle tue richieste. Puoi anche chiamare facoltativamente 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 separati dei token dell'input (promptTokenCount), dei contenuti memorizzati nella cache (cachedContentTokenCount) e dell'output (candidatesTokenCount)
  • Il conteggio dei token per il processo di pensiero (thoughtsTokenCount)
  • Il numero totale di token sia nell'input che nell'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 di sistema e strumenti

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 la chiamata di funzione, il conteggio di totalTokens aumenta per riflettere l'aggiunta di tools.