Comprender y contar tokens


Gemini y otros modelos de IA generativa procesan las entradas y salidas con un nivel de detalle llamado token.

Información acerca de los tokens

Los tokens pueden ser caracteres individuales, como z, o palabras completas, como cat. Las palabras largas se dividen en varios tokens. El conjunto de todos los tokens que usa el modelo se llama vocabulario, y el proceso de dividir el texto en tokens se denomina tokenización.

En el caso de los modelos Gemini, un token equivale a cerca de 4 caracteres. 100 tokens equivalen a entre 60 y 80 palabras en inglés.

Cuando la facturación está habilitada, el costo de una llamada a la API de Gemini se determina en parte por la cantidad de tokens de entrada y salida, por lo que puede ser útil saber cómo contarlos.

Cuenta tokens

Todas las entradas y salidas de la API de Gemini se tokenizan, incluidos el texto, los archivos de imagen y otras modalidades que no son de texto.

Puedes contar tokens de las siguientes maneras:

  • Llama a countTokens con la entrada de la solicitud.
    Esto muestra la cantidad total de tokens en solo la entrada. Puedes realizar esta llamada antes de enviar la entrada al modelo para verificar el tamaño de tus solicitudes.

  • Usa el atributo usageMetadata en el objeto response después de llamar a generate_content.
    Esto muestra la cantidad total de tokens en la entrada y la salida: totalTokenCount.
    También muestra los recuentos de tokens de entrada y salida por separado: promptTokenCount (tokens de entrada) y candidatesTokenCount (tokens de salida).

Cuenta los tokens de texto

Si llamas a countTokens con una entrada de solo texto, muestra el recuento de tokens del texto en solo la entrada (totalTokens). Puedes realizar esta llamada antes de llamar a generateContent para verificar el tamaño de tus solicitudes.

Otra opción es llamar a generateContent y, luego, usar el atributo usageMetadata en el objeto response para obtener lo siguiente:

  • Los recuentos de tokens separados de la entrada (promptTokenCount) y la salida (candidatesTokenCount)
  • Es la cantidad total de tokens en la entrada y la salida (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

Cuenta los tokens de varios turnos (chat)

Si llamas a countTokens con el historial de chat, se muestra el recuento total de tokens del texto de cada rol en el chat (totalTokens).

Otra opción es llamar a sendMessage y, luego, usar el atributo usageMetadata en el objeto response para obtener lo siguiente:

  • Los recuentos de tokens separados de la entrada (promptTokenCount) y la salida (candidatesTokenCount)
  • Es la cantidad total de tokens en la entrada y la salida (totalTokenCount).

Para comprender qué tan grande será tu próximo turno de conversación, debes adjuntarlo al historial cuando llames a 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

Cuenta tokens multimodales

Toda la entrada a la API de Gemini se segmenta, incluidos el texto, los archivos de imagen y otras modalidades que no son de texto. Ten en cuenta los siguientes puntos clave de alto nivel sobre la tokenización de la entrada multimodal durante el procesamiento de la API de Gemini:

  • Con Gemini 2.0, las entradas de imagen con ambas dimensiones <=384 píxeles se cuentan como 258 tokens. Las imágenes más grandes en una o ambas dimensiones se recortan y se ajustan según sea necesario en tarjetas de 768 × 768 píxeles, cada una de las cuales se cuenta como 258 tokens. Antes de Gemini 2.0, las imágenes usaban 258 tokens fijos.

  • Los archivos de audio y video se convierten en tokens a las siguientes tasas fijas: video a 263 tokens por segundo y audio a 32 tokens por segundo.

Archivos de imagen

Si llamas a countTokens con una entrada de texto y una imagen, se muestra el recuento de tokens combinados del texto y la imagen en solo la entrada (totalTokens). Puedes realizar esta llamada antes de llamar a generateContent para verificar el tamaño de tus solicitudes. De manera opcional, también puedes llamar a countTokens en el texto y el archivo por separado.

Otra opción es llamar a generateContent y, luego, usar el atributo usageMetadata en el objeto response para obtener lo siguiente:

  • Los recuentos de tokens separados de la entrada (promptTokenCount) y la salida (candidatesTokenCount)
  • Es la cantidad total de tokens en la entrada y la salida (totalTokenCount).

Ejemplo que usa una imagen subida desde la API de Files:

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

Ejemplo que proporciona la imagen como datos intercalados:

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

Archivos de audio o video

El audio y el video se convierten en tokens con las siguientes tarifas fijas:

  • Video: 263 tokens por segundo
  • Audio: 32 tokens por segundo

Si llamas a countTokens con una entrada de texto y video/audio, se muestra el recuento de tokens combinados del texto y el archivo de video/audio en solo la entrada (totalTokens). Puedes realizar esta llamada antes de llamar a generateContent para verificar el tamaño de tus solicitudes. De manera opcional, también puedes llamar a countTokens en el texto y el archivo por separado.

Otra opción es llamar a generateContent y, luego, usar el atributo usageMetadata en el objeto response para obtener lo siguiente:

  • Los recuentos de tokens separados de la entrada (promptTokenCount) y la salida (candidatesTokenCount)
  • Es la cantidad total de tokens en la entrada y la salida (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

Instrucciones y herramientas del sistema

Las instrucciones y herramientas del sistema también se consideran para el recuento total de tokens de la entrada.

Si usas instrucciones del sistema, el recuento de totalTokens aumenta para reflejar la adición de systemInstruction.

Si usas llamadas a función, el recuento de totalTokens aumenta para reflejar la adición de tools.