> ## Documentation Index > Fetch the complete documentation index at: /docs/llms.txt > Use this file to discover all available pages before exploring further. # Prompt caching > O prompt caching reduz os custos com tokens de entrada armazenando em cache prefixos de prompt repetidos no nível do provedor. Economize em prompts de sistema longos e documentos de referência com Anthropic, OpenAI e Google Gemini. **Casos de uso** * Reutilizar prompts de sistema longos em muitas solicitações para reduzir os custos com tokens de entrada. * Referenciar documentos grandes ou bases de código sem reenviá-los a cada chamada. * Conversas com vários turnos com um contexto grande e estável que não muda entre os turnos. * Pipelines de RAG em que o mesmo contexto recuperado é compartilhado por muitas consultas de usuários. *** ## Visão geral O Prompt Caching é um recurso no nível do provedor que armazena prompts em cache para que **solicitações repetidas** sejam cobradas com uma tarifa reduzida. Ele é mais eficaz quando suas solicitações compartilham um **prefixo grande e estável**: * um prompt de sistema longo. * um documento de referência. * uma lista de definições de ferramentas. Diferentemente do [Response Caching](/docs/pt-BR/ai-gateway/features/cache.md), que entrega uma resposta armazenada para solicitações idênticas, o Prompt Caching continua chamando o modelo a cada solicitação, com custo reduzido. Os dois podem ser usados juntos. A forma de ativar o cache e o que é armazenado variam conforme o provedor. Consulte as seções por provedor abaixo. ## Anthropic O prompt caching em modelos da Anthropic exige ativação explícita por meio de marcadores `cache_control` em partes individuais das mensagens. Um breakpoint marca o fim de um prefixo armazenável em cache: o provedor armazena tudo até o bloco marcado, inclusive, e as solicitações posteriores que compartilham esse prefixo leem a parte em cache em vez de processá-la novamente. No endpoint compatível com a Anthropic, os breakpoints são repassados exatamente como na API nativa da Anthropic; consulte a [Anthropic Messages API](/docs/pt-BR/ai-gateway/features/anthropic-messages-api.md) para detalhes do endpoint e um exemplo com vários turnos. ### Modelos compatíveis Todos os modelos Claude atuais, incluindo o Claude Fable 5 e as famílias Opus, Sonnet e Haiku. ### Ativar o cache Adicione um objeto `cache_control` a qualquer parte de mensagem que você queira marcar como armazenável em cache: ```json theme={"theme":{"light":"github-light","dark":"github-dark"}} { "cache_control": { "type": "ephemeral" } } ``` `"ephemeral"` é o único tipo compatível. Você pode colocá-lo em: * Partes de texto de mensagens de sistema. * Partes de texto de mensagens de usuário. * Imagens, documentos e arquivos (incluindo PDFs) em mensagens de usuário. * Definições de ferramentas. * Conteúdo de resultados de ferramentas. A Anthropic permite no máximo quatro breakpoints de cache por solicitação, incluindo marcadores em definições de ferramentas. Um marcador em uma ferramenta armazena em cache o prefixo das ferramentas sem adicionar um marcador de nível superior. Um `cache_control` explícito de nível superior para cache automático ocupa um dos quatro espaços; consulte [Anthropic prompt caching](https://platform.claude.com/docs/en/build-with-claude/prompt-caching#combining-with-block-level-caching). ### Limites mínimos de tokens O cache só é ativado quando o conteúdo marcado excede uma quantidade mínima de tokens. Solicitações abaixo do limite são processadas normalmente, com custo integral. | Modelo | Mínimo de tokens | | - | - | | Claude Opus 5, Fable 5 | 512 | | Claude Opus 4.8, Sonnet 5, Sonnet 4.6, Sonnet 4.5, Opus 4.1, Opus 4, Sonnet 4, Sonnet 3.7 | 1,024 | | Claude Opus 4.7, Haiku 3.5, Haiku 3 | 2,048 | | Claude Opus 4.6, Opus 4.5, Haiku 4.5 | 4,096 | ### TTL do cache O parâmetro `ttl` controla por quanto tempo o conteúdo em cache persiste antes de expirar. | Valor | Duração | | - | - | | `"5m"` (padrão) | 5 minutos a partir do último uso | | `"1h"` | 1 hora | ```json theme={"theme":{"light":"github-light","dark":"github-dark"}} { "cache_control": { "type": "ephemeral", "ttl": "1h" } } ``` As leituras do cache são cobradas a 0,1x o preço normal dos tokens de entrada. As gravações no cache têm um acréscimo: 1,25x o preço de entrada para o TTL de 5 minutos e 2x para o TTL de 1 hora. Com o TTL de 5 minutos, o cache compensa a partir da segunda solicitação com um prefixo compartilhado: 1,35x contra 2x sem cache. Com o TTL de 1 hora, compensa a partir da terceira: duas solicitações custam 2,1x contra 2x, e três custam 2,2x contra 3x. ### Conversas com vários turnos **Padrão: marque o prompt de sistema.** Coloque `cache_control` na parte de texto do sistema e envie a entrada completa em cada solicitação, incluindo qualquer histórico de conversa mantido pelo cliente. O prompt de sistema é gravado uma vez e lido em todos os turnos seguintes, independentemente do que o usuário disser. Todos os outros exemplos desta página usam essa forma. **Ao continuar com `previous_response_id`, use o parâmetro de nível superior.** O gateway reconstrói o histórico a partir do armazenamento, e os marcadores em nível de bloco dos turnos anteriores não são mantidos. Envie apenas a nova mensagem do usuário e defina `cache_control` no nível superior da solicitação. Cada turno então lê toda a conversa anterior e grava apenas a nova mensagem. ```json theme={"theme":{"light":"github-light","dark":"github-dark"}} { "model": "anthropic/claude-sonnet-5", "previous_response_id": "resp_...", "cache_control": { "type": "ephemeral" }, "input": [ { "role": "user", "content": "And what about clause 9?" } ] } ``` > [!WARNING] > > Não reenvie o prompt de sistema em um turno com `previous_response_id`. O histórico armazenado já o contém, e uma segunda cópia falha na validação em modelos da Anthropic. Evite o parâmetro de nível superior em solicitações independentes. Ele marca o último bloco, que é a mensagem do usuário; assim, solicitações com perguntas diferentes nunca compartilham um prefixo, e cada uma paga o acréscimo de gravação no cache sem nenhuma leitura. ### Exemplo ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}} curl -X POST https://router.toqan.ai/eu/v3/router/responses \ -H "Authorization: Bearer $TOQAN_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "anthropic/claude-sonnet-5", "input": [ { "role": "system", "content": [ { "type": "input_text", "text": "You are a senior legal assistant. The following is our complete contract template library...", "cache_control": { "type": "ephemeral" } } ] }, { "role": "user", "content": "Summarize clause 7 of the NDA template." } ] }' ``` ```bash cURL (Chat Completions) theme={"theme":{"light":"github-light","dark":"github-dark"}} curl -X POST https://router.toqan.ai/eu/v3/router/chat/completions \ -H "Authorization: Bearer $TOQAN_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "anthropic/claude-sonnet-5", "messages": [ { "role": "system", "content": [ { "type": "text", "text": "You are a senior legal assistant. The following is our complete contract template library...", "cache_control": { "type": "ephemeral" } } ] }, { "role": "user", "content": "Summarize clause 7 of the NDA template." } ] }' ``` ```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}} import OpenAI from "openai"; const client = new OpenAI({ apiKey: process.env.TOQAN_API_KEY, baseURL: "https://router.toqan.ai/eu/v3/router", }); const response = await client.responses.create({ model: "anthropic/claude-sonnet-5", input: [ { role: "system", content: [ { type: "input_text", text: "You are a senior legal assistant. The following is our complete contract template library...", cache_control: { type: "ephemeral" }, }, ], }, { role: "user", content: "Summarize clause 7 of the NDA template." }, ], }); console.log(response.output_text); ``` ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}} from openai import OpenAI import os client = OpenAI( api_key=os.environ.get("TOQAN_API_KEY"), base_url="https://router.toqan.ai/eu/v3/router", ) response = client.responses.create( model="anthropic/claude-sonnet-5", input=[ { "role": "system", "content": [ { "type": "input_text", "text": "You are a senior legal assistant. The following is our complete contract template library...", "cache_control": {"type": "ephemeral"}, } ], }, {"role": "user", "content": "Summarize clause 7 of the NDA template."}, ], ) print(response.output_text) ``` ```typescript TypeScript (Chat Completions) theme={"theme":{"light":"github-light","dark":"github-dark"}} import OpenAI from "openai"; const client = new OpenAI({ apiKey: process.env.TOQAN_API_KEY, baseURL: "https://router.toqan.ai/eu/v3/router", }); const response = await client.chat.completions.create({ model: "anthropic/claude-sonnet-5", messages: [ { role: "system", content: [ { type: "text", text: "You are a senior legal assistant. The following is our complete contract template library...", cache_control: { type: "ephemeral" }, }, ], }, { role: "user", content: "Summarize clause 7 of the NDA template." }, ], }); console.log(response.choices[0].message.content); ``` ```python Python (Chat Completions) theme={"theme":{"light":"github-light","dark":"github-dark"}} from openai import OpenAI import os client = OpenAI( api_key=os.environ.get("TOQAN_API_KEY"), base_url="https://router.toqan.ai/eu/v3/router", ) response = client.chat.completions.create( model="anthropic/claude-sonnet-5", messages=[ { "role": "system", "content": [ { "type": "text", "text": "You are a senior legal assistant. The following is our complete contract template library...", "cache_control": {"type": "ephemeral"}, } ], }, {"role": "user", "content": "Summarize clause 7 of the NDA template."}, ], ) print(response.choices[0].message.content) ``` ## OpenAI O prompt caching em modelos da OpenAI é **totalmente automático**. Não é necessário usar `cache_control` nem fazer qualquer alteração na solicitação. O **AI Gateway** encaminha as solicitações normalmente; a OpenAI armazena o prefixo do prompt em cache do lado dela e aplica o desconto de forma transparente. O cache é ativado em prompts com mais de 1,024 tokens, em incrementos de 128 tokens a partir desse limite. A API armazena em cache o prefixo correspondente mais longo de solicitações anteriores na mesma máquina. A duração da retenção do cache depende do modelo e é determinada pela OpenAI. Consulte a [documentação de prompt caching da OpenAI](https://platform.openai.com/docs/guides/prompt-caching) para conhecer a política de retenção atual de cada modelo. Os acertos de cache são refletidos no objeto `usage` da resposta. Consulte [Uso na resposta](#usage-in-the-response) abaixo. > [card] [OpenAI](/docs/pt-BR/ai-studio/integrations/providers/openai.md) > > Configure sua chave de API da OpenAI para usar modelos GPT com prompt caching automático. ## Google Gemini O Google Gemini oferece dois modos de cache pelo **AI Gateway**. O **cache implícito** é ativado por padrão no Gemini 2.5 e em modelos mais recentes. Não é necessário alterar as solicitações. O **AI Gateway** encaminha as solicitações normalmente, e o Google aplica o desconto de cache automaticamente quando existe um prefixo correspondente. O cache implícito é ativado a partir de um mínimo que depende do modelo: 2,048 tokens nos modelos Gemini 2.5, e mais nas gerações mais recentes. Verifique os limites e as tarifas atuais na [documentação de cache do Google](https://ai.google.dev/gemini-api/docs/caching). O **cache explícito** é gerenciado pelo **AI Gateway** nos modelos Gemini compatíveis (Gemini 2.5 e mais recentes). Adicione marcadores `cache_control` às partes de mensagens de sistema ou de usuário (texto e arquivos), usando a mesma sintaxe dos modelos da Anthropic. O gateway cria um objeto de cache do Google para o conteúdo marcado, reutiliza-o nas solicitações seguintes que marcam o mesmo conteúdo e o deixa expirar após o TTL (`5m` por padrão, `1h` compatível). Não é necessário criar nem referenciar objetos de cache do Google diretamente. O cache explícito funciona em deployments do Vertex AI com autenticação por conta de serviço. O gateway o ignora no Google AI (Gemini API) quando a solicitação tem um prompt de sistema ou ferramentas, e totalmente em deployments do Vertex AI Express (chave de API), onde apenas o cache implícito se aplica. > [card] [Google AI](/docs/pt-BR/ai-studio/integrations/providers/google-ai.md) > > Configure sua chave de API do Google AI para usar modelos Gemini com prompt caching implícito. ## Uso na resposta Todos os endpoints informam as leituras e gravações de cache no objeto `usage`. Os nomes dos campos seguem o formato de resposta de cada endpoint; por isso, a mesma solicitação aparece de forma um pouco diferente em cada API. ### Responses API Em `/v3/router/responses`, a atividade de cache é informada em `usage.input_tokens_details`. Os mesmos campos aparecem no evento final `response.completed` durante o streaming. | Campo | Significado | | - | - | | `cached_tokens` | Tokens lidos do cache. | | `cache_creation_tokens` | Tokens gravados no cache, em todos os TTLs. | | `cache_write_tokens` | Mesmo valor de `cache_creation_tokens`, mantido por compatibilidade. | | `cache_creation_5m_tokens` | Tokens gravados com o TTL de 5 minutos. Presente apenas em uma gravação com esse TTL. | | `cache_creation_1h_tokens` | Tokens gravados com o TTL de 1 hora. Presente apenas em uma gravação com esse TTL. | A primeira solicitação com um novo prefixo grava o cache: ```json theme={"theme":{"light":"github-light","dark":"github-dark"}} { "usage": { "input_tokens": 2673, "output_tokens": 30, "total_tokens": 2703, "input_tokens_details": { "cached_tokens": 0, "cache_creation_tokens": 2669, "cache_write_tokens": 2669, "cache_creation_5m_tokens": 2669 } } } ``` Uma solicitação posterior com o mesmo prefixo faz a leitura. Os campos por TTL são omitidos quando nada foi gravado: ```json theme={"theme":{"light":"github-light","dark":"github-dark"}} { "usage": { "input_tokens": 2673, "output_tokens": 30, "total_tokens": 2703, "input_tokens_details": { "cached_tokens": 2669, "cache_creation_tokens": 0, "cache_write_tokens": 0 } } } ``` `input_tokens` inclui os tokens em cache, seguindo a convenção da OpenAI. ### Chat Completions API Em `/v3/router/chat/completions`, a atividade de cache é informada em `usage.prompt_tokens_details`. A divisão por TTL não está disponível neste endpoint. ```json theme={"theme":{"light":"github-light","dark":"github-dark"}} { "usage": { "prompt_tokens": 2673, "completion_tokens": 30, "total_tokens": 2703, "prompt_tokens_details": { "cached_tokens": 2669, "cache_creation_tokens": 0, "audio_tokens": 0 } } } ``` ### Anthropic Messages API Em `/v3/anthropic/v1/messages`, o uso segue os nomes de campos nativos da Anthropic. `input_tokens` conta apenas os tokens que não estão em cache. Os campos de cache só estão presentes quando diferentes de zero: uma gravação omite `cache_read_input_tokens`, e uma leitura pura omite `cache_creation_input_tokens` e o objeto aninhado `cache_creation`. ```json theme={"theme":{"light":"github-light","dark":"github-dark"}} { "usage": { "input_tokens": 4, "output_tokens": 30, "cache_creation_input_tokens": 2669, "cache_creation": { "ephemeral_5m_input_tokens": 2669, "ephemeral_1h_input_tokens": 0 } } } ``` ## Uso do cache em Traces As leituras e gravações de cache são registradas em todos os spans de LLM, para que possam ser inspecionadas por solicitação em [Traces](/docs/pt-BR/ai-studio/observability/traces.md) e agregadas em Analytics. | Onde | O que é exibido | | - | - | | Atributos do span | `gen_ai.usage.prompt_tokens_details.cached_tokens`, `gen_ai.usage.prompt_tokens_details.cache_creation_tokens` e os atributos por TTL `gen_ai.usage.prompt_tokens_details.cache_creation_5m_tokens` / `gen_ai.usage.prompt_tokens_details.cache_creation_1h_tokens`. | | Painel Economics e lista de traces | Tokens de entrada em cache, além de `orq.billing.cache_read_cost` e `orq.billing.cache_write_cost` em USD. O custo de gravação já inclui o acréscimo de 1,25x ou 2x do TTL. | | Analytics | Os tokens em cache e o custo de leitura/gravação do cache são consolidados nos detalhamentos de tokens e custos do workspace. | A divisão de tokens por TTL é armazenada apenas como atributo do span. Ela não aparece como uma coluna separada na lista de traces nem em Analytics. Consulte [Atributos do span](/docs/pt-BR/ai-studio/observability/span-attributes.md#token-usage) para os atributos de uso de tokens e de faturamento, e [Rastreamento de tokens e custos](/docs/pt-BR/ai-studio/observability/token-cost-tracking.md) para saber como os custos de cache são calculados. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.