Cache de prompt na API OpenAI, também chamado de prompt caching, permite reutilizar o processamento de uma parte estável do contexto entre solicitações. Quando várias chamadas começam com as mesmas instruções, exemplos, ferramentas ou documentos, a API pode reaproveitar esse prefixo em vez de processá-lo integralmente outra vez.
O resultado pode ser menor latência e redução do custo dos tokens de entrada reutilizados. O cache não reutiliza a resposta final, não garante textos idênticos e não elimina a cobrança dos tokens de saída.
Nas famílias GPT-5.6 e posteriores, a OpenAI oferece cache implícito e explícito. O modo explícito permite marcar onde termina o conteúdo estável, enquanto o modo implícito deixa a plataforma escolher os pontos de cache. Modelos anteriores usam regras diferentes e, em geral, oferecem apenas o cache implícito.
Documentação, parâmetros e regras de cobrança verificados em 10 de outubro de 2026. Modelos, preços, tempos de retenção e campos do SDK podem mudar; confirme o guia oficial de prompt caching antes de alterar uma aplicação em produção.
Cache de prompt em resumo
| Pergunta | Resposta |
|---|---|
| O que é armazenado? | O estado calculado de um prefixo reutilizável, não a resposta final pronta. |
| O cache muda a resposta? | Não. O modelo ainda gera uma nova saída. |
| Qual é o tamanho mínimo? | 1.024 tokens para GPT-5.6 e posteriores; modelos anteriores podem usar regras dependentes da configuração. |
| O prefixo precisa ser idêntico? | Sim. Alterações antes do ponto reutilizável podem impedir o cache hit. |
| O cache é automático? | O modo implícito pode ser automático; GPT-5.6 e posteriores também permitem breakpoints explícitos. |
| O cache reduz tokens de saída? | Não. Ele afeta o processamento da entrada reutilizada. |
| Tokens em cache contam para rate limits? | Sim. Eles continuam entrando nos limites de tokens por minuto. |
| É possível limpar o cache manualmente? | Não. As entradas expiram conforme a política do modelo. |
Como o prompt caching funciona
Um prompt enviado à API pode conter duas partes:
- prefixo estável: instruções, exemplos, definições de ferramentas, schemas e material de referência que se repetem;
- sufixo variável: pergunta, arquivo, dados ou comando específicos de cada solicitação.
Na primeira solicitação elegível, a OpenAI processa o conteúdo e pode gravar um prefixo no cache. Nas chamadas seguintes, a plataforma procura o maior prefixo compatível já armazenado.
- A aplicação envia um contexto com tamanho suficiente.
- A API identifica ou recebe um breakpoint de cache.
- O prefixo é processado e gravado.
- Uma nova solicitação reutiliza exatamente o mesmo início.
- A API encontra o prefixo compatível.
- Os tokens reaproveitados aparecem como
cached_tokens. - O conteúdo posterior ao breakpoint continua sendo processado normalmente.
O cache funciona por prefixo. Repetir um parágrafo idêntico no final do prompt não ajuda se o conteúdo anterior mudou. Para aumentar a reutilização, coloque o material estável primeiro e os dados variáveis depois.
O que pode fazer parte do prefixo reutilizável?
- instruções do desenvolvedor;
- regras de estilo e segurança;
- exemplos de entrada e saída;
- rubricas de avaliação;
- documentação de produto;
- políticas internas;
- schemas de Structured Outputs;
- definições de funções e ferramentas;
- histórico preservado de uma conversa;
- imagens idênticas incluídas no mesmo ponto;
- trechos de código compartilhados entre várias tarefas.
Ferramentas, imagens, mensagens, schemas e parâmetros que participam do contexto precisam permanecer compatíveis. Alterar a ordem das ferramentas, uma descrição de função ou um campo do schema pode reduzir o prefixo reutilizado.
Cache implícito e cache explícito
| Modo | Como funciona | Quando considerar |
|---|---|---|
| Implícito | A OpenAI escolhe breakpoints elegíveis com base na estrutura da solicitação. | Conversas que crescem por anexação e integrações que precisam de configuração simples. |
| Explícito | O desenvolvedor marca onde termina uma parte estável que deve ser gravada. | Prompts com prefixo longo e sufixo variável que não vale a pena gravar. |
| Implícito com breakpoints adicionais | A plataforma mantém um breakpoint automático e aceita pontos explícitos extras. | Workflows com partes que mudam em ritmos diferentes. |
| Somente explícito | A API usa apenas os breakpoints definidos pela aplicação. | Quando é necessário impedir gravações automáticas em trechos variáveis. |
Em GPT-5.6 e posteriores, cada solicitação pode criar até quatro gravações de cache. No modo implícito, o breakpoint automático utiliza uma dessas posições.
Modelos anteriores a GPT-5.6 seguem regras diferentes. Antes de copiar um parâmetro entre modelos, verifique a seção de compatibilidade do guia oficial.
Estrutura recomendada do prompt
1. Instruções estáveis 2. Políticas e regras 3. Exemplos fixos 4. Documentos de referência 5. Definições de ferramentas 6. Breakpoint de cache 7. Dados variáveis do usuário 8. Pergunta atual
Uma estrutura ruim coloca identificadores, datas, perguntas ou dados pessoais no início. Como esse conteúdo muda em cada chamada, toda a parte posterior deixa de corresponder ao prefixo anterior.
Estrutura com baixo reaproveitamento: 1. ID variável do usuário 2. Pergunta atual 3. Instruções estáveis 4. Ferramentas 5. Documento repetido Estrutura com maior reaproveitamento: 1. Instruções estáveis 2. Ferramentas 3. Documento repetido 4. ID ou dados variáveis 5. Pergunta atual
Exemplo de cache explícito com Python
O exemplo usa a Responses API e gpt-6.1-sol, modelo que oferece cache explícito. O conteúdo marcado como estável precisa atingir o tamanho mínimo elegível para produzir uma gravação.
import os
from openai import OpenAI
client = OpenAI(
api_key=os.environ["OPENAI_API_KEY"]
)
CONTEXTO_ESTAVEL = """
Você é um assistente de suporte técnico.
Regras:
- responda em português do Brasil;
- use somente a documentação fornecida;
- não invente preços, limites ou funcionalidades;
- quando faltar uma informação, escreva "não encontrado";
- preserve exatamente nomes de produtos, códigos e datas.
Documentação de referência:
[adicione aqui um conteúdo estável e suficientemente longo]
""".strip()
def responder(pergunta: str):
return client.responses.create(
model="gpt-6.1-sol",
prompt_cache_options={
"mode": "explicit",
"ttl": "30m",
},
input=[
{
"role": "developer",
"content": [
{
"type": "input_text",
"text": CONTEXTO_ESTAVEL,
"prompt_cache_breakpoint": {
"mode": "explicit"
},
}
],
},
{
"role": "user",
"content": [
{
"type": "input_text",
"text": pergunta,
}
],
},
],
)
primeira = responder(
"Como redefinir a senha?"
)
segunda = responder(
"Como atualizar o e-mail da conta?"
)
print(primeira.output_text)
print(segunda.output_text)O texto anterior ao prompt_cache_breakpoint deve permanecer igual. A pergunta muda depois do breakpoint, portanto não invalida o prefixo estável.
O campo superior instructions não aceita um breakpoint explícito. Para marcar instruções reutilizáveis, coloque-as em um bloco input_text com função developer, como no exemplo.
O código é demonstrativo e não foi executado neste artigo. Confirme a versão instalada do SDK e a disponibilidade do model ID antes de usar em produção.
Exemplo com cache implícito
Quando o fluxo cresce por anexação, o modo implícito pode ser suficiente:
import os
from openai import OpenAI
client = OpenAI(
api_key=os.environ["OPENAI_API_KEY"]
)
response = client.responses.create(
model="gpt-6.1-sol",
prompt_cache_key="suporte:produto-a",
prompt_cache_options={
"mode": "implicit",
"ttl": "30m",
},
input=[
{
"role": "developer",
"content": (
"Instruções e documentação estáveis..."
),
},
{
"role": "user",
"content": (
"Como configurar uma nova conta?"
),
},
],
)
print(response.output_text)Em GPT-5.6 e posteriores, prompt_cache_key não é necessário para otimizar o roteamento. Ele pode ser útil para separar a contabilização entre clientes, usuários ou workspaces.
Em modelos anteriores, uma chave estável pode ajudar a encaminhar solicitações relacionadas para máquinas que possuem o prefixo esperado. Ela influencia o roteamento, mas não fixa a solicitação em um servidor nem garante um cache hit.
Como pré-aquecer o cache
O prewarm prepara um prefixo antes da pergunta real. Ele pode ser útil quando uma aplicação conhece previamente um grande conjunto de instruções, ferramentas ou documentos que será usado na primeira interação.
import os
from openai import OpenAI
client = OpenAI(
api_key=os.environ["OPENAI_API_KEY"]
)
contexto = """
Instruções, ferramentas ou material
de referência estável da aplicação...
""".strip()
client.responses.create(
model="gpt-6.1-sol",
input=[
{
"role": "developer",
"content": contexto,
}
],
prompt_cache_options={
"prewarm": True,
},
)
response = client.responses.create(
model="gpt-6.1-sol",
input=[
{
"role": "developer",
"content": contexto,
},
{
"role": "user",
"content": "Resuma a política de reembolso.",
},
],
)
print(response.output_text)A chamada de pré-aquecimento não gera a resposta final. Os tokens gravados são cobrados pela tarifa de cache write, portanto não faça prewarm sem medir a probabilidade de reutilização.
Como verificar se o cache funcionou
Na Responses API, examine usage.input_tokens_details. Os campos mais relevantes são:
cached_tokens: tokens lidos de um prefixo já armazenado;cache_write_tokens: tokens gravados no cache;input_tokens: total de tokens de entrada contabilizados.
details = response.usage.input_tokens_details
print(
{
"input_tokens": response.usage.input_tokens,
"cached_tokens": details.cached_tokens,
"cache_write_tokens": (
details.cache_write_tokens
),
"output_tokens": response.usage.output_tokens,
}
)Na primeira solicitação, é normal encontrar cached_tokens igual a zero e uma quantidade positiva em cache_write_tokens. Uma chamada posterior compatível pode mostrar leitura do cache.
Não avalie o recurso com apenas uma solicitação. Registre várias chamadas reais e compare:
- taxa de cache hit;
- tokens gravados;
- tokens reutilizados;
- tempo até o primeiro token;
- duração total;
- custo de entrada;
- qualidade da resposta;
- volume de solicitações sem reutilização.
Diagnóstico de cache miss
Em modelos GPT-5.6 e posteriores compatíveis, os diagnósticos de prompt cache podem comparar uma solicitação atual com uma resposta anterior e indicar mudanças que impediram a reutilização.
Verifique especialmente:
- model ID diferente;
- service tier diferente;
- alteração em instruções iniciais;
- mudança de ordem das ferramentas;
- schema modificado;
- parâmetros de raciocínio ou verbosity incompatíveis;
- imagem diferente;
- breakpoint colocado depois de conteúdo variável;
- entrada expirada;
- mudança de região de processamento.
Como é feita a cobrança
Em GPT-5.6 e posteriores, as regras gerais documentadas são:
| Tipo de token | Multiplicador sobre a tarifa normal de entrada |
|---|---|
| Entrada comum | 1× |
| Gravação no cache | 1,25× |
| Leitura do cache na maioria dos modelos | 0,1× |
| Leitura do cache em GPT-6.1 Sol | 0,05× |
Esses multiplicadores precisam ser aplicados à tarifa de entrada do model ID, do contexto e do modo de processamento selecionados. Consulte a página atual de preços da OpenAI API.
custo de entrada =
(tokens comuns × tarifa de entrada)
+ (tokens gravados × tarifa de cache write)
+ (tokens lidos × tarifa de cached input)Exemplo em equivalentes de tokens
Considere um prefixo de 10 mil tokens reutilizado em dez solicitações em um modelo cuja leitura custa 0,1×:
Sem cache: 10 solicitações × 10.000 tokens = 100.000 equivalentes Com cache: 1 gravação × 10.000 × 1,25 = 12.500 9 leituras × 10.000 × 0,1 = 9.000 Total = 21.500 equivalentes de tokens de entrada
O exemplo considera reutilização integral do prefixo e não inclui o sufixo variável, tokens de saída, ferramentas ou tentativas adicionais. O ganho real depende da quantidade efetivamente reutilizada.
Quando o prompt caching vale a pena?
O recurso tende a ser útil em workflows com contexto longo e repetido:
- chatbots que preservam histórico;
- assistentes com políticas extensas;
- agentes com muitas definições de ferramentas;
- análise repetida sobre o mesmo manual;
- avaliações com a mesma rubrica e exemplos;
- classificação de itens com instruções longas;
- revisão de diferentes arquivos contra a mesma política;
- edições sucessivas na mesma base de código;
- geração de respostas com schema e ferramentas estáveis.
Quando o cache pode não compensar?
- prompts curtos que não atingem o mínimo elegível;
- solicitações únicas sem repetição;
- prefixo que muda em praticamente todas as chamadas;
- documentos diferentes colocados antes das instruções estáveis;
- prewarm feito sem uma chamada posterior provável;
- gravações frequentes de conteúdo que nunca será relido;
- migração de modelo que altera os breakpoints ou requisitos;
- tráfego distribuído entre regiões de processamento diferentes.
Não aumente artificialmente um prompt curto apenas para atingir o mínimo sem calcular o ponto de equilíbrio. Tokens adicionais também têm custo e podem alterar o comportamento do modelo.
Tempo de vida e retenção do cache
Em GPT-5.6 e posteriores, prompt_cache_options.ttl aceita atualmente 30m, que também é o valor padrão. Um prefixo permanece elegível por pelo menos 30 minutos depois da gravação ou reutilização mais recente, embora a OpenAI possa mantê-lo por mais tempo.
Modelos anteriores utilizam prompt_cache_retention. Conforme o modelo e a política da organização, os valores podem incluir:
in_memory: normalmente entre cinco e dez minutos de inatividade, com limite de até uma hora;24h: retenção estendida que pode alcançar até 24 horas.
Não copie prompt_cache_retention para uma família nova sem verificar a documentação. Ao migrar para GPT-5.6 ou posterior, a orientação atual é usar prompt_cache_options.ttl.
Cache de prompt e privacidade
Segundo a documentação, estados de cache podem ser armazenados como tensores criptografados em memória ou armazenamento associado às GPUs. Os caches não são compartilhados entre organizações nem entre limites regionais de processamento.
O uso do cache não substitui uma política de dados. Antes de colocar conteúdo sensível em um prefixo reutilizável:
- remova dados pessoais desnecessários;
- evite segredos e chaves;
- separe a contabilização entre clientes quando necessário;
- verifique a política de Zero Data Retention da organização;
- confirme a região de processamento;
- documente o período esperado de reutilização;
- avalie se o prefixo realmente precisa conter o documento completo.
Não inclua dados pessoais no próprio prompt_cache_key. Use identificadores internos pseudonimizados, como cliente_123, em vez de e-mail, telefone ou nome completo.
Prompt caching não é um objeto de prompt salvo
Prompt caching e reusable prompt objects são recursos diferentes:
| Recurso | Finalidade |
|---|---|
| Prompt caching | Reutilizar processamento computacional de um prefixo repetido. |
| Prompt armazenado ou versionado | Guardar conteúdo e variáveis de um prompt para reutilização lógica. |
| Prompt em código | Manter instruções sob revisão, testes e versionamento da aplicação. |
A OpenAI está descontinuando os reusable prompt objects: a criação foi despriorizada em 3 de junho de 2026 e o endpoint v1/prompts está programado para ser desligado em 30 de novembro de 2026. A orientação atual é versionar prompts no código da aplicação.
Essa mudança não representa o fim do prompt caching. O cache continua sendo um mecanismo de desempenho e cobrança separado.
Erros que reduzem a taxa de cache hit
| Erro | Consequência | Correção |
|---|---|---|
| Dados variáveis no início | O prefixo muda a cada solicitação | Mover os dados variáveis para o final |
| Ferramentas em ordem diferente | As definições deixam de corresponder | Manter lista e schemas estáveis |
| Remover ferramentas em algumas chamadas | O contexto inicial muda | Usar tool_choice: "none" ou restringir ferramentas permitidas |
| Model ID diferente | O cache não é compartilhado entre modelos | Separar métricas por model ID |
| Breakpoint após conteúdo variável | Gravações pouco reutilizáveis | Marcar o final do conteúdo estável |
| Prewarm sem reutilização | Pagamento de cache write sem benefício | Pré-aquecer apenas workflows previsíveis |
| Chave diferente em cada chamada | Pode prejudicar roteamento ou contabilização | Usar uma chave estável dentro do mesmo grupo |
| Prompts abaixo do mínimo | cached_tokens permanece zero | Revisar se o fluxo realmente precisa de cache |
Como medir o resultado em produção
Não use somente a redução teórica de preço. Monitore métricas por recurso, cliente e model ID:
- porcentagem de solicitações com cache hit;
- porcentagem dos tokens de entrada reutilizada;
- razão entre tokens gravados e lidos;
- custo médio por tarefa concluída;
- tempo até o primeiro token;
- latência total;
- taxa de erros;
- qualidade da resposta antes e depois da reorganização;
- volume de conteúdo que nunca é reutilizado.
Uma taxa de cache hit alta não garante economia total se o prompt contém material desnecessário, gera respostas longas ou utiliza ferramentas caras. O objetivo deve ser reduzir o custo do workflow completo, não maximizar uma única métrica.
Checklist de implementação
- identificar o conteúdo repetido;
- medir o tamanho do prefixo;
- colocar conteúdo estável antes do conteúdo variável;
- manter ferramentas e schemas em ordem estável;
- escolher cache implícito ou explícito;
- definir breakpoint no ponto correto;
- configurar o TTL compatível com o modelo;
- evitar dados pessoais na cache key;
- registrar
cached_tokensecache_write_tokens; - comparar custo e latência antes e depois;
- testar comportamento e qualidade;
- acompanhar mudanças de modelo e preços.
O cache de prompt funciona melhor quando a aplicação possui um prefixo longo, estável e repetido. Organize as instruções, ferramentas e referências no início, deixe os dados variáveis no final e use as métricas de uso para confirmar que a reutilização está gerando economia real.