Entender e contar tokens

O Gemini e outros modelos de IA generativa processam entradas e saídas em uma granularidade chamada token.

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.

Sobre 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.

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. Por isso, 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 count_tokens com a entrada da solicitação. Retorna o número total de tokens apenas na entrada. Faça essa chamada antes de enviar a entrada para verificar o tamanho das suas solicitações.

  • Use o usage na resposta da interação. Retorna contagens de tokens para entrada (total_input_tokens), saída (total_output_tokens), pensamento (total_thought_tokens), conteúdo em cache (total_cached_tokens), uso de ferramentas (total_tool_use_tokens) e total (total_tokens).

Contar tokens de texto

Python

# This will only work for SDK newer than 2.0.0
from google import genai

client = genai.Client()
prompt = "The quick brown fox jumps over the lazy dog."

# Count tokens before sending
total_tokens = client.models.count_tokens(
    model="gemini-3.6-flash",
    contents=prompt
)
print("total_tokens:", total_tokens.total_tokens)

# Get usage from interaction
interaction = client.interactions.create(
    model="gemini-3.6-flash",
    input=prompt
)
print(interaction.usage)

JavaScript

// This will only work for SDK newer than 2.0.0
import { GoogleGenAI } from '@google/genai';

const client = new GoogleGenAI({});
const prompt = "The quick brown fox jumps over the lazy dog.";

// Count tokens before sending
const countResponse = await client.models.countTokens({
    model