Migration progressive vers l'API Responses

Pourquoi et quand migrer

L’endpoint Chat Completions est marque legacy. Il continuera de fonctionner, mais les nouvelles fonctionnalites ne lui seront pas ajoutees. Si votre application a besoin d’outils serveur (recherche web, execution de code), de stockage de conversations ou de raisonnement chiffre, la migration vers l’API Responses devient necessaire.

La bonne nouvelle : cette migration peut se faire de maniere progressive. Vous n’avez pas besoin de tout réécrire d’un coup.

Etape 1 : Identifier les fonctionnalites utilisees

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. Parametres de generation
# temperature, max_tokens, top_p, stop, seed

Les appels basiques et le streaming sont les plus simples a migrer. Le function calling necessite une adaptation du format. La vision fonctionne de maniere similaire.

Etape 2 : Migrer les appels basiques

La migration d’un appel simple suit ce schema :

# AVANT — Chat Completions
response = client.chat.completions.create(
    model="grok-4.20-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-reasoning",
    instructions="Tu es un assistant utile.",
    input="Bonjour !"
)
texte = response.output_text

Correspondance des champs

Les principaux changements sont :

• messages avec role system → instructions (parametre dedie)
• messages avec role user → input (string simple)
• response.choices[0].message.content → response.output_text
• temperature, max_tokens → memes noms, meme fonctionnement

Etape 3 : Migrer les conversations multi-tour

C’est ici que l’API Responses simplifie les choses. Au lieu de reconstituer l’historique a chaque requete, 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-reasoning",
        messages=historique
    )
    reponse = response.choices[0].message.content
    historique.append({"role": "assistant", "content": reponse})
    return reponse

# APRES — API Responses (le serveur gere l'historique)
dernier_id = None

def envoyer_message(texte: str) -> str:
    response = client.responses.create(
        model="grok-4.20-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 a gerer le tableau de messages manuellement.

Etape 4 : Profiter des nouvelles fonctionnalites

Une fois migre, vous pouvez exploiter les fonctionnalites exclusives de l’API Responses :

Recherche web integree

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

Stockage des reponses

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

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

Raisonnement chiffre

response = client.responses.create(
    model="grok-4.20-reasoning",
    input="Resous ce probleme complexe...",
    include=["reasoning.encrypted_content"]
)
# Le raisonnement chiffre peut etre reutilise dans les requetes suivantes

Strategie de migration recommandee

Plutot que de tout migrer d’un coup, procedez par etapes :

1. Identifiez les appels Chat Completions dans votre code
2. Classez-les par complexite (basique → streaming → function calling)
3. Migrez d’abord les nouveaux endpoints ou fonctionnalites (greenfield)
4. Migrez ensuite les appels existants les plus simples
5. Gardez Chat Completions pour les integrations tierces qui le necessitent (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-reasoning",
                instructions=system,
                input=user_message
            )
            return response.output_text
        else:
            response = self.client.chat.completions.create(
                model="grok-4.20-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 cles a retenir

• La migration peut etre 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 a un simple previous_response_id
• L’API Responses donne acces a des fonctionnalites exclusives (web_search, stockage, raisonnement chiffre)
• Faites coexister les deux endpoints pendant la transition et migrez par ordre de complexite