Migration graduelle vers l'API Responses
På denna sida
Mis à jour le 3 novembre 2026 : Le mappage des paramètres indiquait précédemment que
max_tokensconservait son nom dans l’API Responses ; le tableau de xAI le change enmax_output_tokens, et les compteurs d’utilisation changent également de nom. Source : Comparaison avec Chat Completions.
Pourquoi et quand migrer
Le point de terminaison Chat Completions est marqué comme hérité. Il continuera de fonctionner, mais aucune nouvelle fonctionnalité ne lui sera ajoutée. Si ton application a besoin d’outils côté serveur (recherche web, exécution de code), de stockage de conversations ou de raisonnement chiffré, la migration vers l’API Responses devient nécessaire.
La bonne nouvelle : cette migration peut se faire progressivement. Tu n’as pas besoin de tout réécrire d’un coup.
Étape 1 : Identifier les fonctionnalités que tu utilises
Avant de migrer, fais l’inventaire de ce que ton application utilise avec Chat Completions :
# Audit your existing code
# Look for these patterns:
# 1. Basic calls (simple text)
client.chat.completions.create(model=..., messages=...)
# 2. Streaming
client.chat.completions.create(..., stream=True)
# 3. Function calling
client.chat.completions.create(..., tools=[...])
# 4. Vision (images)
# messages with content as array [text, image_url]
# 5. Generation parameters
# temperature, max_tokens, top_p, stop, seed
Les appels basiques et le streaming sont les plus simples à migrer. L’appel de fonctions nécessite d’adapter le format. La vision fonctionne de manière similaire.
Étape 2 : Migrer les appels basiques
La migration d’un appel simple suit ce schéma :
# BEFORE — Chat Completions
response = client.chat.completions.create(
model="grok-4.20-0309-reasoning",
messages=[
{"role": "system", "content": "You are a helpful assistant."},
{"role": "user", "content": "Hello!"}
]
)
texte = response.choices[0].message.content
# AFTER — Responses API
response = client.responses.create(
model="grok-4.20-0309-reasoning",
instructions="You are a helpful assistant.",
input="Hello!"
)
texte = response.output_text
Mappage des champs
Les principaux changements sont :
messagesavec le rôlesystem→instructions(paramètre dédié)messagesavec le rôleuser→input(chaîne simple)response.choices[0].message.content→response.output_textmax_tokens→max_output_tokens, selon le tableau de mappage de xAI ;temperatureconserve son nomresponse.usage.prompt_tokensetcompletion_tokens→input_tokensetoutput_tokens(détails :input_tokens_details.cached_tokens,output_tokens_details.reasoning_tokens)
Étape 3 : Migrer les conversations multi-tours
C’est ici que l’API Responses simplifie les choses. Au lieu de reconstruire l’historique à chaque requête, tu les enchaînes par ID :
# BEFORE — Chat Completions (manage history yourself)
historique = [
{"role": "system", "content": "You are a helpful assistant."}
]
def envoyer_message(texte: str) -> str:
historique.append({"role": "user", "content": texte})
response = client.chat.completions.create(
model="grok-4.20-0309-reasoning",
messages=historique
)
reponse = response.choices[0].message.content
historique.append({"role": "assistant", "content": reponse})
return reponse
# AFTER — Responses API (server manages history)
dernier_id = None
def envoyer_message(texte: str) -> str:
response = client.responses.create(
model="grok-4.20-0309-reasoning",
instructions="You are a helpful assistant.",
input=texte,
previous_response_id=dernier_id
)
dernier_id = response.id
return response.output_text
Le code est plus simple et tu n’as plus à gérer manuellement le tableau de messages.
Étape 4 : Profiter des nouvelles fonctionnalités
Une fois migré, tu peux exploiter les fonctionnalités exclusives à l’API Responses :
Recherche web intégrée
response = client.responses.create(
model="grok-4.20-0309-reasoning",
input="What are the latest developments in generative AI?",
tools=[{"type": "web_search"}]
)
# The response includes citations with source URLs
Stockage des réponses
response = client.responses.create(
model="grok-4.20-0309-reasoning",
input="Analyze this document...",
store=True # Keeps for 30 days
)
# Retrieve later
stored = client.responses.retrieve(response.id)
Raisonnement chiffré
response = client.responses.create(
model="grok-4.20-0309-reasoning",
input="Solve this complex problem...",
include=["reasoning.encrypted_content"]
)
# The encrypted reasoning can be reused in subsequent requests
Stratégie de migration recommandée
Plutôt que de tout migrer d’un coup, procède par étapes :
- Identifie les appels Chat Completions dans ton code
- Classe-les par complexité (basique → streaming → appel de fonctions)
- Migre en premier les nouveaux points de terminaison ou fonctionnalités (greenfield)
- Migre ensuite les appels existants les plus simples
- Conserve Chat Completions pour les intégrations tierces qui l’exigent (LangChain, etc.)
Coexistence temporaire
Il est tout à fait acceptable d’exécuter les deux points de terminaison côte à côte pendant la transition :
# Wrapper that abstracts the endpoint used
class GrokClient:
def __init__(self, use_responses: bool = False):
self.use_responses = use_responses
self.client = OpenAI(
api_key=os.getenv("XAI_API_KEY"),
base_url="https://api.x.ai/v1"
)
def generate(self, system: str, user_message: str) -> str:
if self.use_responses:
response = self.client.responses.create(
model="grok-4.20-0309-reasoning",
instructions=system,
input=user_message
)
return response.output_text
else:
response = self.client.chat.completions.create(
model="grok-4.20-0309-reasoning",
messages=[
{"role": "system", "content": system},
{"role": "user", "content": user_message}
]
)
return response.choices[0].message.content
Cette approche te permet de basculer progressivement en testant chaque migration individuellement.
Viktiga punkter
- La migration peut être graduelle : pas besoin de tout réécrire d’un coup
- Changements principaux :
messages→input/instructions,choices[0].message.content→output_text - Les conversations multi-tours passent d’un tableau de messages à un simple
previous_response_id - L’API Responses donne accès à des fonctionnalités exclusives (web_search, stockage, raisonnement chiffré)
- Exécute les deux points de terminaison côte à côte pendant la transition et migre par ordre de complexité
Teste tes connaissances
L’API héritée est comprise et la migration préparée.
1. Que signifie le statut hérité et sans état de Chat Completions ?
Réponse : Le point de terminaison reste pris en charge mais n’évolue plus : sans état, il exige de renvoyer l’intégralité de l’historique à chaque appel — l’API Responses est la voie moderne.
2. Quels rôles structurent les messages ?
Réponse : system (et developer), user, assistant — le cadre, les requêtes, les réponses : l’historique complet redémarre à chaque requête.
3. Comment utiliser du code OpenAI existant avec Grok ?
Réponse : En changeant base_url vers https://api.x.ai/v1 et la clé API — la compatibilité de format gère le reste, y compris le SDK OpenAI et le Vercel AI SDK.
4. Que lis-tu dans la réponse et l'utilisation ?
Réponse : choices porte les réponses avec finish_reason ; usage détaille les tokens, y compris reasoning_tokens pour les modèles de raisonnement — la base pour le suivi des coûts.
5. Comment migrer proprement vers l'API Responses ?
Réponse : Progressivement : nouveaux développements dans Responses, points de terminaison existants convertis un par un avec re-test des prompts — comparer les deux formats guide la conversion.
Comprends l’héritage, construis pour le moderne : le plan de migration graduelle du cours est ta feuille de route — sans big bang.