O armazenamento em cache de contexto

Em um fluxo de trabalho típico de IA, é possível transmitir os mesmos tokens de entrada repetidamente para um modelo. A API Gemini oferece dois mecanismos de armazenamento em cache diferentes:

Armazenamento em cache implícito (automático, sem garantia de economia de custos)
Armazenamento em cache explícito (garantia manual de economia de custos)

O armazenamento em cache implícito é ativado por padrão nos modelos Gemini 2.5. Se uma solicitação contiver conteúdo que é um acerto de cache, vamos repassar automaticamente a economia de custo para você.

O armazenamento em cache explícito é útil nos casos em que você quer garantir a economia de custos, mas com algum trabalho extra do desenvolvedor.

Armazenamento em cache implícito

O armazenamento em cache implícito é ativado por padrão para todos os modelos do Gemini 2.5. Transmitimos automaticamente a economia de custos se a solicitação atingir os caches. Não é necessário fazer nada para ativar esse recurso. Ela entrou em vigor em 8 de maio de 2025. A contagem mínima de tokens de entrada para o armazenamento em cache de contexto é de 1.024 para o Flash 2.5 e 2.048 para o Pro 2.5.

Para aumentar a chance de uma ocorrência de cache implícita:

Tente colocar conteúdos grandes e comuns no início do comando.
Tentar enviar solicitações com prefixo semelhante em um curto período

Você pode conferir o número de tokens que foram acertos de cache no campo usage_metadata do objeto de resposta.

Armazenamento em cache explícito

Usando o recurso de armazenamento em cache explícito da API Gemini, é possível transmitir algum conteúdo ao modelo uma vez, armazenar os tokens de entrada em cache e, em seguida, consultar os tokens em cache para solicitações subsequentes. Em alguns volumes, o uso de tokens em cache tem um custo menor do que o envio repetido do mesmo corpus de tokens.

Ao armazenar em cache um conjunto de tokens, você pode escolher por quanto tempo o cache vai existir antes que os tokens sejam excluídos automaticamente. Essa duração de armazenamento em cache é chamada de time to live (TTL). Se não for definido, o TTL será definido como 1 hora. O custo do armazenamento em cache depende do tamanho do token de entrada e de quanto tempo você quer que os tokens persistam.

Nesta seção, presumimos que você instalou um SDK do Gemini (ou o curl) e configurou uma chave de API, conforme mostrado no Guia de início rápido.

Quando usar o armazenamento em cache explícito

O armazenamento em cache de contexto é particularmente adequado para cenários em que um contexto inicial substancial é referenciado repetidamente por solicitações mais curtas. Use armazenamento em cache de contexto para casos de uso como estes:

Chatbots com instruções do sistema extensas
Análise repetitiva de arquivos de vídeo longos
Consultas recorrentes em grandes conjuntos de documentos
Análise frequente do repositório de código ou correção de bugs

Como o armazenamento em cache explícito reduz custos

O armazenamento em cache de contexto é um recurso pago projetado para reduzir os custos operacionais gerais. O faturamento é baseado nos seguintes fatores:

Contagem de tokens de cache: o número de tokens de entrada armazenados em cache, faturados com uma taxa reduzida quando incluído nos comandos subsequentes.
Duração do armazenamento:o tempo de armazenamento e cobrança dos tokens em cache (TTL), faturado com base na duração do TTL da contagem de tokens em cache. Não há limites mínimos ou máximos no TTL.
Outros fatores: outras cobranças se aplicam, como tokens de entrada não armazenados em cache e tokens de saída.

Para detalhes atualizados sobre preços, consulte a página de preços da API Gemini. Para saber como contar tokens, consulte o guia de tokens.

Outras considerações

Considere as seguintes considerações ao usar o armazenamento em cache de contexto:

A contagem de tokens de entrada mínima para o armazenamento em cache de contexto é de 1.024 para o Flash 2.5 e 2.048 para o Pro 2.5. O máximo é igual ao máximo do modelo especificado. Para saber mais sobre a contagem de tokens, consulte o guia de tokens.
O modelo não faz distinção entre tokens em cache e tokens de entrada normais. O conteúdo armazenado em cache é um prefixo do comando.
Não há taxas ou limites de uso especiais no armazenamento em cache de contexto. Os limites de taxa padrão para GenerateContent são aplicados, e os limites de token incluem tokens em cache.
O número de tokens em cache é retornado no usage_metadata das operações de criação, acesso e listagem do serviço de cache e também em GenerateContent ao usar o cache.