Migration progressive vers l'API Responses — Chat Completions : compatibilité OpenAI

Corrigé le 3 novembre 2026 : la correspondance des paramètres indiquait que max_tokens garde son nom dans l’API Responses ; le tableau de xAI le fait devenir max_output_tokens, et les compteurs d’usage changent aussi de nom. Source : Comparison with Chat Completions.

Pourquoi et quand migrer

L’endpoint Chat Completions est marque legacy. Il continuera de fonctionner, mais les nouvelles fonctionnalités ne lui seront pas ajoutées. Si votre application a besoin d’outils 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 de manière progressive. Vous n’avez pas besoin de tout réécrire d’un coup.

Étape 1 : Identifier les fonctionnalités utilisées

Avant de migrer, faites l’inventaire de ce que votre application utilise avec Chat Completions :

# Audit de votre code existant
# Cherchez ces patterns :

# 1. Appels basiques (texte simple)
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 avec content en tableau [text, image_url]

# 5. Paramètres de generation
# temperature, max_tokens, top_p, stop, seed

Les appels basiques et le streaming sont les plus simples à migrer. Le function calling nécessite une adaptation du format. La vision fonctionne de manière similaire.

Étape 2 : Migrer les appels basiques

La migration d’un appel simple suit ce schéma :

# AVANT — Chat Completions
response = client.chat.completions.create(
    model="grok-4.20-0309-reasoning",
    messages=[
        {"role": "system", "content": "Tu es un assistant utile."},
        {"role": "user", "content": "Bonjour !"}
    ]
)
texte = response.choices[0].message.content

# APRES — API Responses
response = client.responses.create(
    model="grok-4.20-0309-reasoning",
    instructions="Tu es un assistant utile.",
    input="Bonjour !"
)
texte = response.output_text

Correspondance des champs

Les principaux changements sont :

messages avec rôle system → instructions (paramètre dédié)
messages avec rôle user → input (string simple)
response.choices[0].message.content → response.output_text
max_tokens → max_output_tokens, d’après le tableau de correspondance de xAI ; temperature garde son nom
response.usage.prompt_tokens et completion_tokens → input_tokens et output_tokens (détails : input_tokens_details.cached_tokens, output_tokens_details.reasoning_tokens)

Étape 3 : Migrer les conversations multi-tour

C’est ici que l’API Responses simplifie les choses. Au lieu de reconstituer l’historique à chaque requête, vous chaineriez par identifiant :

# AVANT — Chat Completions (gerer l'historique soi-meme)
historique = [
    {"role": "system", "content": "Tu es un assistant utile."}
]

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

# APRES — API Responses (le serveur gère l'historique)
dernier_id = None

def envoyer_message(texte: str) -> str:
    response = client.responses.create(
        model="grok-4.20-0309-reasoning",
        instructions="Tu es un assistant utile.",
        input=texte,
        previous_response_id=dernier_id
    )
    dernier_id = response.id
    return response.output_text

Le code est plus simple et vous n’avez plus à gérer le tableau de messages manuellement.

Étape 4 : Profiter des nouvelles fonctionnalités

Une fois migre, vous pouvez exploiter les fonctionnalités exclusives de l’API Responses :

Recherche web intégrée

response = client.responses.create(
    model="grok-4.20-0309-reasoning",
    input="Quels sont les derniers développements en IA generative ?",
    tools=[{"type": "web_search"}]
)
# La reponse inclut des citations avec URLs sources

Stockage des réponses

response = client.responses.create(
    model="grok-4.20-0309-reasoning",
    input="Analyse ce document...",
    store=True  # Conserve pendant 30 jours
)

# Recuperer plus tard
stored = client.responses.retrieve(response.id)

Raisonnement chiffré

response = client.responses.create(
    model="grok-4.20-0309-reasoning",
    input="Résous ce problème complexe...",
    include=["reasoning.encrypted_content"]
)
# Le raisonnement chiffre peut etre reutilise dans les requetes suivantes

Stratégie de migration recommandée

Plutôt que de tout migrer d’un coup, procédez par étapes :

Identifiez les appels Chat Completions dans votre code
Classez-les par complexité (basique → streaming → function calling)
Migrez d’abord les nouveaux endpoints ou fonctionnalités (greenfield)
Migrez ensuite les appels existants les plus simples
Gardez Chat Completions pour les intégrations tierces qui le nécessitent (LangChain, etc.)

Coexistence temporaire

Il est parfaitement acceptable de faire cohabiter les deux endpoints pendant la transition :

# Wrapper qui abstrait l'endpoint utilise
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 vous permet de basculer progressivement en testant chaque migration individuellement.

Points clés à retenir

La migration peut être progressive : pas besoin de tout réécrire d’un coup
Les principaux changements : messages → input/instructions, choices[0].message.content → output_text
Les conversations multi-tour 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é)
Faites coexister les deux endpoints pendant la transition et migrez par ordre de complexité

Testez vos connaissances

L’API legacy comprise — et la migration préparée.

1. Que signifie le statut legacy et stateless de Chat Completions ?

Réponse : L’endpoint reste supporté mais n’évolue plus : sans état, il exige de renvoyer tout l’historique à chaque appel — la Responses API est la voie moderne.

2. Quels rôles structurent les messages ?

Réponse : system (et developer), user, assistant — le cadre, les demandes, les réponses : l’historique complet repart à chaque requête.

3. Comment utiliser un 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 fait le reste, SDK OpenAI et Vercel AI SDK compris.

4. Que lit-on dans la réponse et l'usage ?

Réponse : choices porte les réponses avec finish_reason ; usage détaille les tokens, y compris les reasoning_tokens des modèles à raisonnement — la matière du suivi des coûts.

5. Comment migrer proprement vers la Responses API ?

Réponse : Progressivement : nouveaux développements en Responses, endpoints existants convertis un à un avec re-test des prompts — la comparaison des deux formats guide la conversion.

Comprendre l’héritage, construire en moderne : la migration progressive du cours est votre plan — sans big bang.