Responses API GPT-6.2 : conserver un préfixe intact pour ne pas perdre le raisonnement
À partir de GPT-6.2 Astra et Sol, modifier l'historique antérieur dans la Responses API supprime les éléments de raisonnement suivants. Conservez un préfixe intact avec des tours en ajout seul, configuration_update, additional_tools et des instructions placées dans un message developer initial, puis contrôlez input_transformations et Prompt Cache Diagnostics.
Sommaire

À partir de gpt-6.2-astra et gpt-6.2-sol, la Responses API d’OpenAI supprime les éléments de raisonnement dès qu’une modification touche le préfixe en cours de conversation, qu’un modèle est rétrogradé ou que l’organisation ou l’utilisateur final change. Cette règle concerne chaque développeur et chaque équipe d’agents dont le code réécrit d’anciens messages developer, raccourcit des résultats d’outils précédents ou modifie entre deux tours des paramètres de premier niveau comme reasoning.effort ou tools. Passez votre intégration à un historique input en ajout seul, utilisez configuration_update et additional_tools pour les changements en cours de fil, puis vérifiez input_transformations sur chaque réponse afin de confirmer qu’aucun raisonnement n’a disparu.
Choisir une route pour vos appels GPT-6.2 sur la Responses API
GPT-6.2 Astra et Sol prennent en charge Chat Completions pour le texte, mais l’appel d’outils exige la Responses API, et les mécanismes de préservation du préfixe (configuration_update, additional_tools et input_transformations) appartiennent exclusivement à la Responses API. Sélectionnez une route qui expose POST /v1/responses et correspond à vos conditions d’accès et de facturation.
| Route | Prérequis | Unité de facturation | Notes sur la Responses API | Quand la choisir |
|---|---|---|---|---|
| Passerelle API BetterToken | Compte BetterToken, API Key créée dans la console, solde à l’usage (le solde payé ne se réinitialise pas chaque mois) | Selon l’unité de facturation actuelle du modèle (les tokens d’entrée, de sortie et de cache peuvent avoir des tarifs et règles distincts) ; consultez les tarifs actuels | https://www.bettertoken.ai/v1 (POST /v1/responses) propose gpt-6.2-astra et gpt-6.2-sol ; vérifiez d’abord avec votre clé le renvoi d’historique en mode sans état (store: false), ainsi que la transmission de configuration_update et input_transformations | Vous souhaitez une seule API Key à l’usage pour les modèles disponibles ou vous ne pouvez pas utiliser la facturation directe OpenAI |
| API OpenAI directe | Compte OpenAI dans un pays ou territoire pris en charge et facturation API active | Par 1M tokens d’entrée, d’entrée en cache, d’écriture en cache et de sortie | Documente la prise en charge native de configuration_update, input_transformations, prompt_cache_diagnostics, previous_response_id, des fenêtres d’exécution en arrière-plan et du Zero Data Retention (ZDR) au niveau de l’organisation | Vous disposez d’un accès direct à OpenAI et vous dépendez de l’état hébergé par OpenAI, du ZDR ou de fonctionnalités bêta documentées |
Vérifier le renvoi d’historique en ajout seul et la détection d’une modification de préfixe via BetterToken
BetterToken propose une route API compatible OpenAI à l’adresse https://www.bettertoken.ai/v1 (POST /v1/responses), authentifiée avec votre API Key issue de la console BetterToken. Au 2026-11-21, gpt-6.2-sol et gpt-6.2-astra figurent tous deux sur l’endpoint Responses. BetterToken est une plateforme multimodèle et une couche d’accès API, et non un produit officiel d’OpenAI. Sa référence Responses API ne confirme pas la prise en charge du renvoi de l’historique et des éléments de raisonnement chiffrés en mode sans état (store: false), ni la transmission de configuration_update, input_transformations ou prompt_cache_diagnostics. Exécutez donc ce test en deux tours en mode sans état avec votre clé avant toute mise en production.
Exportez votre clé BetterToken dans Bash sans l’afficher :
read -rs BETTERTOKEN_API_KEY && export BETTERTOKEN_API_KEY
Envoyez le tour 1 avec store: false et vérifiez qu’il renvoie au moins un élément reasoning doté de encrypted_content. Comparez ensuite deux appels en mode sans état qui renvoient l’historique et les éléments de raisonnement chiffrés : le premier ajoute simplement un nouveau tour, tandis que le second modifie aussi le message developer antérieur pour servir de témoin :
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)
Analysez quatre signaux avant de déployer :
status == "completed"confirme uniquement l’acceptation et la fin de la requête. Ce statut ne prouve pas que la passerelle a conservé le raisonnement d’un tour à l’autre.- Vérifiez que le tour 1 avec
store: falserenvoie une listereasoning_idsnon vide et que chaque élément de raisonnement contientencrypted_content. Si la passerelle ometencrypted_content, considérez le renvoi d’historique en mode sans état comme non vérifié, car le tour 2 ne peut pas transmettre les tokens de raisonnement chiffrés entre différents canaux amont. - Comparez
input_transformationssur les deux appels du tour 2. Une transmission vérifiée signale une entréeprefix_mismatchcorrespondant à un identifiant dereasoning_idssuredited_control, et aucune surappend_only. Siinput_transformationsvautNoneou reste vide dans les deux cas, considérez le test comme non concluant : la passerelle ne relaie peut-être pas ce champ. - Testez la transmission de
configuration_updateséparément du contrôle de préfixe. Vous pouvez vérifier une mise à jour detext.formaten envoyant un appel de tour 2 distinct qui basculetext.formatvers un schéma JSON strict, puis en contrôlant la conformité de la sortie. En revanche, OpenAI ne documente aucun champ de réponse confirmant un changement dereasoning.efforten cours de conversation (le champreasoning.effortde la réponse continue d’indiquer la valeur de premier niveau) ; considérez doncconfiguration_updatepourreasoning.effortcomme non vérifié via BetterToken.
Pour la mise en cache des prompts, OpenAI impose un préfixe minimal de 1,024 tokens d’entrée visibles sur GPT-5.6 et les modèles ultérieurs comme condition d’éligibilité. Observez append_only.usage.input_tokens_details.cached_tokens pour mesurer la réutilisation réelle dès que votre préfixe réutilisable atteint ce seuil. Consultez les tarifs actuels pour vérifier les prix des modèles et les règles de cache avant de monter en charge.
Si vous appelez OpenAI directement, omettez base_url, utilisez OPENAI_API_KEY et suivez le guide officiel Keep the prefix unchanged.
Ce qui compte comme une modification de préfixe dans GPT-6.2
Le préfixe d’un élément de raisonnement correspond à tout l’historique de conversation placé avant lui. Sur GPT-6.2, modifier cet historique antérieur entraîne la suppression par l’API des éléments de raisonnement situés après la modification.
OpenAI distingue deux catégories de modifications du préfixe :
- Modifier des éléments
inputantérieurs : raccourcir le résultat d’un outil, réécrire un messagedeveloper, réduire des images ou fichiers déjà envoyés, ou remplacer d’anciens tours par un résumé. - Altérer des paramètres de premier niveau entre deux tours : modifier
tools(ajout, suppression, réorganisation ou édition des schémas et descriptions), changertext.format, modifierreasoning.effortau niveau racine ou changerinstructionssur les modèles antérieurs à GPT-6.2.
D’après le guide Reasoning d’OpenAI, prefix_mismatch se déclenche sur GPT-6.2 et les versions suivantes lorsque vous insérez ou éditez du contenu avant un élément de raisonnement. Supprimer des éléments entiers sans modifier ceux qui restent, ou ajouter de nouveaux éléments après un élément de raisonnement, ne déclenche pas prefix_mismatch en soi. Toutefois, retirer d’anciens tours peut quand même réduire la réutilisation du cache de prompts, et Prompt Cache Diagnostics peut signaler input_changed lorsque ce retrait empêche la réutilisation.
Les modifications de préfixe représentent l’une des cinq raisons de suppression indiquées dans input_transformations :
Raison (reason) | Cas où l’API retire l’élément de raisonnement |
|---|---|
prefix_mismatch | Sur GPT-6.2 et versions ultérieures, du contenu a été inséré ou modifié avant l’élément de raisonnement |
end_user_mismatch | Sur GPT-6.2 et versions ultérieures, safety_identifier diffère entre la requête de création et celle de réutilisation, y compris lorsqu’il manque sur l’une des deux |
model_mismatch | Vous avez changé de famille de modèles ou rétrogradé au sein de la même famille (monter en gamme dans la même famille conserve le raisonnement compatible si les autres vérifications réussissent) |
organization_mismatch | Vous avez réutilisé un élément provenant d’une autre organisation ou d’un autre espace de travail rattaché à un autre utilisateur |
turn_boundary | L’élément provient d’un tour antérieur alors que le modèle n’utilise que le raisonnement du tour courant (reasoning.context contrôle cette éligibilité sur les modèles pris en charge) |
Que se passe-t-il lorsque les éléments de raisonnement sont supprimés
Une requête sur la Responses API peut aboutir normalement même si l’API retire des éléments de raisonnement : la perte reste silencieuse tant que vous n’inspectez pas input_transformations dans la réponse. Modifier le préfixe en cours de conversation entraîne deux pénalités distinctes en production :
- Impact du raisonnement supprimé : lorsque des éléments de raisonnement disparaissent, le modèle peut devoir refaire une partie du raisonnement antérieur, ce qui peut accroître la consommation de tokens, le coût et la latence. Si le modèle ne parvient pas à reconstituer le raisonnement perdu, la qualité de la réponse peut également baisser.
- Impact sur le préfixe mis en cache : comme le cache de prompts compare les requêtes depuis le début, modifier le préfixe peut interrompre la réutilisation du cache à partir de la modification, ce qui peut renchérir les entrées et ralentir les réponses.
Les tarifs Standard publiés par OpenAI au 2026-11-21 (jusqu’à 272,000 tokens d’entrée) montrent à quelle vitesse les défauts de cache pèsent sur la facture :
- GPT-6.2 Astra (
gpt-6.2-astra) : $0.40/1M en entrée en cache contre $8/1M en entrée non mise en cache ($10/1M pour les écritures en cache de 30 minutes, $20/1M pour les écritures de 12 heures) et $40/1M en sortie. - GPT-6.2 Sol (
gpt-6.2-sol) : $0.10/1M en entrée en cache contre $2/1M en entrée non mise en cache ($2.50/1M pour les écritures en cache de 30 minutes, $5/1M pour les écritures de 12 heures) et $10/1M en sortie.
Au-delà de 272,000 tokens d’entrée, OpenAI double les tarifs d’entrée et de cache, et facture la sortie à 1.5x le tarif contexte court pour l’ensemble de la requête. Pour évaluer quand la rétention de 12 heures devient rentable sur des préfixes stables, consultez notre guide sur le prompt caching 12 heures d’OpenAI.
Mettre à jour les paramètres et le contexte sans casser le préfixe
Remplacez les modifications en place par des éléments ajoutés en fin de contexte afin que le raisonnement et les préfixes en cache survivent d’un tour à l’autre.
Modifier reasoning.effort et text.format avec configuration_update
Changer reasoning.effort au premier niveau peut réécrire des instructions système cachées. Sur les modèles GPT-6 et ultérieurs pris en charge en mode mono-agent standard, laissez reasoning.effort et text.format inchangés au niveau de la requête et ajoutez un élément configuration_update dans input juste avant le message utilisateur suivant :
{
"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
}
}
}
}
Respectez cinq règles lorsque vous utilisez configuration_update :
- Un élément
configuration_updatereste actif sur les tours suivants jusqu’à ce qu’une nouvelle mise à jour le remplace. Modifier uniquementreasoning.effortconserve une mise à jour antérieure detext.format, et inversement. - Le champ
reasoning.effortde l’objet de réponse continue d’indiquer la valeur racine de la requête, et non le nouvel effort appliqué. - Conservez les mises à jour grâce à
previous_response_id, ou renvoyez chaqueconfiguration_updateà sa position d’origine si vous gérezinputmanuellement. - La troncature automatique et l’endpoint autonome
/responses/compactrejettent les historiques contenant des élémentsconfiguration_update. Utilisezcontext_managementoucompaction_triggerà la place (voir la section sur la compaction ci-dessous). gpt-6.2-astraetgpt-6.2-solrejettent tous deuxreasoning.effort: "none". Le guide Using GPT-6.2 d’OpenAI recommande de démarrer avecmedium, ou d’utiliserlowà la place denoneouminimal.
Ajouter ou restreindre des outils sans muter tools
Gardez le tableau tools, ses schémas et son ordre identiques au premier niveau entre les tours. Adaptez les outils appelables avec trois méthodes qui préservent le préfixe :
- Définissez
tool_choicesur"none"pour désactiver les outils pendant un tour sans retirertools. - Utilisez
tool_choiceavecallowed_toolspour limiter les outils appelables sur un tour donné :
{
"tool_choice": {
"type": "allowed_tools",
"mode": "auto",
"tools": [
{ "type": "function", "name": "get_weather" },
{ "type": "function", "name": "search_docs" }
]
}
}
- Ajoutez un élément
additional_toolsavec le rôledeveloperpour introduire de nouveaux outils en cours de conversation, ou activez tool search avecdefer_loading: trueafin que les outils découverts s’ajoutent en fin de contexte. Les outils déclarés dansadditional_toolsne deviennent appelables qu’après l’apparition de cet élément : renvoyez-le donc à sa position initiale :
{
"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
}
}
]
}
Séparer les messages developer réutilisables du champ racine instructions
À partir de GPT-6.2, OpenAI ajoute le champ de premier niveau instructions après input, au-delà des points de coupure éligibles au cache. OpenAI facture ces tokens au tarif d’entrée non mis en cache à chaque requête, même s’ils ne changent pas, et previous_response_id ne reporte pas ce champ instructions.
Répartissez vos consignes selon leur portée :
- Placez les prompts système réutilisables et les règles partagées dans un message
developeren toute première position deinputafin que le cache de prompts puisse les faire correspondre. - Ajoutez un nouveau message
developerà la fin deinputlorsque vous mettez à jour des règles réutilisables en cours de fil, au lieu d’éditer le premier message. - Réservez le champ racine
instructionsaux directives propres à la requête courante.
Gérer la compaction et les sorties d’outils volumineuses
Raccourcissez les sorties d’outils trop longues et réduisez la taille des images ou fichiers avant de les envoyer au modèle pour la première fois. Ne tronquez jamais d’anciens éléments rétroactivement.
La compaction modifie le préfixe, ce qui rend les défauts de cache difficiles à éviter. Pour les sessions longues, le guide Compaction d’OpenAI décrit deux approches :
- Compaction automatique (
context_managementaveccompact_threshold) : OpenAI conserve les éléments de raisonnement suivants malgré la modification du préfixe. Si des tours précédents contiennent des élémentsconfiguration_update, l’API émet un nouvel élémentconfiguration_updatejuste après l’élémentcompactionet stocke les déclarationsadditional_toolsdans l’élément de compaction chiffré. Renvoyez les éléments retournés dans leur ordre exact. - Compaction explicite ou personnalisée : l’endpoint autonome
/responses/compactrejette les historiques contenantconfiguration_update. Lorsque vous appelez/responses/compact, omettezinstructionset transmettez la fenêtre renvoyée dans son ordre d’origine. Si votre historique utiliseconfiguration_update, incluez plutôt un élémentcompaction_triggerdans/responses, puis ajoutez un nouvel élémentconfiguration_updaterappelant chaque champ modifié avant le message utilisateur suivant. En cas de compaction maison, placez le résumé compacté en fin de contexte au lieu de remplacer les anciens tours en place, ou acceptez la suppression des éléments de raisonnement suivants.
Vérifier la préservation du préfixe avec input_transformations et Prompt Cache Diagnostics
Combinez deux contrôles sur la réponse : le premier signale les éléments de raisonnement écartés, et le second identifie ce qui a rompu la réutilisation du cache de prompts.
1. Inspecter input_transformations sur chaque réponse
Selon la référence create de la Responses API, input_transformations est un tableau optionnel d’objets {id, action, reason, type} qui liste, dans l’ordre d’entrée, les éléments de raisonnement retirés (action vaut "removed" et type vaut "reasoning"). Lorsque reason vaut "prefix_mismatch", rapprochez id d’un élément de raisonnement présent dans l’output d’une réponse antérieure pour repérer la modification qui le précède.
2. Lancer Prompt Cache Diagnostics avec comparison_response_id
Pour expliquer un compteur usage.input_tokens_details.cached_tokens inférieur aux attentes, sélectionnez une réponse récente et terminée de la même organisation, passez son id dans prompt_cache_options.comparison_response_id, puis inspectez prompt_cache_diagnostics :
{
"prompt_cache_diagnostics": {
"type": "cache_miss",
"reason": "tools_changed",
"comparison_reusable_tokens": 5629,
"cache_missed_tokens": 5629
}
}
D’après le guide Prompt cache diagnostics d’OpenAI, prompt_cache_diagnostics.type renvoie cache_hit, cache_miss, comparison_response_not_found ou unavailable. En cas de cache_miss, l’objet contient reason et cache_missed_tokens (estimation des tokens non réutilisés), et peut inclure comparison_reusable_tokens (nombre brut de tokens du préfixe réutilisable de référence). Les défauts de cache se classent selon reason :
input_changed: une entrée antérieure a changé, par exemple après l’ajout d’un horodatage ou d’un identifiant de requête dans un messagedeveloper, ou après l’édition, la réorganisation ou la suppression d’anciens tours.tools_changed: des outils ont été ajoutés, retirés, réordonnés ou modifiés.reasoning_effort_changedoutext_format_changed:reasoning.effortoutext.formata changé au premier niveau au lieu de passer parconfiguration_update.model_changed,service_tier_changed,verbosity_changed,prompt_cache_key_changedoucontext_compacted: le modèle, le palier de service, la verbosité, la clé de cache ou la compaction a changé.
Gardez cinq limites de diagnostic en tête : l’outil exige GPT-5.6 ou une version ultérieure et un préfixe réutilisable d’au moins 1,024 tokens ; il signale uniquement la première différence qu’il parvient à identifier, et ce résultat peut être incomplet ; il n’entraîne aucun surcoût et fonctionne avec Zero Data Retention ; avec stream=True, lisez prompt_cache_diagnostics dans event.response lors de l’événement response.completed ; enfin, ce diagnostic ne peut pas confirmer si le modèle a réellement réutilisé le raisonnement.
Points à vérifier dans une configuration d’API personnalisée ou de passerelle
Les équipes qui routent GPT-6.2 via une URL de base personnalisée ou une passerelle multi-amont doivent contrôler quatre points :
- Appeler
POST /v1/responseset non Chat Completions : GPT-6.2 Astra et Sol acceptent Chat Completions pour le texte, mais l’appel d’outils,configuration_update,additional_toolsetinput_transformationsexigent la Responses API. Pour la liste de migration de base, consultez notre guide de migration vers la Responses API GPT-6 Astra. - Renvoyer des tableaux
inputcomplets en ajout seul au lieu de s’appuyer uniquement surprevious_response_id: le routage intelligent de BetterToken dirige les requêtes vers les canaux amont disponibles, et un modèle doté de plusieurs canaux configurés peut basculer en cas d’erreur applicable ou de délai dépassé (tous les modèles ne disposent pas de plusieurs canaux amont, toutes les erreurs ne déclenchent pas de basculement et le succès n’est pas garanti). Le renvoi complet de l’historique en mode sans état évite toute dépendance à un état serveur lié à un seul canal amont. Sur l’API OpenAI, Zero Data Retention (ZDR) est un réglage au niveau de l’organisation réservé aux organisations approuvées sur les endpoints et fonctionnalités éligibles, distinct du paramètrestoredéfini surfalsedans une requête. Dans les deux modes sans état (store: falseou organisation avec ZDR activé, où OpenAI traitestorecommefalse), les éléments de raisonnement dansoutputincluentencrypted_contentpar défaut. OpenAI accepte encore l’option héritéeinclude: ["reasoning.encrypted_content"]par compatibilité, sans l’exiger. Renvoyez tous les élémentsoutputdans l’ordre, gardez unsafety_identifieridentique à chaque tour (ou omettez-le systématiquement) pour éviterend_user_mismatch, et surveillezorganization_mismatchdansinput_transformations. - Omettre les paramètres d’échantillonnage non pris en charge : pour les appels Responses vers
gpt-6.2-astraetgpt-6.2-sol, supprimez les paramètres de premier niveautemperature,top_pettop_logprobs, et retirez uniquementmessage.output_text.logprobsdeinclude. - Réserver les fenêtres d’exécution en arrière-plan aux appels directs vers OpenAI : sur la Responses API d’OpenAI, GPT-6.2 Astra et Sol ne prennent pas en charge
service_tier: "flex". Pour les tâches longues exécutées directement sur l’API OpenAI, utilisez les fenêtres d’exécution de 2 heures ou 8 heures du mode arrière-plan (bêta publique), détaillées dans notre guide sur completion_window dans la Responses API. Les fenêtres d’exécution en arrière-plan ne sont pas vérifiées dans la documentation publique Responses API de BetterToken : testez-les ou routez directement vers OpenAI si votre charge de travail en dépend.