Contar tokens para modelos do Gemini

Gemini modelos processam a entrada e a 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 divisão do texto em tokens é chamado de tokenização.

Para os 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 do comando 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.

Modelos compatíveis

• gemini-3.1-pro-preview
• gemini-3-flash-preview
• gemini-3.1-flash-lite-preview
• gemini-3-pro-image-preview
• gemini-3.1-flash-image-preview
• 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)

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. Confira as opções para contar tokens:

Verifique a contagem de tokens apenas das 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 apenas da entrada

Verifique a contagem de tokens das solicitações e respostas.

Acesse o atributo usageMetadata no objeto de resposta. Isso inclui:

• prompt_token_count: contagem de tokens da entrada
• candidates_token_count: contagem de tokens da saída (não inclui tokens de pensamento)
• thoughts_token_count: contagem de tokens de pensamento usados para gerar a resposta
• total_token_count: contagem total de tokens para ambas as entradas e saídas (inclui tokens de pensamento)

Ao transmitir a saída, o usageMetadata atributo só aparece no último bloco do stream. Ele é nil para blocos intermediários.

Confira os pontos a seguir sobre as opções acima:

• Elas não contam o número de imagens de entrada ou o número de segundos em arquivos de entrada de áudio ou vídeo. No entanto, a contagem de tokens para cada uma dessas modalidades será correlacionada com esses valores.
• A contagem de tokens de entrada inclui o comando (texto e arquivos de entrada), bem como instruções e ferramentas do sistema.
• A contagem de tokens de saída não inclui tokens de pensamento. Eles são fornecidos em um campo separado.
• Revise as informações adicionais específicas para cada tipo de solicitação mais adiante nesta página.
• Os modelos Gemini Live API não oferecem suporte a countTokens. Além disso, Firebase AI Logic ainda não oferece suporte ao atributo usageMetadata na resposta dos modelos Live API, mas isso será lançado em breve!

Preços dessas opções

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

• Uso do atributo usageMetadata: esse atributo é sempre retornado como parte da resposta e não gera tokens ou cobranças.

Informações adicionais

Confira algumas informações adicionais 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 para chamar countTokens ao usar o chat:

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

Contar tokens de entrada multimodais

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

• Você pode chamar countTokens no texto e no arquivo separadamente.
• Para ambas as opções de contagem de tokens, você vai receber a mesma contagem de tokens, seja fornecendo o arquivo como dados inline ou usando o URL.

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 é contada 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 áudio e vídeo 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. Portanto, cada página de um PDF é tokenizada da mesma forma que uma imagem.