Cache de prompt

Quando você manda o mesmo começo de prompt várias vezes (instruções de sistema, um documento longo, a lista de ferramentas), o provedor do modelo pode guardar esse trecho em cache. Nas chamadas seguintes, a parte que veio do cache é cobrada com um desconto grande sobre o preço normal de entrada e a resposta costuma começar mais rápido.

Esse é o cache do provedor. O Tokia não guarda o conteúdo das suas mensagens: ele só repassa o pedido e cobra pelo uso real que o provedor informar, já com o desconto do cache.

Quais modelos têm cache

FamíliaComo ligaO que fazer
Gemini (Google)AutomáticoNada. Prompts longos repetidos entram em cache sozinhos.
GPT (OpenAI)AutomáticoNada. Vale para prompts acima de um tamanho mínimo.
DeepSeekAutomáticoNada.
Claude (Anthropic)ExplícitoMarcar o trecho com cache_control, como no exemplo abaixo.

Para saber se um modelo específico tem preço de cache, veja a coluna Entrada em cache em Preços ou o campo price_brl_cache_read_per_mtok da API de preços. Quando o valor é null, o parceiro não informa preço de cache para aquele modelo.

Como estruturar o prompt

  • Coloque o que não muda no início: instruções de sistema, documentos de referência, exemplos e ferramentas.
  • Deixe o que muda (a pergunta do usuário, dados da hora) no fim.
  • Mantenha o começo idêntico entre chamadas. Qualquer caractere diferente no início invalida o cache dali em diante.
  • Use o mesmo modelo nas chamadas que devem aproveitar o cache.

Tamanho mínimo e tempo de vida

Cada provedor define um tamanho mínimo de prompt para usar o cache (em geral, da ordem de mil tokens) e um tempo de vida curto, de alguns minutos, renovado a cada uso. Os valores exatos dependem do provedor e do modelo e podem mudar sem aviso. Por isso, trate o cache como economia provável, não garantida.

Exemplos

Cache automático (Gemini, GPT, DeepSeek)

Não muda nada no pedido. Basta repetir o mesmo começo de prompt:

python
from openai import OpenAI

client = OpenAI(api_key="sk-...", base_url="https://api.usetokia.com/v1")

INSTRUCOES = open("manual-do-produto.md").read()

resposta = client.chat.completions.create(
    model="gemini-flash",
    messages=[
        {"role": "system", "content": INSTRUCOES},
        {"role": "user", "content": "Como troco a senha?"},
    ],
)

detalhes = resposta.usage.prompt_tokens_details
print("entrada:", resposta.usage.prompt_tokens)
print("em cache:", detalhes.cached_tokens if detalhes else 0)

Cache explícito (Claude)

Nos modelos Claude, marque o fim do trecho fixo com "cache_control": {"type": "ephemeral"} dentro do conteúdo da mensagem:

bash
curl https://api.usetokia.com/v1/chat/completions \
  -H "Authorization: Bearer $TOKIA_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet-46",
    "messages": [
      {
        "role": "system",
        "content": [
          {
            "type": "text",
            "text": "<instruções e documento longo aqui>",
            "cache_control": {"type": "ephemeral"}
          }
        ]
      },
      {"role": "user", "content": "Resuma a seção 3."}
    ]
  }'
typescript
import OpenAI from "openai";

const client = new OpenAI({ apiKey: process.env.TOKIA_KEY, baseURL: "https://api.usetokia.com/v1" });

const resposta = await client.chat.completions.create({
  model: "claude-sonnet-46",
  messages: [
    {
      role: "system",
      content: [
        {
          type: "text",
          text: documentoLongo,
          cache_control: { type: "ephemeral" },
        } as OpenAI.Chat.ChatCompletionContentPartText,
      ],
    },
    { role: "user", content: "Resuma a seção 3." },
  ],
});

console.log(resposta.usage?.prompt_tokens_details?.cached_tokens ?? 0);

Como ver o cache

Na resposta da API

O campo usage.prompt_tokens_details.cached_tokens mostra quantos tokens da entrada vieram do cache. Ele já está incluído em usage.prompt_tokens. Veja todos os campos em /v1/chat/completions.

No painel

  • Em Uso, os tokens em cache aparecem separados da entrada nova, com a taxa de cache e a economia do período em reais.
  • Em Chamadas, cada chamada mostra os tokens em cache e a economia no detalhe.

Streaming

Em chamadas com "stream": true, o gateway sempre pede ao provedor o uso real da chamada, então o desconto do cache entra na cobrança mesmo que você não peça o resumo de uso. Para o seu código receber o resumo ao final do stream, mande "stream_options": {"include_usage": true}. Veja Streaming.

Como é cobrado

A parte da entrada que veio do cache é cobrada pelo preço de Entrada em cache do modelo. O resto da entrada e a saída seguem os preços normais. Os preços já estão em reais por milhão de tokens e seguem a mesma composição dos demais (veja Preços).