Entender e contar tokens


O Gemini e outros modelos de IA generativa processam a entrada e a saída com uma granularidade chamada token.

Sobre os tokens

Os tokens podem ser caracteres únicos, como z, ou palavras inteiras, como cat. Palavras longas são divididas em vários tokens. O conjunto de todos os tokens usados pelo modelo é chamado de vocabulário, e o processo de dividir o texto em tokens é chamado de tokenização.

Para modelos do Gemini, um token equivale a cerca de quatro caracteres. 100 tokens equivalem a cerca de 60 a 80 palavras em inglês.

Quando o faturamento está ativado, o custo de uma chamada para a API Gemini é determinado em parte pelo número de tokens de entrada e saída. Portanto, saber como contar tokens pode ser útil.

Contar Tokens

Todas as entradas e saídas da API Gemini são tokenizadas, incluindo texto, arquivos de imagem e outras modalidades que não são de texto.

É possível contar tokens das seguintes maneiras:

  • Chame countTokens com a entrada da solicitação.
    Retorna o número total de tokens na entrada somente. Você pode fazer essa chamada antes de enviar a entrada para o modelo para verificar o tamanho das solicitações.

  • Use o atributo usageMetadata no objeto response depois de chamar generate_content.
    Isso retorna o número total de tokens em entrada e saída: totalTokenCount.
    Ele também retorna as contagens de tokens de entrada e saída separadamente: promptTokenCount (tokens de entrada) e candidatesTokenCount (tokens de saída).

Contar tokens de texto

Se você chamar countTokens com uma entrada somente de texto, ela retornará a contagem de tokens do texto em somente a entrada (totalTokens). É possível fazer essa chamada antes de chamar generateContent para verificar o tamanho das suas solicitações.

Outra opção é chamar generateContent e usar o atributo usageMetadata no objeto response para receber o seguinte:

  • As contagens de tokens separadas da entrada (promptTokenCount) e da saída (candidatesTokenCount)
  • O número total de tokens na entrada e na saída (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

Contagem de tokens de chat com vários turnos

Se você chamar countTokens com o histórico de chat, ele vai retornar a contagem total de tokens do texto de cada função no chat (totalTokens).

Outra opção é chamar sendMessage e usar o atributo usageMetadata no objeto response para receber o seguinte:

  • As contagens de tokens separadas da entrada (promptTokenCount) e da saída (candidatesTokenCount)
  • O número total de tokens na entrada e na saída (totalTokenCount)

Para entender o tamanho da sua próxima vez de conversa, você precisa adicioná-la ao histórico quando chamar 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

Contar tokens multimodais

Todas as entradas na API Gemini são tokenizadas, incluindo texto, arquivos de imagem e outras modalidades não textuais. Confira os seguintes pontos-chave de alto nível sobre a tokenização de entrada multimodal durante o processamento pela API Gemini:

  • Com o Gemini 2.0, as entradas de imagem com as duas dimensões <=384 pixels são contadas como 258 tokens. As imagens maiores em uma ou ambas as dimensões são cortadas e redimensionadas conforme necessário em blocos de 768 x 768 pixels, cada um contado como 258 tokens. Antes do Gemini 2.0, as imagens usavam 258 tokens fixos.

  • Os arquivos de vídeo e áudio são convertidos em tokens nas seguintes taxas fixas: vídeo a 263 tokens por segundo e áudio a 32 tokens por segundo.

Arquivos de imagem

Se você chamar countTokens com uma entrada de texto e imagem, ela retornará a contagem de tokens combinada do texto e da imagem apenas na entrada (totalTokens). Você pode fazer essa chamada antes de chamar generateContent para verificar o tamanho das solicitações. Também é possível chamar countTokens no texto e no arquivo separadamente.

Outra opção é chamar generateContent e usar o atributo usageMetadata no objeto response para receber o seguinte:

  • As contagens de tokens separadas da entrada (promptTokenCount) e da saída (candidatesTokenCount)
  • O número total de tokens na entrada e na saída (totalTokenCount)

Exemplo que usa uma imagem enviada pela 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

Exemplo que fornece a imagem como dados inline:

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

Arquivos de áudio ou vídeo

O áudio e o vídeo são convertidos em tokens com as seguintes taxas fixas:

  • Vídeo: 263 tokens por segundo
  • Áudio: 32 tokens por segundo

Se você chamar countTokens com uma entrada de texto e vídeo/áudio, ela retornará a contagem de tokens combinada do texto e do arquivo de vídeo/áudio apenas na entrada (totalTokens). É possível fazer essa chamada antes de chamar generateContent para verificar o tamanho das suas solicitações. Também é possível chamar countTokens no texto e no arquivo separadamente.

Outra opção é chamar generateContent e usar o atributo usageMetadata no objeto response para receber o seguinte:

  • As contagens de tokens separadas da entrada (promptTokenCount) e da saída (candidatesTokenCount)
  • O número total de tokens na entrada e na saída (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

Instruções e ferramentas do sistema

As instruções e ferramentas do sistema também são contabilizadas na contagem total de tokens da entrada.

Se você usar instruções do sistema, a contagem de totalTokens vai aumentar para refletir a adição de systemInstruction.

Se você usar a chamada de função, a contagem de totalTokens vai aumentar para refletir a adição de tools.