Conventions de nommage

Comprendre les identifiants de modèles

Quand vous appelez l’API xAI, le champ model détermine quel modèle traite votre requête. xAI utilise un système de nommage structuré avec des alias et des versions figées. Comprendre ce système est essentiel pour gérer la stabilité et la migration de vos applications.

Les trois formats d’identifiant

xAI propose trois façons de référencer un modèle, chacune avec un comportement distinct :

Alias simple

{
  "model": "grok-4.20"
}

L’alias simple pointe vers la dernière version stable du modèle. Quand xAI publie une mise à jour mineure, l’alias est automatiquement redirigé vers la nouvelle version. Votre application utilise donc toujours la version la plus récente et stable, sans modification de votre code.

Avantage : vous bénéficiez automatiquement des améliorations. Risque : le comportement peut changer légèrement d’une version à l’autre.

Alias latest

{
  "model": "grok-4.20-latest"
}

L’alias latest pointe vers la version « bleeding edge » — la toute dernière itération, y compris les versions qui n’ont pas encore été promues en version stable. C’est la version la plus récente mais potentiellement la moins testée.

Avantage : accès immédiat aux dernières améliorations. Risque : comportement qui peut changer à tout moment, possibilité de régressions.

Version figée

{
  "model": "grok-4.20-0309"
}

La version figée identifie une version précise du modèle, indexée par sa date de publication (ici, le 9 mars). Cette version ne changera jamais : le comportement que vous observez aujourd’hui sera identique dans six mois.

Avantage : stabilité totale, résultats reproductibles. Risque : la version sera éventuellement dépréciée puis supprimée.

Les identifiants complets actuels

Le cycle de vie d’un modèle

Chaque modèle xAI suit un cycle de vie en trois phases :

1. Actif — le modèle est disponible et recommandé pour une utilisation en production
2. Déprécié — le modèle fonctionne encore, mais xAI recommande de migrer vers une version plus récente. Un délai est annoncé avant la suppression
3. Obsolète — le modèle est supprimé. Les requêtes vers ce modèle échouent

Surveillez les annonces de dépréciation sur la console xAI et dans les release notes. Quand un modèle est déprécié, planifiez votre migration sans attendre la date de suppression.

Recommandations par environnement

Développement

Utilisez les alias simples (grok-4.20, grok-4-1-fast-reasoning) pour bénéficier automatiquement des améliorations. En développement, un léger changement de comportement entre versions est acceptable et vous permet de repérer les incompatibilités avant la production.

Staging et tests

Utilisez les versions figées (grok-4.20-0309-reasoning) pour garantir la reproductibilité de vos tests. Si un test passe aujourd’hui, il doit passer demain avec exactement le même résultat.

Production

Utilisez les versions figées pour la stabilité. Planifiez des migrations périodiques vers les nouvelles versions après validation en staging.

Migration entre versions

Quand vous migrez d’une version à l’autre :

1. Mettez à jour le champ model dans vos requêtes
2. Testez vos prompts existants — les modèles plus récents peuvent répondre différemment
3. Vérifiez les paramètres API — une nouvelle version peut supporter ou déprécier certains paramètres
4. Validez les résultats — comparez qualitativement les sorties de l’ancienne et de la nouvelle version

Les endpoints API

xAI maintient deux endpoints principaux :

• /v1/responses — l’endpoint principal, recommandé pour tous les nouveaux projets
• /v1/chat/completions — l’endpoint legacy, maintenu pour la compatibilité avec les clients existants

L’endpoint legacy ne reçoit plus de nouvelles fonctionnalités. Si vous démarrez un nouveau projet, utilisez /v1/responses exclusivement.

Points clés à retenir

• Trois formats : alias simple (stable), alias latest (bleeding edge), version figée (immuable)
• En production, utilisez les versions figées pour la stabilité
• En développement, utilisez les alias pour bénéficier des améliorations
• Surveillez les annonces de dépréciation et planifiez vos migrations
• L’endpoint recommandé est /v1/responses, pas /v1/chat/completions
• Testez toujours vos prompts lors d’une migration de version