Chat Completions vs Responses API : comparaison

Deux endpoints, deux philosophies

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

Gestion de l’état : la différence fondamentale

Chat Completions : vous gérez l’historique

À chaque requête, vous devez renvoyer l’intégralité de la conversation :

# Chat Completions — tout renvoyer a chaque fois
response = client.chat.completions.create(
    model="grok-4.20-0309-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 prénom ?"}
    ]
)

API Responses : le serveur gère l’historique

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

# Responses API — juste l'ID de la réponse précédente
response1 = client.responses.create(
    model="grok-4.20-0309-reasoning",
    input="Bonjour, je m'appelle Alice."
)

response2 = client.responses.create(
    model="grok-4.20-0309-reasoning",
    input="Quel est mon prénom ?",
    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 réduisez la taille de vos requêtes.

Outils et fonctionnalités exclusives

L’API Responses donne accès à des outils serveur que Chat Completions ne propose pas :

• web_search : recherche sur le web en temps réel
• x_search : recherche dans les publications X (Twitter)
• code_interpreter : exécution de code Python côté serveur

Ces outils sont intégrés directement dans la requête :

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

Chat Completions supporte le function calling (outils définis par le développeur), mais pas ces outils serveur managés par xAI.

Quand utiliser Chat Completions ?

Chat Completions reste le bon choix dans plusieurs scénarios :

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

Quand utiliser l’API Responses ?

L’API Responses est préférable pour :

• Nouveaux projets : bénéficiez des dernières fonctionnalités dès le départ
• Outils serveur : besoin de recherche web, exécution de code ou recherche X
• Conversations longues : pas besoin de renvoyer l’historique à chaque requête
• Raisonnement chiffré : accès au contenu de raisonnement pour la continuité entre requêtes

Points clés à retenir

• Chat Completions est stateless (vous gérez l’historique), l’API Responses est stateful (le serveur gère)
• L’API Responses offre des outils serveur exclusifs : web_search, x_search, code_interpreter
• Chat Completions à une compatibilité OpenAI totale, l’API Responses est spécifique à xAI
• Les deux endpoints facturent l’historique complet de la conversation
• Utilisez Chat Completions pour la compatibilité, l’API Responses pour les nouvelles fonctionnalités