Champs de coût dans les réponses

Suivre les coûts en temps réel

Chaque réponse de l’API Grok transporte le détail de ce qu’elle vient de coûter. Beaucoup d’équipes découvrent cette information trop tard, au moment de la facture mensuelle, alors qu’elle est disponible requête par requête. En l’exploitant dès l’intégration, vous repérez une dérive dans l’heure qui suit son apparition : un prompt système qui a doublé de volume après un déploiement, une boucle de retry mal calibrée qui rejoue les mêmes appels, un contexte qui franchit un palier de facturation. Sans ce suivi, ces incidents restent invisibles jusqu’au relevé.

L’objet usage

Chaque réponse inclut un objet usage qui détaille la consommation de tokens et le coût associé :

{
  "usage": {
    "prompt_tokens": 1250,
    "completion_tokens": 340,
    "total_tokens": 1590,
    "cached_tokens": 800,
    "cost_in_usd_ticks": 5000000000,
    "cost_in_nano_usd": 500000000
  }
}

Les quatre champs de comptage se lisent de la façon suivante.

Une précision qui évite une erreur fréquente : cached_tokens est inclus dans prompt_tokens, il ne s’y ajoute pas. Dans l’exemple ci-dessus, 1 250 tokens sont entrés dans le modèle, dont 800 provenaient du cache et 450 seulement ont été facturés au tarif plein. Si votre agrégateur additionne les deux champs, il comptera deux fois la portion cachée et gonflera artificiellement vos statistiques de volume.

Deux échelles pour un même coût

Le coût de la requête est fourni dans deux unités entières. Ce choix n’est pas anodin : exprimer des fractions de centime en nombres à virgule flottante introduit des erreurs d’arrondi qui deviennent visibles quand on agrège des millions d’appels. Des entiers évitent complètement ce problème.

Le champ cost_in_usd_ticks compte en « ticks », avec 10 milliards de ticks pour un dollar. La valeur 5 000 000 000 de l’exemple correspond donc à $0.50, et un million de ticks vaut $0.0001. La conversion tient en une ligne :

cout_usd = cost_in_usd_ticks / 10_000_000_000

Le champ cost_in_nano_usd compte en nano-dollars, avec un milliard de nano-dollars pour un dollar. Les 500 000 000 de l’exemple représentent la même somme, $0.50, et mille nano-dollars valent $0.000001. La conversion suit la même logique :

cout_usd = cost_in_nano_usd / 1_000_000_000

Les deux champs décrivent le même montant à des échelles différentes. cost_in_nano_usd est plus intuitif à manipuler, cost_in_usd_ticks offre une précision légèrement supérieure. Choisissez-en un et tenez-vous-y dans toute votre chaîne de mesure : mélanger les deux dans un même agrégat est le meilleur moyen d’obtenir des totaux incohérents.

Construire un suivi de coûts

En production, il suffit d’un accumulateur pour transformer ces champs en tableau de bord. La classe ci-dessous enregistre chaque objet usage et expose le coût cumulé ainsi que le taux de cache :

class SuiviCouts:
    def __init__(self):
        self.total_nano_usd = 0
        self.requetes = 0
        self.tokens_entree = 0
        self.tokens_sortie = 0
        self.tokens_caches = 0

    def enregistrer(self, usage):
        self.total_nano_usd += usage.get("cost_in_nano_usd", 0)
        self.requetes += 1
        self.tokens_entree += usage.get("prompt_tokens", 0)
        self.tokens_sortie += usage.get("completion_tokens", 0)
        self.tokens_caches += usage.get("cached_tokens", 0)

    @property
    def cout_total_usd(self):
        return self.total_nano_usd / 1_000_000_000

    @property
    def taux_cache(self):
        if self.tokens_entree == 0:
            return 0
        return self.tokens_caches / self.tokens_entree

Branchez ensuite des seuils sur cout_total_usd. Un premier palier à 80 % du budget quotidien déclenche une alerte informative destinée à l’équipe technique ; un second à 95 % passe en alerte critique et exige une décision humaine ; à 100 %, l’application coupe automatiquement les requêtes non critiques — traitements par lots, pré-calculs, enrichissements différés — et ne laisse passer que le trafic utilisateur direct. Cette dégradation progressive vaut mieux qu’un arrêt brutal du service un jour de pic.

Analyser le taux de cache

La propriété taux_cache mérite un tableau de bord à part entière, car elle traduit directement la qualité de la structure de vos prompts.

Un taux qui chute brutalement d’une semaine à l’autre est presque toujours le signe d’un déploiement ayant introduit une variable en début de prompt. La leçon suivante détaille le mécanisme ; retenez pour l’instant que ce chiffre est un indicateur de régression aussi précieux qu’un taux d’erreur.

Tarifs relevés le 5 août 2026 — les prix évoluent régulièrement : avant tout calcul de budget, vérifiez la grille en vigueur sur la page officielle des modèles et tarifs xAI.

Points clés à retenir

• Chaque réponse API contient un objet usage avec le détail des tokens et le coût
• cost_in_usd_ticks : 10 milliards de ticks = $1 USD
• cost_in_nano_usd : 1 milliard de nano-USD = $1 USD
• Le champ cached_tokens permet de mesurer l’efficacité du cache
• Construisez un suivi de coûts en production avec des alertes budgétaires