Usage des tokens et reasoning_tokens

Comprendre la facturation par tokens

Chaque requête à l’API Chat Completions est facturée en fonction du nombre de tokens consommés. L’objet usage dans la réponse vous donne un décompte précis qui est essentiel pour surveiller vos coûts, optimiser vos prompts et dimensionner vos budgets API.

L’objet usage standard

Voici la structure de l’objet usage retourné avec chaque réponse :

{
  "usage": {
    "prompt_tokens": 127,
    "completion_tokens": 342,
    "total_tokens": 469
  }
}

Les trois compteurs de base

• prompt_tokens : nombre de tokens dans votre requête (message system + historique + nouveau message). C’est la partie “entrée” de la facturation.
• completion_tokens : nombre de tokens générés par le modèle dans sa réponse. C’est la partie “sortie”.
• total_tokens : somme des deux précédents. C’est le total facturé pour cette requête.

Impact de l’historique sur les coûts

Comme l’endpoint est stateless, l’historique est renvoyé à chaque requête. Cela signifie que prompt_tokens augmente à chaque échange :

Échange 1 : prompt_tokens = 50   (system + 1 message user)
Échange 2 : prompt_tokens = 150  (system + 2 user + 1 assistant)
Échange 3 : prompt_tokens = 300  (system + 3 user + 2 assistant)
Échange 10: prompt_tokens = 1500 (system + 10 user + 9 assistant)

Pour les conversations longues, le coût de l’historique peut rapidement dépasser celui de la réponse elle-même.

Les reasoning_tokens : spécifique aux modèles de raisonnement

Les modèles Grok avec capacité de raisonnement (comme grok-4.20-0309-reasoning) ajoutent un champ supplémentaire dans l’objet usage :

{
  "usage": {
    "prompt_tokens": 127,
    "completion_tokens": 892,
    "total_tokens": 1019,
    "completion_tokens_details": {
      "reasoning_tokens": 550
    }
  }
}

Qu’est-ce que les reasoning_tokens ?

Les reasoning_tokens représentent les tokens utilisés par le modèle pour son raisonnement interne — la “réflexion” qu’il effectue avant de produire sa réponse finale. Ces tokens sont générés mais ne sont pas visibles dans le champ content de la réponse.

Dans l’exemple ci-dessus :

• Le modèle a généré 892 tokens au total (completion_tokens)
• Dont 550 tokens de raisonnement interne (reasoning_tokens)
• Et donc 342 tokens de réponse visible (892 - 550)

Pourquoi c’est important

Les reasoning tokens sont facturés comme des tokens de complétion normaux. Pour un modèle de raisonnement, la réponse visible peut ne représenter qu’une fraction du coût total :

usage = response.usage

visible_tokens = usage.completion_tokens - usage.completion_tokens_details.reasoning_tokens
reasoning_tokens = usage.completion_tokens_details.reasoning_tokens

print(f"Tokens visibles : {visible_tokens}")
print(f"Tokens raisonnement : {reasoning_tokens}")
print(f"Ratio raisonnement : {reasoning_tokens / usage.completion_tokens * 100:.0f}%")

Il n’est pas rare que les reasoning tokens représentent 50 à 80% des tokens de complétion pour des questions complexes.

Stratégies d’optimisation des coûts

Réduire les prompt_tokens

• Résumez l’historique : au lieu de renvoyer toute la conversation, résumez les échanges anciens
• Limitez le message system : un system prompt de 500 tokens est rarement nécessaire — visez 100-200 tokens
• Filtrez les messages : ne renvoyez que les échanges pertinents pour la question en cours

Contrôler les completion_tokens

• Utilisez max_tokens : définissez une limite raisonnable pour éviter les réponses trop longues
• Précisez le format : “Réponds en 3 phrases” coûte moins cher que “Explique en détail”
• Choisissez le bon modèle : un modèle sans raisonnement est moins coûteux si la tâche ne nécessite pas de réflexion complexe

Surveiller les coûts en production

import json

def log_usage(response, requete_id: str):
    usage = response.usage
    log = {
        "id": requete_id,
        "prompt": usage.prompt_tokens,
        "completion": usage.completion_tokens,
        "total": usage.total_tokens,
    }
    if hasattr(usage, "completion_tokens_details") and usage.completion_tokens_details:
        log["reasoning"] = usage.completion_tokens_details.reasoning_tokens

    print(json.dumps(log))

Points clés à retenir

• L’objet usage contient prompt_tokens, completion_tokens et total_tokens
• Les prompt_tokens augmentent à chaque échange à cause de l’historique renvoyé
• Les modèles de raisonnement ajoutent des reasoning_tokens dans completion_tokens_details
• Les reasoning tokens sont facturés mais invisibles dans la réponse — ils peuvent représenter 50-80% du coût
• Optimisez en résumant l’historique, limitant max_tokens et choisissant le bon modèle