Cache de Prompt do GPT

O cache de prompts (Prompt Caching) dos modelos da série GPT (gpt-4o e posteriores) é ativado automaticamente: quando o prefixo da requisição atinge 1.024 tokens e é idêntico, caractere por caractere, ao de uma requisição recente, a parte com acerto é cobrada pelo preço de leitura de cache, ao mesmo tempo em que a latência do primeiro token diminui. A série GPT-5.6 (gpt-5.6-sol / gpt-5.6-terra / gpt-5.6-luna) atualizou o mecanismo de cache: a escrita de cache passa a ser cobrada separadamente (1.25x o preço de entrada), a leitura de cache custa 0.1x o preço de entrada, o cache é mantido por no mínimo 30 minutos, e foram adicionados o prompt_cache_key para correspondência mais confiável e o parâmetro de ponto de quebra de cache explícito. Resumo do comportamento de cache das duas gerações de modelos:

	Antes do GPT-5.6	GPT-5.6 e posteriores
Modo de cache	Automático	Automático + ponto de quebra explícito
Comprimento mínimo de cache	1.024 tokens	1.024 tokens
Cobrança de escrita de cache	Sem cobrança adicional	1.25x o preço base de entrada
Cobrança de leitura de cache	Preço de leitura de cache do modelo correspondente	0.1x o preço base de entrada
Retenção do cache	Limpo após 5–10 minutos de inatividade, no máximo 1 hora	Mantido por no mínimo 30 minutos
`prompt_cache_key`	Opcional, usado para aumentar a taxa de acertos	Exigido pela documentação oficial para habilitar a correspondência de cache mais confiável
Retenção estendida de 24 horas	Suportada por alguns modelos (`prompt_cache_retention`)	Substituída por `prompt_cache_options.ttl`, atualmente apenas `"30m"`

Início rápido

O cache de prompts não requer configuração adicional: envie duas requisições consecutivas com o mesmo prefixo longo; se usage.prompt_tokens_details.cached_tokens na segunda resposta for maior que 0, houve acerto. Para a série GPT-5.6, recomenda-se também definir prompt_cache_key:

curl https://aihubmix.com/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $AIHUBMIX_API_KEY" \
  -d '{
    "model": "gpt-5.6-sol",
    "prompt_cache_key": "my-app-report-assistant-v1",
    "messages": [
      {
        "role": "system",
        "content": "You are a meticulous assistant for analyzing quarterly financial reports... [coloque aqui instruções longas fixas ou material de referência, ≥1024 tokens]"
      },
      {
        "role": "user",
        "content": "Summarize the key figures in one sentence."
      }
    ]
  }'

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["AIHUBMIX_API_KEY"],  # A chave é lida da variável de ambiente
    base_url="https://aihubmix.com/v1",
)

long_context = "You are a meticulous assistant for analyzing quarterly financial reports... [instruções longas fixas ou material de referência, ≥1024 tokens]"

# Duas requisições consecutivas com o mesmo prefixo; a segunda acerta o cache
for i in range(2):
    completion = client.chat.completions.create(
        model="gpt-5.6-sol",
        prompt_cache_key="my-app-report-assistant-v1",
        messages=[
            {"role": "system", "content": long_context},
            {"role": "user", "content": "Summarize the key figures in one sentence."},
        ],
    )
    print(completion.usage.prompt_tokens_details)

Usage medido nas duas chamadas (2026-07-10, gpt-5.6-sol):

// 1ª chamada: sem acerto
"prompt_tokens_details": {"audio_tokens": 0, "cached_tokens": 0}

// 2ª chamada: o prefixo acerta o cache
"prompt_tokens_details": {"audio_tokens": 0, "cached_tokens": 2816}

Cobrança do cache

Regras de cobrança de cache da série GPT-5.6:

Item de cobrança	Taxa
Tokens de entrada regulares	Preço da plataforma
Tokens de escrita de cache	1.25x o preço base de entrada
Tokens de leitura de cache	0.1x o preço base de entrada
Tokens de saída	Preço da plataforma

Descrição oficial da OpenAI para essa regra (do anúncio de lançamento do GPT-5.6): “For GPT‑5.6 and later models, cache writes are billed at 1.25x the model’s uncached input rate, while cache reads continue to receive the 90% cached-input discount.”. No guia oficial de cache de prompts, o escopo de aplicação dessas regras de cobrança é descrito como “GPT-5.6 models and later model families”. Os preços oficiais de cada modelo estão em OpenAI Pricing; os preços efetivos na AIHubMix estão no catálogo de modelos. A partir das regras de preço oficiais, o balanço pode ser calculado diretamente: escrever um prefixo no cache custa 0.25x o preço de entrada a mais do que não usar cache; a partir daí, cada acerto economiza 0.9x o preço de entrada. Basta que o prefixo seja reutilizado 1 vez para haver economia líquida; quanto mais reutilizações, maior a economia. Requisições de uso único cujo prefixo nunca será reutilizado pagam a taxa de escrita a mais; nesse caso, o cache pode ser desativado com o modo explicit (veja “Parâmetros de cache do GPT-5.6” abaixo). Nos modelos anteriores ao GPT-5.6, a escrita de cache não tem cobrança adicional e a leitura de cache é cobrada pelo preço de leitura de cache do modelo correspondente; os preços de cada modelo estão no catálogo de modelos.

A série GPT-5.6 distingue faixas de contexto curto e longo: quando a entrada de uma única requisição ultrapassa 272K tokens, toda a requisição é cobrada pela faixa de contexto longo (entrada 2x, saída 1.5x). As proporções de preço de 1.25x para escrita e 0.1x para leitura de cache também se aplicam na faixa de contexto longo, tendo como base o preço de entrada dessa faixa.

Como o cache é ativado automaticamente

Ao enviar uma requisição, o sistema verifica se o prefixo da requisição (na ordem de serialização de messages, tools etc.) é idêntico, caractere por caractere, ao prefixo de uma requisição recente:

Quando o prefixo atinge 1.024 tokens e um prefixo em cache idêntico é encontrado, a parte com acerto é cobrada pelo preço de leitura de cache e a latência do primeiro token diminui;
Quando nenhum é encontrado, a requisição é processada como entrada regular e o prefixo é escrito no cache (no GPT-5.6 e posteriores, a escrita é cobrada a 1.25x);
O acerto exige que o prefixo seja idêntico byte a byte; qualquer alteração em um ponto do prefixo invalida todo o cache a partir daquela posição.

Os cenários com maior benefício:

Instruções de sistema longas e fixas ou grande quantidade de exemplos few-shot
Material de referência longo citado repetidamente em cenários RAG
Workflows de agentes com muitas definições de ferramentas (tools)
Conversas longas de múltiplos turnos em que as mensagens são apenas acrescentadas ao final

Retenção do cache: nos modelos anteriores ao GPT-5.6, o cache é limpo após 5–10 minutos de inatividade, com máximo de 1 hora; no GPT-5.6 e posteriores, é mantido por no mínimo 30 minutos e, na prática, pode durar mais. O cache não é compartilhado entre organizações e não tem efeito sobre o conteúdo da saída.

Parâmetros de cache do GPT-5.6

A série GPT-5.6 adiciona três parâmetros relacionados a cache (comuns às APIs Chat Completions e Responses):

Parâmetro	Tipo / posição	Valores	Padrão
`prompt_cache_key`	string, nível superior do corpo da requisição	Identificador estável personalizado; recomenda-se separar por aplicação ou tenant; o tráfego total de cada key deve ficar em torno de 15 requisições/minuto	Nenhum
`prompt_cache_options`	object, nível superior do corpo da requisição	`mode`: `"implicit"` / `"explicit"`; `ttl`: apenas `"30m"`	`mode: "implicit"`, `ttl: "30m"`
`prompt_cache_breakpoint`	object, dentro do bloco de conteúdo	`{"mode": "explicit"}`, marca o fim do prefixo cacheável	Sem ponto de quebra

Os modelos anteriores ao GPT-5.6 rejeitam requisições com prompt_cache_options ou prompt_cache_breakpoint; o parâmetro de retenção estendida de 24 horas dos modelos antigos, prompt_cache_retention ("24h" / "in_memory"), é substituído por prompt_cache_options.ttl no GPT-5.6 e posteriores. Relação entre os três modos de controle de cache:

Padrão (modo implicit): mesmo sem nenhum parâmetro de cache, o cache é escrito automaticamente — o sistema define o ponto de quebra automaticamente na posição da mensagem mais recente. No GPT-5.6 e posteriores, as escritas de cache automáticas também são cobradas a 1.25x.
Modo implicit + ponto de quebra explícito: além do ponto de quebra automático, é possível definir prompt_cache_breakpoint em um bloco de conteúdo para fixar a fronteira do cache no fim do conteúdo estável; alterações no conteúdo posterior ao ponto de quebra não invalidam o cache do prefixo anterior a ele.
Modo explicit: com prompt_cache_options.mode definido como "explicit", apenas os pontos de quebra manuais são usados; se nenhum ponto de quebra for definido, a requisição não usa cache nem gera cobrança de escrita de cache. Texto oficial: “If the conversation contains no explicit breakpoints, the request does not use prompt caching or incur cache-write charges.”

Usando o modo explicit para desativar a cobrança de escrita de cache em requisições longas de uso único:

{
  "model": "gpt-5.6-sol",
  "prompt_cache_options": {"mode": "explicit"},
  "messages": [
    {"role": "user", "content": "[conteúdo longo de uso único que não será reutilizado]"}
  ]
}

Uso oficial do ponto de quebra explícito (o ponto de quebra é definido no fim do bloco de conteúdo longo e fixo):

{
  "model": "gpt-5.6-sol",
  "prompt_cache_key": "my-app-report-assistant-v1",
  "messages": [
    {
      "role": "system",
      "content": [
        {
          "type": "text",
          "text": "[instruções longas fixas ou material de referência, ≥1024 tokens]",
          "prompt_cache_breakpoint": {"mode": "explicit"}
        }
      ]
    },
    {"role": "user", "content": "Summarize the key figures in one sentence."}
  ]
}

Restrições rígidas (regras oficiais):

Cada requisição cria no máximo 4 novas escritas de cache; no modo implicit, o ponto de quebra automático ocupa 1 delas;
O prefixo anterior ao ponto de quebra ainda precisa atingir 1.024 tokens para ser cacheado;
Na leitura, o prefixo com correspondência mais longa é escolhido entre os 50 pontos de quebra mais recentes;
Definir um ponto de quebra em um bloco de conteúdo sem suporte retorna 400 invalid_request_error. Chat Completions suporta blocos text / image_url / input_audio / file / refusal; a Responses API suporta blocos input_text / input_image / input_file.

O suporte da AIHubMix ao ponto de quebra prompt_cache_breakpoint em blocos de conteúdo e aos acertos de cache pela Responses API está em fase de aprimoramento. No estágio atual, recomenda-se usar o cache automático via Chat Completions com prompt_cache_key definido (exemplo do início rápido desta página, com acerto verificado); o modo explicit de prompt_cache_options funciona normalmente para desativar a escrita de cache. Esta página será atualizada conforme o progresso do suporte.

Por que o cache não teve acerto

O acerto exige que todo o conteúdo anterior à posição do ponto de quebra seja idêntico byte a byte. Se cached_tokens continuar em 0 na segunda requisição, verifique a lista a seguir:

Prefixo abaixo de 1.024 tokens: requisições abaixo do comprimento mínimo de cache são processadas como entrada regular;
Conteúdo variável misturado no prefixo: timestamps, IDs de sessão, variáveis de usuário etc. devem ficar depois do conteúdo fixo; qualquer alteração no prefixo invalida o cache a partir daquele ponto;
Definições ou ordem de tools alteradas: a lista de ferramentas participa do cálculo do prefixo; definições e ordenação devem ser exatamente iguais;
Parâmetro detail de imagens inconsistente: detail afeta a tokenização das imagens e precisa permanecer o mesmo;
Schema de saída estruturada alterado: o JSON Schema de response_format participa do cache como prefixo da mensagem de sistema; mudar o schema muda o prefixo;
reasoning_effort alterado: listado oficialmente entre as causas comuns de menor taxa de acertos de cache (“Changes to reasoning effort”);
Período de retenção do cache excedido: antes do GPT-5.6, o cache é limpo após 5–10 minutos de inatividade; no GPT-5.6 e posteriores, é mantido por no mínimo 30 minutos;
prompt_cache_key ausente (GPT-5.6): sem ele, acertos automáticos ainda podem ocorrer, mas o mecanismo de correspondência mais confiável não é usado.

Melhores práticas

Coloque o conteúdo fixo (instruções de sistema, exemplos, material de referência, definições de ferramentas) no início da requisição e o conteúdo que muda a cada turno no final;
Defina o mesmo prompt_cache_key estável para o tráfego que compartilha o mesmo prefixo, mantendo o tráfego total de cada key em torno de 15 requisições/minuto; acima disso, divida em mais keys por área de negócio;
Em conversas de múltiplos turnos, apenas acrescente mensagens ao final, sem modificar mensagens do histórico;
Mantenha tráfego contínuo para requisições com o mesmo prefixo, reduzindo a limpeza do cache;
Para requisições longas de uso único cujo prefixo não será reutilizado, use o modo explicit para evitar a cobrança de escrita de cache (GPT-5.6 e posteriores);
Monitore continuamente os acertos por meio de usage.prompt_tokens_details.cached_tokens.

Perguntas Frequentes (FAQ)

O cache de prompts do GPT precisa ser ativado manualmente?

A ativação manual não é necessária: prefixos que atingem 1.024 tokens são cacheados automaticamente. No GPT-5.6 e posteriores, recomenda-se também definir prompt_cache_key para obter uma correspondência de cache mais confiável.

Como é calculada a taxa de escrita de cache do GPT-5.6? Como evitar taxas de escrita desnecessárias?

A escrita de cache é cobrada a 1.25x o preço base de entrada e a leitura a 0.1x; basta que o prefixo seja reutilizado 1 vez para haver economia líquida. Para requisições longas de uso único cujo prefixo não será reutilizado, defina prompt_cache_options.mode como "explicit" sem definir pontos de quebra; a requisição então não usa cache e não gera taxa de escrita.

Por quanto tempo o cache é mantido?

No GPT-5.6 e posteriores, por no mínimo 30 minutos (ttl atualmente aceita apenas "30m"; na prática, a retenção pode ser maior); nos modelos anteriores ao GPT-5.6, o cache é limpo após 5–10 minutos de inatividade, com máximo de 1 hora, e alguns modelos antigos suportam retenção estendida com prompt_cache_retention: "24h".

Qual é a diferença entre o ponto de quebra explícito do GPT-5.6 e o cache_control do Claude?

Ambos servem para fixar a fronteira do cache no fim do conteúdo estável. Principais diferenças: o GPT-5.6 faz cache automaticamente sem nenhum parâmetro e o ponto de quebra é um controle fino opcional, enquanto o Claude exige a habilitação do cache na requisição (cache_control de nível superior para ponto de quebra automático ou ponto de quebra explícito em nível de bloco de conteúdo); o GPT-5.6 mantém o cache por no mínimo 30 minutos, e o Claude usa 5 minutos por padrão, com opção de 1 hora; em ambos, a leitura de cache é cobrada a 0.1x o preço de entrada. O uso no Claude está em Cache de Prompt do Claude.

O cache afeta o conteúdo da saída?

Não afeta. Regra oficial: o cache de prompts afeta apenas o processamento e a cobrança do lado da entrada; a forma como o modelo gera a saída é exatamente a mesma de quando o cache não é usado.

Referências oficiais

Os mecanismos, proporções de preço e parâmetros desta página vêm das seguintes fontes oficiais da OpenAI:

Anúncio de lançamento do GPT-5.6: regra de cobrança de escrita de cache a 1.25x e desconto de 90% na leitura
Guia de cache de prompts: mecanismo, parâmetros, campos de usage e limites
OpenAI Pricing: preços oficiais de cada modelo
Documentação do modelo GPT-5.6: janela de contexto e limiar de cobrança de contexto longo

Os preços efetivos de cada modelo na AIHubMix estão no catálogo de modelos.

Última atualização: 2026-07-10

Começar

Recursos de gateway

Capacidades do modelo

Referência de protocolo

Gestão de plataforma

Privacidade e termos

Cache de Prompt do GPT

Início rápido

Cobrança do cache

Como o cache é ativado automaticamente

Parâmetros de cache do GPT-5.6

Por que o cache não teve acerto

Melhores práticas

Perguntas Frequentes (FAQ)

O cache de prompts do GPT precisa ser ativado manualmente?

Como é calculada a taxa de escrita de cache do GPT-5.6? Como evitar taxas de escrita desnecessárias?

Por quanto tempo o cache é mantido?

Qual é a diferença entre o ponto de quebra explícito do GPT-5.6 e o cache_control do Claude?

O cache afeta o conteúdo da saída?

Referências oficiais

​Início rápido

​Cobrança do cache

​Como o cache é ativado automaticamente

​Parâmetros de cache do GPT-5.6

​Por que o cache não teve acerto

​Melhores práticas

​Perguntas Frequentes (FAQ)

​O cache de prompts do GPT precisa ser ativado manualmente?

​Como é calculada a taxa de escrita de cache do GPT-5.6? Como evitar taxas de escrita desnecessárias?

​Por quanto tempo o cache é mantido?

​Qual é a diferença entre o ponto de quebra explícito do GPT-5.6 e o cache_control do Claude?

​O cache afeta o conteúdo da saída?

​Referências oficiais

Início rápido

Cobrança do cache

Como o cache é ativado automaticamente

Parâmetros de cache do GPT-5.6

Por que o cache não teve acerto

Melhores práticas

Perguntas Frequentes (FAQ)

O cache de prompts do GPT precisa ser ativado manualmente?

Como é calculada a taxa de escrita de cache do GPT-5.6? Como evitar taxas de escrita desnecessárias?

Por quanto tempo o cache é mantido?

Qual é a diferença entre o ponto de quebra explícito do GPT-5.6 e o cache_control do Claude?

O cache afeta o conteúdo da saída?

Referências oficiais