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ília | Como liga | O que fazer |
|---|---|---|
| Gemini (Google) | Automático | Nada. Prompts longos repetidos entram em cache sozinhos. |
| GPT (OpenAI) | Automático | Nada. Vale para prompts acima de um tamanho mínimo. |
| DeepSeek | Automático | Nada. |
| Claude (Anthropic) | Explícito | Marcar 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:
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:
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."}
]
}'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).