GPT-6.2 Responses API: não edite o prefixo ou perca o raciocínio
A partir de GPT-6.2 Astra e Sol, editar o histórico anterior na Responses API descarta os itens de raciocínio seguintes. Mantenha o prefixo inalterado com turnos append-only, configuration_update, additional_tools e instruções na primeira mensagem developer, e valide com input_transformations e Prompt Cache Diagnostics.
Conteúdo

A partir de gpt-6.2-astra e gpt-6.2-sol, a OpenAI Responses API descarta itens de raciocínio após uma edição do prefixo no meio da conversa, um downgrade de modelo ou uma alteração de organização ou usuário final. Isso afeta todo desenvolvedor e toda equipe de agentes cujo código reescreve mensagens developer anteriores, corta resultados de ferramentas passados ou altera parâmetros de nível superior como reasoning.effort e tools entre turnos. Migre sua integração para um histórico input somente de acréscimo (append-only), use configuration_update e additional_tools para mudanças no meio da conversa e verifique input_transformations em cada resposta para confirmar que nenhum raciocínio saiu do contexto.
Escolha uma rota para chamadas GPT-6.2 na Responses API
GPT-6.2 Astra e Sol aceitam Chat Completions para texto, mas chamadas de ferramentas exigem a Responses API, e os controles de preservação de prefixo (configuration_update, additional_tools e input_transformations) existem apenas na Responses API. Escolha uma rota de API que exponha POST /v1/responses e combine com seu acesso e cobrança.
| Rota | Requisitos | Unidade de cobrança | Observações da Responses API | Quando escolher |
|---|---|---|---|---|
| Gateway de API BetterToken | Conta BetterToken, API Key do console e saldo para cobrança conforme o uso (o saldo pago adquirido não zera todo mês) | Pela unidade de cobrança atual do modelo (tokens de entrada, saída e cache podem ter preços e regras distintos); veja os preços atuais | https://www.bettertoken.ai/v1 (POST /v1/responses) lista gpt-6.2-astra e gpt-6.2-sol; teste antes com sua chave o replay sem estado com store: false e o repasse de configuration_update e input_transformations | Quando você quer acessar os modelos disponíveis com uma única API Key, com o uso cobrado do saldo, ou não consegue usar a cobrança direta da OpenAI |
| OpenAI API direta | Conta OpenAI em país ou território compatível e cobrança de API | Por 1M de tokens de entrada, entrada em cache, escrita em cache e saída | Documenta suporte nativo para configuration_update, input_transformations, prompt_cache_diagnostics, previous_response_id, janelas de conclusão em segundo plano e Zero Data Retention (ZDR) no nível da organização | Quando você tem acesso direto à OpenAI e depende de estado hospedado na OpenAI, ZDR ou recursos beta documentados |
Verifique o replay append-only e a detecção de prefixo na BetterToken
A BetterToken oferece uma rota de API compatível com OpenAI em https://www.bettertoken.ai/v1 (POST /v1/responses), autenticada com sua API Key do console da BetterToken. Em 2026-11-21, gpt-6.2-sol e gpt-6.2-astra constam como disponíveis no endpoint Responses. A BetterToken é uma plataforma multimodelo e camada de acesso via API, não um produto oficial da OpenAI. Sua referência da Responses API não verifica o repasse do replay criptografado sem estado com store: false, nem de configuration_update, input_transformations ou prompt_cache_diagnostics. Execute esta checagem controlada de dois turnos sem estado na sua chave antes de publicar em produção.
Exporte sua chave da BetterToken no Bash sem exibi-la no terminal:
read -rs BETTERTOKEN_API_KEY && export BETTERTOKEN_API_KEY
Envie o turno 1 com store: false e confirme que a resposta devolve pelo menos um item reasoning com encrypted_content. Em seguida, compare duas chamadas sem estado no turno 2: a chamada append_only reenvia o histórico anterior sem alterações, enquanto a chamada edited_control modifica apenas a primeira mensagem developer:
import os
from openai import OpenAI
client = OpenAI(
api_key=os.environ["BETTERTOKEN_API_KEY"],
base_url="https://www.bettertoken.ai/v1",
timeout=120.0,
max_retries=0,
)
model = "gpt-6.2-sol" # Or "gpt-6.2-astra"
history = [
{"role": "developer", "content": "You are a backend reviewer. Give concise engineering answers."},
{"role": "user", "content": "Draft a two-step plan to add a non-blocking index on PostgreSQL."},
]
first = client.responses.create(
model=model,
store=False,
reasoning={"effort": "low"},
input=history,
)
reasoning_items = [item for item in first.output if item.type == "reasoning"]
if not reasoning_items:
raise RuntimeError("Turn 1 returned no reasoning items; use a harder prompt or higher effort.")
if not all(getattr(item, "encrypted_content", None) for item in reasoning_items):
raise RuntimeError("Stateless replay unverified: Turn 1 reasoning items lack encrypted_content.")
reasoning_ids = [item.id for item in reasoning_items]
first_output = [item.to_dict() for item in first.output]
follow_up = {"role": "user", "content": "List the failure modes and rollback steps for step 2."}
append_only = client.responses.create(
model=model,
store=False,
reasoning={"effort": "low"},
input=[*history, *first_output, follow_up],
)
edited_history = [{**history[0], "content": history[0]["content"] + " Be brief."}, history[1]]
edited_control = client.responses.create(
model=model,
store=False,
reasoning={"effort": "low"},
input=[*edited_history, *first_output, follow_up],
)
print("reasoning_ids:", reasoning_ids)
print("append_only:", append_only.status, getattr(append_only, "input_transformations", None))
print("edited_control:", edited_control.status, getattr(edited_control, "input_transformations", None))
print("append_only_cached_tokens:", append_only.usage.input_tokens_details.cached_tokens)
Analise quatro sinais antes de colocar o código em produção:
status == "completed"confirma apenas que a API aceitou e concluiu a requisição. Isso não prova que o gateway preservou o raciocínio entre turnos.- Confirme que a lista
reasoning_idsmontada pelo script a partir defirst.outputno turno 1 comstore: falsenão está vazia e que cada item de raciocínio retornado pela API trazencrypted_content. Se o gateway omitirencrypted_content, trate o replay sem estado como não verificado, pois o turno 2 não consegue levar tokens de raciocínio criptografados entre upstreams diferentes. - Compare
input_transformationsnas duas chamadas do turno 2. Um repasse verificado traz uma entradaprefix_mismatchcom um ID presente emreasoning_idsna respostaedited_controle nenhuma entrada emappend_only. Seinput_transformationsvierNoneou vazio nos dois testes, considere a verificação inconclusiva, porque o gateway pode não repassar esse campo. - Teste o repasse de
configuration_updateseparadamente do teste de prefixo. Você pode conferir uma atualização detext.formatenviando outra requisição de turno 2 que alteretext.formatpara um JSON Schema estrito e checando se a saída segue esse esquema. A OpenAI não documenta nenhum campo de resposta que confirme uma atualização dereasoning.effortno meio da conversa (o camporeasoning.effortda resposta continua exibindo o valor do nível da requisição), portanto trateconfiguration_updateparareasoning.effortcomo não verificado via BetterToken.
Para prompt caching, a OpenAI define um prefixo mínimo armazenável em cache de 1,024 tokens de entrada visíveis no GPT-5.6 e modelos posteriores como condição de elegibilidade. Observe append_only.usage.input_tokens_details.cached_tokens para medir a reutilização real quando seu prefixo reutilizável tiver pelo menos 1,024 tokens de entrada visíveis. Consulte os preços atuais para conferir as tarifas do modelo e as regras de cache antes de escalar.
Se preferir chamar a OpenAI diretamente, remova base_url, use OPENAI_API_KEY e siga o guia Keep the prefix unchanged da OpenAI.
Criar uma conta na BetterToken
O que conta como alteração de prefixo no GPT-6.2
O prefixo de um item de raciocínio é todo o histórico de conversa renderizado antes dele. No GPT-6.2, modificar esse histórico anterior faz a API descartar os itens de raciocínio que vêm depois da edição.
A OpenAI documenta duas categorias de alterações de prefixo:
- Editar itens anteriores em
input: encurtar o resultado de uma ferramenta, reescrever uma mensagemdeveloper, reduzir o tamanho de imagens ou arquivos antigos ou substituir turnos anteriores por um resumo. - Alterar parâmetros no nível da requisição entre turnos: atualizar
tools(adicionar, remover, reordenar ou editar esquemas e descrições), mudartext.format, mudar oreasoning.effortno nível superior ou alterarinstructionsem modelos anteriores ao GPT-6.2.
Segundo o guia Reasoning da OpenAI, prefix_mismatch ocorre no GPT-6.2 e versões seguintes quando você insere ou edita conteúdo antes de um item de raciocínio. Apagar itens inteiros sem editar os itens restantes, ou acrescentar itens após o item de raciocínio, não dispara prefix_mismatch por si só. Ainda assim, remover turnos antigos pode reduzir a reutilização do prompt cache, e o Prompt Cache Diagnostics pode relatar input_changed quando essa remoção impede o reaproveitamento.
Edições de prefixo formam um dos cinco motivos de remoção relatados em input_transformations:
reason da remoção | Quando a API remove o item de raciocínio |
|---|---|
prefix_mismatch | No GPT-6.2 e posteriores, houve inserção ou edição de conteúdo antes do item de raciocínio |
end_user_mismatch | No GPT-6.2 e posteriores, safety_identifier difere entre a requisição que criou o item e a que o reutiliza, inclusive quando aparece em apenas uma das duas |
model_mismatch | Você trocou de família de modelos ou fez downgrade dentro da mesma família (um upgrade dentro da mesma família preserva o raciocínio compatível se as demais checagens passarem) |
organization_mismatch | Você reutilizou um item de outra organização ou de outro workspace sob outro usuário |
turn_boundary | O item pertence a qualquer turno anterior enquanto o modelo usa apenas o raciocínio do turno atual (reasoning.context controla a elegibilidade nos modelos compatíveis) |
O que acontece quando a API descarta itens de raciocínio
Uma requisição à Responses API pode terminar com sucesso mesmo quando a API remove itens de raciocínio da entrada do modelo, então essa perda passa despercebida se você não conferir input_transformations na resposta. Editar o prefixo no meio da conversa gera dois efeitos separados em produção:
- Impacto do raciocínio descartado: quando a API remove itens de raciocínio, o modelo pode precisar refazer parte do raciocínio anterior, o que pode aumentar o uso de tokens, o custo e a latência. Se o modelo não recuperar o raciocínio perdido, a qualidade da resposta também pode cair.
- Impacto na quebra do prefixo em cache: como o prompt caching compara as requisições a partir do início, editar o prefixo pode interromper a reutilização do cache desse ponto em diante, o que pode elevar os custos de entrada e deixar as respostas mais lentas.
As tarifas Standard da OpenAI consultadas em 2026-11-21 (para até 272,000 tokens de entrada) mostram o custo que falhas de cache podem acumular:
- GPT-6.2 Astra (
gpt-6.2-astra): $0.40/1M na entrada em cache contra $8/1M na entrada sem cache ($10/1M para escrita em cache de 30 minutos, $20/1M para escrita em cache de 12 horas) e $40/1M na saída. - GPT-6.2 Sol (
gpt-6.2-sol): $0.10/1M na entrada em cache contra $2/1M na entrada sem cache ($2.50/1M para escrita em cache de 30 minutos, $5/1M para escrita em cache de 12 horas) e $10/1M na saída.
Acima de 272,000 tokens de entrada, a OpenAI dobra as tarifas de entrada e cache e cobra 1.5x a tarifa de saída de contexto curto para toda a requisição. Para decidir quando escritas de 12 horas compensam em prefixos estáveis, veja nosso guia de prompt caching de 12 horas da OpenAI.
Atualize parâmetros e contexto sem quebrar o prefixo
Troque edições no histórico existente por itens acrescentados ao final para manter o raciocínio e os prefixos em cache intactos entre turnos.
Altere reasoning.effort e text.format com configuration_update
Alterar reasoning.effort no nível superior pode reescrever instruções ocultas de sistema. Nos modelos GPT-6 e posteriores compatíveis no modo padrão de agente único, mantenha reasoning.effort e text.format inalterados no topo da requisição e acrescente um item configuration_update a input antes da próxima mensagem do usuário:
{
"type": "configuration_update",
"reasoning": {
"effort": "high"
},
"text": {
"format": {
"type": "json_schema",
"name": "migration_checks",
"strict": true,
"schema": {
"type": "object",
"properties": {
"safe": { "type": "boolean" },
"rollback_sql": { "type": "string" }
},
"required": ["safe", "rollback_sql"],
"additionalProperties": false
}
}
}
}
Siga cinco regras ao usar configuration_update:
- Um
configuration_updatecontinua valendo nos turnos seguintes até outra atualização substituí-lo. Atualizar apenasreasoning.effortpreserva uma mudança anterior detext.format, e vice-versa. - O campo
reasoning.effortno objeto de resposta continua relatando o valor do nível da requisição, e não o esforço atualizado. - Leve as atualizações adiante com
previous_response_id, ou reenvie cadaconfiguration_updateem sua posição original quando gerenciarinputmanualmente. - O truncamento automático e o endpoint avulso
/responses/compactrejeitam históricos que contenham itensconfiguration_update. Usecontext_managementoucompaction_trigger(veja a seção de compactação abaixo). - Tanto
gpt-6.2-astraquantogpt-6.2-solrejeitamreasoning.effort: "none". O guia Using GPT-6.2 da OpenAI recomenda começar commedium, ou usarlowno lugar denoneeminimal.
Adicione ou restrinja ferramentas sem alterar tools
Mantenha o array tools, os esquemas e a ordem no nível da requisição idênticos entre turnos. Ajuste as ferramentas disponíveis com três padrões seguros para o prefixo:
- Defina
tool_choicecomo"none"para desativar ferramentas em um turno sem removertools. - Use
tool_choicecomallowed_toolspara restringir quais ferramentas o modelo pode chamar em um turno:
{
"tool_choice": {
"type": "allowed_tools",
"mode": "auto",
"tools": [
{ "type": "function", "name": "get_weather" },
{ "type": "function", "name": "search_docs" }
]
}
}
- Acrescente um item
additional_toolscom papeldeveloperpara adicionar ferramentas no meio da conversa, ou use tool search comdefer_loading: truepara anexar as ferramentas descobertas ao final do contexto. As ferramentas dentro deadditional_toolsficam disponíveis apenas após a posição desse item, então reenvie-o no mesmo lugar:
{
"type": "additional_tools",
"role": "developer",
"tools": [
{
"type": "function",
"name": "get_customer",
"description": "Look up a customer by ID.",
"parameters": {
"type": "object",
"properties": {
"customer_id": { "type": "string" }
},
"required": ["customer_id"],
"additionalProperties": false
}
}
]
}
Separe mensagens developer reutilizáveis de instructions no nível superior
A partir do GPT-6.2, a OpenAI anexa o campo superior instructions depois de input, além dos pontos elegíveis para cache. A OpenAI cobra esses tokens na tarifa de entrada sem cache em toda requisição mesmo que não mudem, e previous_response_id não carrega instructions de um turno para outro.
Organize as instruções conforme o escopo:
- Coloque prompts de sistema reutilizáveis e políticas compartilhadas em uma mensagem
developercomo o primeiro item deinputpara permitir reaproveitamento no prompt caching. - Acrescente uma nova mensagem
developerao final deinputao atualizar instruções reutilizáveis no meio da conversa, em vez de editar a primeira. - Use o campo superior
instructionsapenas para orientações válidas somente na requisição atual.
Lide com compactação e saídas longas de ferramentas
Encurte saídas extensas de ferramentas e reduza imagens ou arquivos antes de enviá-los ao modelo pela primeira vez. Não corte itens antigos de forma retroativa.
A compactação altera o prefixo, o que dificulta evitar falhas de cache nesses turnos. Para sessões longas, o guia Compaction da OpenAI documenta dois caminhos:
- Compactação automática (
context_managementcomcompact_threshold): a OpenAI mantém os itens de raciocínio seguintes apesar da mudança no prefixo. Se turnos anteriores contiveremconfiguration_update, a API emite um novoconfiguration_updatelogo após o itemcompactione guarda as declarações deadditional_toolsdentro do item criptografado de compactação. Reenvie os itens de saída na mesma ordem. - Compactação explícita ou personalizada: o endpoint avulso
/responses/compactrejeita históricos comconfiguration_update; ao chamar/responses/compact, omitainstructionse passe a janela retornada na ordem original. Se o histórico usarconfiguration_update, inclua um itemcompaction_triggerem/responsese depois adicione um novoconfiguration_updaterepetindo cada campo alterado antes da próxima mensagem do usuário. Na compactação personalizada, coloque o resumo compactado no final do contexto em vez de substituir turnos antigos no meio, ou aceite o descarte dos itens de raciocínio.
Verifique a preservação do prefixo com input_transformations e Prompt Cache Diagnostics
Combine duas verificações na resposta: uma lista quais itens de raciocínio a API removeu da entrada do modelo, e a outra identifica o que quebrou o reaproveitamento do prompt cache.
1. Inspecione input_transformations em cada resposta
Na referência de criação da Responses API, input_transformations é um array opcional de objetos {id, action, reason, type} que lista, na ordem da entrada, os itens de raciocínio removidos da entrada do modelo (action é "removed" e type é "reasoning"). Quando reason for "prefix_mismatch", compare esse id com o item de raciocínio no output da resposta anterior que o retornou para localizar qual edição ocorreu antes dele.
2. Execute o Prompt Cache Diagnostics com comparison_response_id
Para entender por que usage.input_tokens_details.cached_tokens ficou abaixo do esperado, escolha uma resposta concluída recente da mesma organização, informe o id dela em prompt_cache_options.comparison_response_id e inspecione prompt_cache_diagnostics:
{
"prompt_cache_diagnostics": {
"type": "cache_miss",
"reason": "tools_changed",
"comparison_reusable_tokens": 5629,
"cache_missed_tokens": 5629
}
}
O guia Prompt cache diagnostics da OpenAI retorna prompt_cache_diagnostics.type como cache_hit, cache_miss, comparison_response_not_found ou unavailable. Em caso de cache_miss, o objeto traz reason e cache_missed_tokens (estimativa de tokens não reutilizados) e pode incluir comparison_reusable_tokens (contagem bruta de tokens do prefixo reutilizável da resposta de referência). O campo reason classifica a falha:
input_changed: a entrada anterior mudou, por exemplo ao inserir um timestamp ou ID de requisição em uma mensagemdeveloper, ou ao editar, reordenar ou remover turnos antigos.tools_changed: ferramentas foram adicionadas, removidas, reordenadas ou editadas.reasoning_effort_changedoutext_format_changed: o campo superiorreasoning.effortoutext.formatmudou em vez de usarconfiguration_update.model_changed,service_tier_changed,verbosity_changed,prompt_cache_key_changedoucontext_compacted: houve mudança de modelo, service tier, verbosidade, chave de cache ou compactação.
Leve em conta cinco limites do diagnóstico: ele exige GPT-5.6 ou posterior e um prefixo reutilizável de pelo menos 1,024 tokens; relata apenas a primeira causa classificada que consegue identificar e pode não encontrar nenhuma; não gera custo extra e funciona com Zero Data Retention; com stream=True, leia prompt_cache_diagnostics em event.response dentro do evento response.completed; e o diagnóstico não comprova se o modelo reutilizou o raciocínio.
Observe estes detalhes em APIs personalizadas e gateways
Equipes que roteiam o GPT-6.2 por uma URL base personalizada ou por um gateway com vários upstreams devem conferir quatro pontos:
- Chame
POST /v1/responses, não Chat Completions: GPT-6.2 Astra e Sol suportam Chat Completions para texto, mas chamadas de ferramentas,configuration_update,additional_toolseinput_transformationsexigem Responses. Para uma lista básica de migração, veja nosso guia de migração do GPT-6 Astra na Responses API. - Reenvie o array
inputappend-only completo em vez de depender apenas deprevious_response_id: o roteamento inteligente da BetterToken envia requisições para os canais upstream disponíveis no momento, e um modelo com vários upstreams configurados pode fazer failover em caso de erro aplicável ou timeout (nem todo modelo possui vários upstreams, nem todo erro aciona failover e o sucesso não é garantido). O replay sem estado evita depender de estado mantido em um único upstream. Na API da OpenAI, Zero Data Retention (ZDR) é uma configuração no nível da organização para organizações aprovadas em endpoints e recursos elegíveis, distinta de definirstorecomofalseem uma requisição. Em ambos os modos sem estado (store: falseou organização com ZDR ativo, onde a OpenAI tratastorecomofalse), os itens de raciocínio emoutputincluemencrypted_contentpor padrão. A OpenAI ainda aceita o valor legadoinclude: ["reasoning.encrypted_content"]por compatibilidade, mas não o exige. Reenvie todos os itens deoutputna ordem, mantenhasafety_identifieridêntico entre turnos (ou omita-o em todos) para evitarend_user_mismatche monitoreorganization_mismatcheminput_transformations. - Omita parâmetros de amostragem não suportados: nas chamadas Responses para
gpt-6.2-astraegpt-6.2-sol, omita os parâmetros de nível superiortemperature,top_petop_logprobs, e remova apenasmessage.output_text.logprobsdeinclude. - Restrinja janelas de conclusão em segundo plano às chamadas diretas à OpenAI: na Responses API da OpenAI, GPT-6.2 Astra e Sol não suportam
service_tier: "flex". Para tarefas longas enviadas diretamente à API da OpenAI, use as janelas de conclusão de 2 horas ou 8 horas do modo em segundo plano (beta público), detalhadas em nosso guia de completion_window na Responses API. Janelas de conclusão em segundo plano não estão verificadas na documentação pública da Responses API da BetterToken, portanto teste ou roteie diretamente para a OpenAI se sua carga de trabalho depender delas.