> ## Documentation Index > Fetch the complete documentation index at: https://docs.apimart.ai/llms.txt > Use this file to discover all available pages before exploring further. # Guia de uso do cache de contexto do Gemini > Crie e reutilize o cache de contexto do Gemini (Context Cache) por meio da API Chat Completions compatível com a OpenAI ou da API nativa do Gemini. Use cache_control para armazenar em cache um prefixo estável e reduzir o custo de tokens de conteúdos longos repetidos. Este guia explica como criar e reutilizar o cache de contexto do Gemini (Context Cache) por meio da API Chat Completions compatível com a OpenAI ou da API nativa do Gemini. Antes de começar: ```bash theme={null} export API_KEY="SUA_CHAVE_DE_API" ``` Os exemplos deste guia usam o `gemini-3.6-flash`. Para saber se outros modelos são compatíveis com Context Cache, consulte a descrição do modelo e a página de preços da plataforma. ## Casos de uso Quando várias solicitações incluem repetidamente o mesmo bloco grande de conteúdo, você pode armazenar em cache um prefixo estável, por exemplo: * Um system prompt muito longo * Uma base de conhecimento fixa ou documentação de produto * Mensagens de histórico estáveis em uma conversa com vários turnos * Definições e instruções de ferramentas que são reutilizadas O Context Cache é adequado para solicitações em que “o conteúdo inicial permanece o mesmo e apenas a pergunta final muda”. ## Uso básico Adicione `cache_control` ao bloco de conteúdo da última mensagem do prefixo estável: ```json theme={null} { "type": "text", "text": "Este é o último trecho de conteúdo do prefixo estável", "cache_control": { "type": "ephemeral", "ttl": "5m" } } ``` TTLs compatíveis: | TTL | Significado | | ---- | ------------------- | | `5m` | Cache por 5 minutos | | `1h` | Cache por 1 hora | Se `ttl` for omitido, o valor padrão será `5m`. ## Estrutura das mensagens Recomendamos usar a seguinte estrutura: ```text theme={null} system → Texto longo estável ou mensagens de histórico → Limite do prefixo estável com cache_control → Pergunta atual do usuário (não armazenada em cache) ``` A mensagem que contém `cache_control` e todas as mensagens anteriores formam o prefixo armazenado em cache. Deve haver pelo menos uma mensagem em tempo real depois dela. ## Exemplo de solicitação compatível com a OpenAI ```bash theme={null} curl "https://api.apimart.ai/v1/chat/completions" \ -H "Authorization: Bearer $API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "gemini-3.6-flash", "stream": false, "messages": [ { "role": "system", "content": "Responda estritamente de acordo com o material de referência fornecido." }, { "role": "user", "content": "Insira aqui o material de referência extenso que será reutilizado…" }, { "role": "assistant", "content": [ { "type": "text", "text": "Li e compreendi o material de referência acima.", "cache_control": { "type": "ephemeral", "ttl": "5m" } } ] }, { "role": "user", "content": "Resuma os três principais pontos do material de referência." } ] }' ``` Na primeira vez que você enviar a solicitação, o sistema tentará criar um cache e o usará para concluir a solicitação atual. Não é necessário chamar um endpoint separado para criar o cache. `cache_control` define tanto o “limite do cache” quanto o seu “período de validade”. ## Exemplo de solicitação nativa do Gemini O endpoint nativo `generateContent` do Gemini também permite adicionar `cache_control` em `contents[].parts[]`: ```bash theme={null} curl "https://api.apimart.ai/v1beta/models/gemini-3.6-flash:generateContent" \ -H "x-goog-api-key: $API_KEY" \ -H "Content-Type: application/json" \ -d '{ "systemInstruction": { "parts": [ { "text": "Responda estritamente de acordo com o material de referência fornecido." } ] }, "contents": [ { "role": "user", "parts": [ { "text": "Insira aqui o material de referência extenso que será reutilizado…" } ] }, { "role": "model", "parts": [ { "text": "Li e compreendi o material de referência acima.", "cache_control": { "type": "ephemeral", "ttl": "5m" } } ] }, { "role": "user", "parts": [ { "text": "Resuma os três principais pontos do material de referência." } ] } ] }' ``` `cache_control` é um campo de extensão da plataforma para o formato de solicitação do Gemini. Depois de identificar o limite, a plataforma remove esse campo antes de encaminhar a solicitação e cria ou reutiliza automaticamente o conteúdo em cache (`cachedContent`). A interface de streaming usa o mesmo corpo da solicitação; basta alterar o endereço para: ```bash theme={null} curl -N "https://api.apimart.ai/v1beta/models/gemini-3.6-flash:streamGenerateContent?alt=sse" \ -H "x-goog-api-key: $API_KEY" \ -H "Content-Type: application/json" \ -d '{ "contents": [ { "role": "user", "parts": [ { "text": "Insira aqui o material de referência extenso que será reutilizado…", "cache_control": { "type": "ephemeral", "ttl": "5m" } } ] }, { "role": "user", "parts": [ { "text": "Resuma os três principais pontos do material de referência." } ] } ] }' ``` Ao reutilizar o cache, mantenha `systemInstruction`, os `contents` anteriores ao limite, o TTL e as tools inalterados; modifique apenas o conteúdo em tempo real posterior ao limite. ## Fluxo de criação e reutilização Na primeira vez que você enviar uma solicitação com `cache_control`: ```text theme={null} Identificar o prefixo estável → Criar o Context Cache → Referenciar o novo cache na solicitação atual → Retornar o resultado do modelo ``` Ao enviar novamente o mesmo prefixo estável: ```text theme={null} Identificar o mesmo prefixo estável → Reutilizar um Context Cache que ainda não expirou → Enviar apenas o conteúdo atual em tempo real → Retornar o resultado do modelo ``` Por isso, a primeira solicitação também pode retornar diretamente uma grande quantidade de tokens provenientes do cache. Esse comportamento é normal e não exige o envio prévio de uma “solicitação de aquecimento”. ## Reutilizar o cache Nas solicitações seguintes, mantenha os itens abaixo inalterados: * O modelo * Todas as mensagens anteriores a `cache_control` * `cache_control.ttl` * As definições de ferramentas (se você usar tools) * `systemInstruction` nas solicitações nativas do Gemini Modifique apenas a pergunta em tempo real posterior ao limite: ```json theme={null} { "role": "user", "content": "Quais riscos são mencionados no material de referência?" } ``` Desde que o prefixo estável seja idêntico e o cache ainda não tenha expirado, o sistema reutilizará o cache existente. As seguintes alterações geram um cache diferente: * Modificar o texto ou a ordem das mensagens no prefixo estável * Trocar o modelo * Alterar `5m` para `1h` * Modificar as tools ou a definição dos parâmetros das ferramentas * Usar outro usuário ou canal de API ## Exemplo em Python ```python theme={null} from openai import OpenAI client = OpenAI( api_key="YOUR_API_KEY", base_url="https://api.apimart.ai/v1", ) stable_messages = [ { "role": "system", "content": "Responda estritamente de acordo com o material de referência fornecido.", }, { "role": "user", "content": "Insira aqui o material de referência extenso que será reutilizado…", }, { "role": "assistant", "content": [ { "type": "text", "text": "Li e compreendi o material de referência acima.", "cache_control": { "type": "ephemeral", "ttl": "5m", }, } ], }, ] response = client.chat.completions.create( model="gemini-3.6-flash", messages=[ *stable_messages, { "role": "user", "content": "Resuma os três principais pontos do material de referência.", }, ], ) print(response.choices[0].message.content) print(response.usage) ``` Nas solicitações seguintes, reutilize o mesmo `stable_messages` e substitua apenas a última mensagem do usuário. ## Verificar se o cache foi usado ### Resposta compatível com a OpenAI Consulte os seguintes campos da resposta: ```json theme={null} { "usage": { "prompt_tokens": 14430, "prompt_tokens_details": { "cached_tokens": 14420, "cache_write_tokens": 0 } } } ``` Descrição dos campos: | Campo | Significado | | -------------------- | -------------------------------------------------- | | `prompt_tokens` | Total de tokens de entrada desta solicitação | | `cached_tokens` | Tokens de entrada lidos do cache nesta solicitação | | `cache_write_tokens` | Tokens gravados no cache; retornar `0` é normal | A primeira solicitação também pode apresentar um valor alto de `cached_tokens`, pois o sistema pode criar o cache e referenciá-lo na mesma chamada ao modelo. ### Resposta nativa do Gemini Consulte `usageMetadata.cachedContentTokenCount` na resposta: ```json theme={null} { "usageMetadata": { "promptTokenCount": 13926, "cachedContentTokenCount": 13916, "totalTokenCount": 13954 } } ``` Descrição dos campos: | Campo | Significado | | ------------------------- | ---------------------------------------------------- | | `promptTokenCount` | Total de tokens de entrada desta solicitação | | `cachedContentTokenCount` | Tokens de entrada lidos do cache nesta solicitação | | `totalTokenCount` | Total de tokens de entrada e saída desta solicitação | `streamGenerateContent` retorna o mesmo `usageMetadata` em um frame da resposta SSE. O cliente deve ler o frame que contém esse campo, em vez de verificar apenas o primeiro trecho de texto. ## Recomendações 1. Armazene em cache apenas conteúdos longos que sejam realmente estáveis e que serão reutilizados várias vezes. 2. Coloque a pergunta que muda a cada solicitação depois do limite definido por `cache_control`. 3. Não inclua timestamps, IDs aleatórios nem informações dinâmicas do usuário no prefixo estável. 4. Use `5m` se você espera repetir as chamadas em um curto período. 5. Use `1h` quando precisar de uma janela de reutilização mais longa. 6. Se o prefixo for muito curto, o modelo não for compatível ou o cache estiver temporariamente indisponível, a solicitação poderá ser processada automaticamente da maneira convencional. 7. No formato nativo do Gemini, o limite do cache deve estar em `contents[].parts[]`, e não em `systemInstruction`. ## Perguntas frequentes Sim. `generateContent` e `streamGenerateContent` usam a mesma estrutura de `cache_control`. O limite deve estar em `contents[].parts[]`, e deve haver pelo menos um content em tempo real depois do content que contém o limite. Se a solicitação já fornecer explicitamente o nome de um recurso `cachedContent` nativo, a plataforma dará prioridade ao recurso fornecido pelo usuário e não tentará criar um cache automaticamente. Os motivos mais comuns incluem: * O prefixo estável não é exatamente igual ao da solicitação anterior * O TTL expirou * O modelo ou as tools foram modificados * O conteúdo armazenado em cache não atingiu o número mínimo de tokens exigido pelo modelo * `cache_control` foi colocado na última mensagem, sem deixar uma pergunta em tempo real Não é recomendável. A última mensagem geralmente é a pergunta atual em tempo real e não deve ser armazenada em cache. Se não houver nenhuma mensagem em tempo real depois do limite, a solicitação será processada da maneira convencional. Não. No momento, apenas `5m` e `1h` são compatíveis. Qualquer outro valor retorna um erro HTTP 400. Sim, mas todos os limites devem usar o mesmo TTL, e o sistema usará o último deles. Em geral, recomendamos configurar apenas um limite por solicitação para deixar a estrutura mais clara. Normalmente, não. Se as condições para criar ou reutilizar o cache não forem atendidas, o sistema processará automaticamente a solicitação da maneira convencional. As exceções são erros de parâmetros, como um TTL inválido ou o uso combinado de TTLs diferentes. A solicitação será processada automaticamente da maneira convencional, sem criar um cache explícito nem gerar custos de armazenamento em cache. A entrada e a saída normais, bem como eventuais acertos em cache implícito, continuarão a ser cobrados de acordo com as regras existentes do modelo. Esse é o comportamento normal do cache de contexto do Gemini. O custo de criação é registrado como uma cobrança separada de armazenamento em cache; `cache_write_tokens`, no estilo da OpenAI ou do Claude, não é usado para indicar quantos tokens foram gravados no cache. Não necessariamente. O próprio sistema também pode produzir acertos em um cache implícito. Para usuários comuns, os tokens lidos do cache permitem determinar se a solicitação se beneficiou de uma leitura em cache. Se você precisar verificar o custo de criação de um cache explícito, consulte os registros de consumo de Context Cache storage na plataforma. Ao criar um cache, pode haver uma cobrança única de armazenamento. Ao usar o cache, os tokens correspondentes são cobrados pelo preço de leitura do cache. Consulte os preços específicos na página de preços dos modelos da plataforma.