Guia de cache de contexto da OpenAI

Nos modelos GPT-5.6 e posteriores compatíveis, defina prompt_cache_options.ttl em uma solicitação à Responses API para escolher uma duração mínima de cache de 30 minutos ou 12 horas. Os exemplos usam gpt-6.1-terra.

O cache de 12 horas está disponível apenas em /v1/responses, não em /v1/chat/completions. O TTL indica uma duração mínima, não um prazo de exclusão nem uma garantia de acerto de cache em todas as solicitações.

Definir a chave de API

export API_KEY="YOUR_API_KEY"

O texto longo nos exemplos é ilustrativo. Substitua-o pelo conteúdo que deseja reutilizar. O prefixo precisa ter pelo menos 1.024 tokens; esse texto curto sozinho não gera uma gravação no cache.

Usar o cache de 30 minutos

Defina prompt_cache_options.ttl como "30m". Omitir ttl também seleciona 30 minutos. Sem mode, o cache é implícito: o serviço de origem escolhe o ponto de cache automaticamente.

curl "https://api.apimart.ai/v1/responses" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "gpt-6.1-terra",
  "prompt_cache_options": {
    "ttl": "30m"
  },
  "input": [
    {
      "role": "user",
      "content": [
        {
          "type": "input_text",
          "text": "Long reference material to reuse (at least 1024 tokens)... Summarize the key points."
        }
      ]
    }
  ]
}'

Usar o cache de 12 horas

Altere o mesmo campo para "12h" e mantenha o restante da estrutura:

curl "https://api.apimart.ai/v1/responses" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "gpt-6.1-terra",
  "prompt_cache_options": {
    "ttl": "12h"
  },
  "input": [
    {
      "role": "user",
      "content": [
        {
          "type": "input_text",
          "text": "Long reference material to reuse (at least 1024 tokens)... Summarize the key points."
        }
      ]
    }
  ]
}'

Reutilizar um prefixo fixo com perguntas diferentes

Para reutilizar um documento longo mudando apenas a última pergunta, defina mode como "explicit" e adicione prompt_cache_breakpoint ao bloco input_text no final do conteúdo fixo. Este exemplo usa 12 horas; para 30 minutos, altere o TTL da solicitação para "30m".

Definir mode: "explicit" sem adicionar um ponto de cache impede leituras e gravações no cache. O ponto abaixo não tem um TTL próprio e herda prompt_cache_options.ttl da solicitação.

curl "https://api.apimart.ai/v1/responses" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "gpt-6.1-terra",
  "prompt_cache_options": {
    "ttl": "12h",
    "mode": "explicit"
  },
  "input": [
    {
      "role": "user",
      "content": [
        {
          "type": "input_text",
          "text": "Long reference material to reuse (at least 1024 tokens)...",
          "prompt_cache_breakpoint": {
            "mode": "explicit"
          }
        }
      ]
    },
    {
      "role": "user",
      "content": [
        {
          "type": "input_text",
          "text": "Summarize the three main points in the reference material."
        }
      ]
    }
  ]
}'

Envie o mesmo modelo, prefixo fixo e ponto de cache nas solicitações seguintes, alterando apenas a última mensagem do usuário. Mantenha o conteúdo, a ordem e as configurações que afetam o contexto. Não é necessário criar ou enviar um ID de cache.

Verificar o uso do cache

Confira usage.input_tokens_details na resposta:

cached_tokens: Tokens lidos do cache nesta solicitação. Um valor maior que 0 indica uma leitura do cache.
cache_write_tokens: Total de tokens gravados no cache nesta solicitação.
cache_write_tokens_details.ttl_30m_tokens: Tokens gravados com TTL de 30 minutos nesta solicitação.
cache_write_tokens_details.ttl_12h_tokens: Tokens gravados com TTL de 12 horas nesta solicitação.

Após a primeira gravação, envie outra solicitação com o mesmo prefixo estável e verifique cached_tokens. O valor pode ser 0 se o prefixo for curto demais, o conteúdo mudar ou não houver acerto de cache.

Exemplo de cache usage e contagem de tokens

Este trecho de resposta mostra apenas usage de um modelo OpenAI compatível com cache, com gravações para ambos os TTLs. Os valores reais dependem da resposta.

{
  "usage": {
    "input_tokens": 12000,
    "input_tokens_details": {
      "cached_tokens": 4000,
      "cache_write_tokens": 7000,
      "cache_write_tokens_details": {
        "ttl_30m_tokens": 5000,
        "ttl_12h_tokens": 2000
      }
    },
    "output_tokens": 1000,
    "total_tokens": 13000
  }
}

Tokens de entrada comuns:

input_tokens - input_tokens_details.cached_tokens - input_tokens_details.cache_write_tokens

cache_write_tokens = ttl_30m_tokens + ttl_12h_tokens
total_tokens = input_tokens + output_tokens

Leituras e gravações no cache já estão incluídas em input_tokens. As duas quantidades por TTL são componentes de cache_write_tokens: não some novamente o total e seus componentes, nem acrescente leituras e gravações à entrada total. Aqui, a entrada comum é 12000 - 4000 - 7000 = 1000, as gravações são 5000 + 2000 = 7000 e o total de tokens é 12000 + 1000 = 13000. Consulte o guia oficial de cache de prompts da OpenAI para entender o funcionamento.

Visão Geral

Modelos

Série de Texto

Série de Imagem

Série de Vídeo

Série de Áudio

Série de Moderação

Gerenciamento de Upload

Gerenciamento de Tarefas

Gerenciamento de Conta

Guia de cache de contexto da OpenAI

Definir a chave de API

Usar o cache de 30 minutos

Usar o cache de 12 horas

Reutilizar um prefixo fixo com perguntas diferentes

Verificar o uso do cache

Exemplo de cache usage e contagem de tokens

​Definir a chave de API

​Usar o cache de 30 minutos

​Usar o cache de 12 horas

​Reutilizar um prefixo fixo com perguntas diferentes

​Verificar o uso do cache

​Exemplo de cache usage e contagem de tokens

Definir a chave de API

Usar o cache de 30 minutos

Usar o cache de 12 horas

Reutilizar um prefixo fixo com perguntas diferentes

Verificar o uso do cache

Exemplo de cache usage e contagem de tokens