Contar tokens para modelos do Gemini

Os modelos Gemini processam entrada e saída em unidades chamadas 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 Gemini, um token equivale a cerca de quatro caracteres. 100 tokens equivalem a cerca de 60 a 80 palavras em inglês.

Cada modelo tem um número máximo de tokens que pode ser processado em um comando e uma resposta. Saber a contagem de tokens da solicitação permite saber se você excedeu esse limite. Além disso, o custo de uma solicitação é determinado em parte pelo número de tokens de entrada e saída. Portanto, saber como contar tokens pode ser útil.

Os modelos Gemini 1.0 e 1.5 também ofereciam uma contagem e preços de "caracteres faturáveis", mas como esses modelos foram desativados ou serão desativados em breve, esta página não descreve nada sobre caracteres faturáveis.

Modelos compatíveis

  • gemini-2.5-pro
  • gemini-2.5-flash
  • gemini-2.5-flash-lite
  • gemini-2.0-flash-001 (e o alias atualizado automaticamente gemini-2.0-flash)
  • gemini-2.0-flash-lite-001 (e o alias atualizado automaticamente gemini-2.0-flash-lite)
  • gemini-2.0-flash-preview-image-generation

Opções para contar tokens

Todas as entradas e saídas do Gemini API são tokenizadas, incluindo texto, arquivos de imagem e outras modalidades não textuais. Estas são as opções para contar tokens:

Verifique a contagem de tokens apenas das suas solicitações (antes de enviá-las ao modelo).
Chame countTokens com a entrada da solicitação antes de enviá-la ao modelo. Isso retorna:
  • total_tokens: contagem de tokens da entrada apenas
Verifique a contagem de tokens das suas solicitações e respostas.
Use o atributo usageMetadata no objeto de resposta. Isso inclui:
  • prompt_token_count: contagem de tokens apenas da entrada
  • candidates_token_count: contagem de tokens da saída apenas (não inclui tokens de pensamento)
  • thoughts_token_count: contagem de tokens de qualquer token de pensamento usado para gerar a resposta.
  • total_token_count: contagem total de tokens para entrada e saída (inclui tokens de pensamento)

Ao transmitir a saída, o atributo usageMetadata só aparece no último bloco do stream. É nil para pedaços intermediários.

Observações sobre as opções acima:

  • Elas não contam o número de imagens de entrada nem o número de segundos em arquivos de entrada de vídeo ou áudio. No entanto, a contagem de tokens para cada uma dessas modalidades vai se correlacionar com esses valores.
  • A contagem de tokens de entrada inclui o comando (texto e arquivos de entrada), além de instruções e ferramentas do sistema.
  • A contagem de tokens de saída não inclui tokens de pensamento, que são fornecidos em um campo separado.
  • Confira as informações adicionais específicas para cada tipo de solicitação mais adiante nesta página.

Preços dessas opções

  • Chamada de countTokens: não há cobrança pela chamada de countTokens (API Count Tokens). A cota máxima para a API Count Tokens é de 3.000 solicitações por minuto (RPM).

  • Usando o atributo usageMetadata: esse atributo é sempre retornado como parte da resposta e não gera tokens nem custos.

Mais informações

Confira outras informações ao trabalhar com tipos específicos de solicitações.

Contar tokens de entrada de texto

Nenhuma informação adicional.

Contar tokens multiturno (chat)

Observe o seguinte ao chamar countTokens usando o chat:

  • Se você chamar countTokens com o histórico de chat, ele vai retornar a contagem total de tokens de ambas as funções no chat (total_tokens).
  • Para entender o tamanho da sua próxima interação, adicione-a ao histórico ao chamar countTokens.

Contar tokens de entrada multimodal

Observe os seguintes pontos sobre a contagem de tokens com entrada multimodal:

  • Você pode chamar countTokens no texto e no arquivo separadamente.
  • Para as duas opções de contagem de tokens, você vai receber o mesmo número, seja fornecendo o arquivo como dados inline ou usando o URL dele.

Arquivos de entrada de imagem

Os arquivos de entrada de imagem são convertidos em tokens com base nas dimensões:

  • Entradas de imagem com ambas as dimensões menores ou iguais a 384 pixels: cada imagem é contabilizada como 258 tokens.
  • Entradas de imagem maiores em uma ou ambas as dimensões: cada imagem é cortada e dimensionada conforme necessário em blocos de 768 x 768 pixels, e cada bloco é contado como 258 tokens.

Arquivos de entrada de áudio e vídeo

Os arquivos de entrada de vídeo e áudio são convertidos em tokens nas seguintes taxas fixas:

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

Arquivos de entrada de documentos (como PDFs)

Os arquivos de entrada em PDF são tratados como imagens. Por isso, cada página de um PDF é tokenizada da mesma forma que uma imagem.