> ## Documentation Index
> Fetch the complete documentation index at: https://docs.aihubmix.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Cache de Prompt do GPT
> Cache de prompts GPT: gpt-5.6-sol / gpt-5.6-terra / gpt-5.6-luna com escrita a 1.25x, leitura a 0.1x, prompt_cache_key e breakpoints de cache explícitos.
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`:
```shell Curl theme={null}
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."
}
]
}'
```
```py Python (OpenAI SDK) theme={null}
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`):
```json theme={null}
// 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](https://openai.com/index/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](https://developers.openai.com/api/docs/guides/prompt-caching), o escopo de aplicação desses multiplicadores é descrito como "GPT-5.6 models and later model families". Os preços oficiais de cada modelo estão em [OpenAI Pricing](https://developers.openai.com/api/docs/pricing); os preços efetivos na AIHubMix estão no [catálogo de modelos](https://aihubmix.com/models).
A partir dos multiplicadores 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](https://aihubmix.com/models).
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). Os multiplicadores 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:
1. 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;
2. 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);
3. 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:
1. **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.
2. **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.
3. **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](https://developers.openai.com/api/docs/guides/prompt-caching): "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:
```json theme={null}
{
"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):
```json theme={null}
{
"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](/pt/api/Claude-Cache).
### 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, multiplicadores e parâmetros desta página vêm das seguintes fontes oficiais da OpenAI:
* [Anúncio de lançamento do GPT-5.6](https://openai.com/index/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](https://developers.openai.com/api/docs/guides/prompt-caching): mecanismo, parâmetros, campos de usage e limites
* [OpenAI Pricing](https://developers.openai.com/api/docs/pricing): preços oficiais de cada modelo
* [Documentação do modelo GPT-5.6](https://platform.openai.com/docs/models/gpt-5.6-sol): 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](https://aihubmix.com/models).
***
Última atualização: 2026-07-10