Depois de a OpenAI acrescentar 12 horas de cache de prompts à API Responses em 20 de outubro, que números de usage decidem a conta?

Em 21 de outubro de 2026: 12 horas é uma vida mínima na API Responses. Uma escrita de 30 minutos é 1,25× e uma de 12 horas é 2,5×. A conta está em cached_tokens e dois campos ttl. Não some cache_write_tokens outra vez.

O que entrou em 20 de outubro é uma vida mínima de cache na API Responses. Não é um relógio de apagamento. Se omitir prompt_cache_options.ttl, o valor é 30m e a escrita fica a 1,25× o preço de entrada ordinário. 12h escreve a 2,5×. Esses multiplicadores são o preço total da escrita, não um acréscimo sobre a entrada ordinária. A leitura é a mesma nas duas vidas: 0,1× na maioria dos modelos GPT-5.6 e posteriores, e 0,05× no GPT-6.1 Sol. A conta está em cached_tokens, ttl_30m_tokens e ttl_12h_tokens. cache_write_tokens já é a soma dos dois últimos.

Este texto está escrito para 21 de outubro de 2026, a partir do registo do dia anterior e do guia de cache de prompts. O registo aponta v1/responses. Ontem tratava-se de qual campo leva a resposta. Aqui a conta lê-se da mesma forma.

O que 20 de outubro acrescentou mesmo

O registo diz que já se pode escolher um cache de prompts de 12 horas na API. O guia põe o interruptor em prompt_cache_options.ttl da API Responses, para GPT-5.6 e posteriores.

ttlVida mínimaTaxa de escritaPara que o guia a indica
30m, o padrão se for omitido30 minutos1,25× a entrada ordináriaConversas e passos de agente próximos
12h12 horas2,5× a entrada ordináriaInstruções e material de referência com intervalos mais longos

A OpenAI pode guardar uma entrada mais tempo do que o mínimo pedido. 12h não marca uma hora de apagamento nem muda o teto da política de retenção. Também não promete reutilizar os tensores KV nem uma latência menor. Valores não suportados devolvem 400 invalid_request_error. Isto não muda prompt_cache_retention dos modelos anteriores. Na tabela, o GPT-5.5 só usa 24h e não tem um custo extra de escrita.

Qual API aceita 12h

A tabela escreve as 12 horas dentro da API Responses. O ttl do pedido vale para o ponto implícito e para os pontos explícitos sem ttl próprio. Um ponto explícito substitui-o com prompt_cache_breakpoint.ttl. Se faltarem os dois, a vida é 30m.

A referência de criação de Chat Completions continua a listar prompt_cache_options.ttl como um valor que por agora só aceita 30m. O guia não oferece 12h em chat/completions. As chamadas de modelo da API Agents seguem o mesmo cache da Responses. O registo de 20 de outubro nomeia v1/responses.

Um pedido escreve no máximo quatro pontos. O modo implícito ocupa um, e ficam três para os explícitos. Com mode em explicit e nenhum ponto explícito, o pedido não usa cache de prompts. No GPT-5.6 e posteriores, um prefixo que se possa cachear precisa de pelo menos 1.024 tokens de entrada visíveis. O conteúdo oculto da OpenAI não entra nesse mínimo. Os modelos anteriores arredondam cached_tokens para baixo até um múltiplo de 128. O GPT-5.6 e posteriores relatam o limite exato, sem os tokens ocultos.

Como duas vidas se cobram numa só chamada

Um ponto cobre todo o prefixo anterior. Dentro de um pedido, cada token é cobrado uma vez, com a vida mais longa das escritas selecionadas que o cobrem. Uma escrita posterior de 12 horas também dá cobertura de 12 horas aos pontos anteriores dentro desse prefixo. As quatro linhas do guia:

Cache anteriorPontos escolhidosLeiturasEscritas de 30 minEscritas de 12 h
Nenhuma12h em 2.000 e depois 30m em 5.00003.0002.000
Nenhuma30m em 2.000 e depois 12h em 5.000005.000
30 minutos válidos até 2.00012h em 5.000005.000
12 horas válidas até 2.00030m em 5.0002.0003.0000

Subir uma cobertura válida de 30 minutos para 12 horas volta a escrever esses tokens à taxa de 12 horas, sem crédito da escrita anterior. O que já está numa entrada válida de 12 horas continua a ser leitura. Uma leitura de 30 minutos renova a cobertura para pelo menos 30 minutos depois dessa leitura. Se a entrada já tiver 12 horas válidas, fica o mais tardio entre o prazo existente e 30 minutos depois da leitura. Não reinicia um relógio de 12 horas e não cobra outra escrita.

Como somar os números de usage

Nos modelos Responses que aceitam prompt_cache_options, as escritas dividem-se em cache_write_tokens_details. ttl_30m_tokens e ttl_12h_tokens não se sobrepõem e somam cache_write_tokens. Os dois campos voltam, e um pode ser zero. cached_tokens conta tokens cobrados como leitura. Exclui os cobrados como escrita, incluindo uma subida de 30 minutos para 12 horas.

{
  "usage": {
    "input_tokens": 12000,
    "input_tokens_details": {
      "cached_tokens": 4000,
      "cache_write_tokens": 7000,
      "cache_write_tokens_details": {
        "ttl_30m_tokens": 3000,
        "ttl_12h_tokens": 4000
      }
    }
  }
}

A entrada ordinária é 12000 - 4000 - 7000 = 1000. O custo de entrada é a entrada ordinária vezes o preço de entrada, cached_tokens vezes o preço de leitura de cache, ttl_30m_tokens vezes 1,25× o preço de entrada e ttl_12h_tokens vezes 2,5×, a dividir por 1.000.000. O guia, com 1 $ por milhão de entrada e 0,10 $ de leitura de cache, obtém 0,01515 $ para essa divisão. O GPT-6.1 Sol lê a 0,05×, que não é o 0,1× desse exemplo. As mesmas contagens a 0,05× não continuam a ser 0,01515 $.

Uma falha costuma ser um prefixo mudado

O cache guarda tensores KV, não os tokens originais. O prefixo renderizado tem de coincidir por inteiro. O guia nomeia definições que mudam o prefixo: model, tools, parallel_tool_calls, text.format (a saída estruturada acrescenta instruções de formato e o esquema enviado), reasoning.effort, text.verbosity e context_management quando reescreve o texto anterior. Se o esquema mudar, o prefixo deixa de coincidir a partir dessa mudança.

As entradas vivem em máquinas concretas. Acima de 15 pedidos por minuto, o tráfego pode ir para uma máquina que não tem a entrada. Os caches não atravessam organizações nem fronteiras regionais de processamento. No GPT-5.6 e posteriores, a OpenAI encaminha sozinha. prompt_cache_key já não serve para otimizar acertos; ainda pode separar a contabilidade por cliente. A nota de migração substitui prompt_cache_retention por prompt_cache_options.ttl.

Guarde esta ficha de uso

De uma chamada, guarde pelo menos estes campos:

{
  "api": "responses",
  "model": "gpt-6.1-sol",
  "request_ttl": "30m",
  "input_tokens": 12000,
  "cached_tokens": 4000,
  "cache_write_tokens": 7000,
  "ttl_30m_tokens": 3000,
  "ttl_12h_tokens": 4000,
  "ordinary_input_tokens": 1000
}

ordinary_input_tokens tem de ser a entrada menos as leituras menos as escritas. Os dois campos ttl têm de voltar a somar cache_write_tokens. Se não somarem, uma subida foi contada como leitura, ou cache_write_tokens foi somado uma segunda vez.

  • Validador JSON — confirme que os campos existem e que os dois ttl somam.
  • JSON Diff — compare dois objetos usage e veja se o acréscimo é uma escrita de 12 horas ou entrada ordinária.
  • JSONPath — tire as respostas cujo ttl_12h_tokens é maior que zero.

Perguntas

O Chat Completions pode pôr ttl em 12h?

O guia põe 12h na API Responses. A referência de criação de Chat Completions continua a dizer que ttl só aceita 30m por agora. O registo de 20 de outubro nomeia v1/responses.

12h quer dizer que a entrada é apagada ao fim de 12 horas?

Não. É uma vida mínima. A OpenAI pode guardá-la mais tempo. Não marca uma hora de apagamento, não muda o teto de retenção e não promete o acerto seguinte nem uma latência menor.

A taxa de 2,5× é um acréscimo sobre a entrada ordinária?

Não. O guia diz que é o preço total da escrita. Um token cobrado como escrita de 12 horas não é também cobrado como entrada ordinária. A entrada ordinária é input_tokens menos cached_tokens menos cache_write_tokens.

Se já paguei uma escrita de 30 minutos, isso é creditado ao subir para 12 horas?

Não. Uma cobertura válida de 30 minutos subida para 12 horas volta a ser escrita à taxa de 12 horas. O que já está numa entrada válida de 12 horas continua a ser leitura.

Devo somar cache_write_tokens outra vez?

Não. É ttl_30m_tokens mais ttl_12h_tokens. Multiplique essas duas partes por 1,25× e 2,5× o preço de entrada. Somar cache_write_tokens por cima conta a escrita duas vezes.

cached_tokens acima de zero quer dizer que a chamada foi mais rápida?

O guia diz que a vida mínima decide se os tokens podem ser cobrados como leitura. Não promete que cada pedido reutilize os KV numa máquina, nem uma latência menor. Acima de 15 pedidos por minuto, o tráfego também pode ir para uma máquina sem a entrada.

Fecho

A mudança de 20 de outubro é uma escolha de vida mínima na API Responses. Uma escrita de 30 minutos é 1,25×, uma de 12 horas é 2,5×, e a leitura fica em 0,1×, ou 0,05× no Sol. O usage parte as escritas em dois campos ttl. Somar cache_write_tokens por cima duplica a escrita.

Um esquema, uma definição de ferramenta e o identificador do modelo mudam o prefixo. Na ficha, guarde que a API era responses, o ttl enviado e se os quatro números de uso ainda cumprem a subtração.