Prompt caching

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, 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 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:

{
  "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.

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

{
  "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.

{
  "model": "anthropic/claude-sonnet-5",
  "previous_response_id": "resp_...",
  "cache_control": { "type": "ephemeral" },
  "input": [
    { "role": "user", "content": "And what about clause 9?" }
  ]
}

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

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."
      }
    ]
  }'

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."
      }
    ]
  }'

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);

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)

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);

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 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 abaixo.

OpenAI

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. 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.

Google AI

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:

{
  "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:

{
  "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.

{
  "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.

{
  "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 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 para os atributos de uso de tokens e de faturamento, e Rastreamento de tokens e custos para saber como os custos de cache são calculados.

Toqan Router

Visão geral

APIs

MCP Portal

Roteamento

Segurança e privacidade

Recursos dos modelos

Ferramentas de servidor

Cenários comuns

Configuração de provedores

Visão geral

Anthropic

Modelos compatíveis

Ativar o cache

Limites mínimos de tokens

TTL do cache

Conversas com vários turnos

Exemplo

OpenAI

OpenAI

Google Gemini

Google AI

Uso na resposta

Responses API

Chat Completions API

Anthropic Messages API

Uso do cache em Traces

​Visão geral

​Anthropic

​Modelos compatíveis

​Ativar o cache

​Limites mínimos de tokens

​TTL do cache

​Conversas com vários turnos

​Exemplo

​OpenAI

OpenAI

​Google Gemini

Google AI

​Uso na resposta

​Responses API

​Chat Completions API

​Anthropic Messages API

​Uso do cache em Traces

Visão geral

Anthropic

Modelos compatíveis

Ativar o cache

Limites mínimos de tokens

TTL do cache

Conversas com vários turnos

Exemplo

OpenAI

Google Gemini

Uso na resposta

Responses API

Chat Completions API

Anthropic Messages API

Uso do cache em Traces