Chat Completions vs Responses API : comparaison

Deux endpoints, deux philosophies

xAI propose deux endpoints pour interagir avec les modeles Grok : Chat Completions (/v1/chat/completions) et l’API Responses (/v1/responses). Comprendre leurs differences est essentiel pour choisir le bon endpoint selon votre projet et planifier une eventuelle migration.

Gestion de l’etat : la difference fondamentale

Chat Completions : vous gerez l’historique

A chaque requete, vous devez renvoyer l’integralite de la conversation :

# Chat Completions — tout renvoyer a chaque fois
response = client.chat.completions.create(
    model="grok-4.20-reasoning",
    messages=[
        {"role": "system", "content": "Tu es un assistant utile."},
        {"role": "user", "content": "Bonjour, je m'appelle Alice."},
        {"role": "assistant", "content": "Bonjour Alice ! Comment puis-je vous aider ?"},
        {"role": "user", "content": "Quel est mon prenom ?"}
    ]
)

API Responses : le serveur gere l’historique

Avec l’API Responses, un simple identifiant suffit pour continuer une conversation :

# Responses API — juste l'ID de la reponse precedente
response1 = client.responses.create(
    model="grok-4.20-reasoning",
    input="Bonjour, je m'appelle Alice."
)

response2 = client.responses.create(
    model="grok-4.20-reasoning",
    input="Quel est mon prenom ?",
    previous_response_id=response1.id
)

Le serveur conserve le contexte et reconstruit l’historique automatiquement. Vous ne payez pas moins de tokens (l’historique est toujours facture), mais vous simplifiez votre code et reduisez la taille de vos requetes.

Outils et fonctionnalites exclusives

L’API Responses donne acces a des outils serveur que Chat Completions ne propose pas :

• web_search : recherche sur le web en temps reel
• x_search : recherche dans les publications X (Twitter)
• code_interpreter : execution de code Python cote serveur

Ces outils sont integres directement dans la requete :

response = client.responses.create(
    model="grok-4.20-reasoning",
    input="Quelles sont les dernieres nouvelles sur l'IA ?",
    tools=[{"type": "web_search"}]
)

Chat Completions supporte le function calling (outils definis par le developpeur), mais pas ces outils serveur manages par xAI.

Quand utiliser Chat Completions ?

Chat Completions reste le bon choix dans plusieurs scenarios :

• Migration depuis OpenAI : votre code existant fonctionne sans modification majeure
• Multi-fournisseurs : vous voulez pouvoir basculer entre OpenAI, Anthropic et xAI avec le meme code
• Frameworks tiers : LangChain, LlamaIndex, Haystack et la plupart des frameworks utilisent le format Chat Completions
• Controle total : vous voulez gerer vous-meme l’historique (resumage, filtrage, modification)

Quand utiliser l’API Responses ?

L’API Responses est preferable pour :

• Nouveaux projets : beneficiez des dernieres fonctionnalites des le depart
• Outils serveur : besoin de recherche web, execution de code ou recherche X
• Conversations longues : pas besoin de renvoyer l’historique a chaque requete
• Raisonnement chiffre : acces au contenu de raisonnement pour la continuite entre requetes

Points cles a retenir

• Chat Completions est stateless (vous gerez l’historique), l’API Responses est stateful (le serveur gere)
• L’API Responses offre des outils serveur exclusifs : web_search, x_search, code_interpreter
• Chat Completions a une compatibilite OpenAI totale, l’API Responses est specifique a xAI
• Les deux endpoints facturent l’historique complet de la conversation
• Utilisez Chat Completions pour la compatibilite, l’API Responses pour les nouvelles fonctionnalites