Usage des tokens et reasoning_tokens

Comprendre la facturation par tokens

Chaque requete a l’API Chat Completions est facturee en fonction du nombre de tokens consommes. L’objet usage dans la reponse vous donne un decompte precis qui est essentiel pour surveiller vos couts, optimiser vos prompts et dimensionner vos budgets API.

L’objet usage standard

Voici la structure de l’objet usage retourne avec chaque reponse :

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

Les trois compteurs de base

• prompt_tokens : nombre de tokens dans votre requete (message system + historique + nouveau message). C’est la partie “entree” de la facturation.
• completion_tokens : nombre de tokens generes par le modele dans sa reponse. C’est la partie “sortie”.
• total_tokens : somme des deux precedents. C’est le total facture pour cette requete.

Impact de l’historique sur les couts

Comme l’endpoint est stateless, l’historique est renvoye a chaque requete. Cela signifie que prompt_tokens augmente a chaque echange :

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

Pour les conversations longues, le cout de l’historique peut rapidement depasser celui de la reponse elle-meme.

Les reasoning_tokens : specifique aux modeles de raisonnement

Les modeles Grok avec capacite de raisonnement (comme grok-4.20-reasoning) ajoutent un champ supplementaire 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 representent les tokens utilises par le modele pour son raisonnement interne — la “reflexion” qu’il effectue avant de produire sa reponse finale. Ces tokens sont generes mais ne sont pas visibles dans le champ content de la reponse.

Dans l’exemple ci-dessus :

• Le modele a genere 892 tokens au total (completion_tokens)
• Dont 550 tokens de raisonnement interne (reasoning_tokens)
• Et donc 342 tokens de reponse visible (892 - 550)

Pourquoi c’est important

Les reasoning tokens sont factures comme des tokens de completion normaux. Pour un modele de raisonnement, la reponse visible peut ne representer qu’une fraction du cout 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 representent 50 a 80% des tokens de completion pour des questions complexes.

Strategies d’optimisation des couts

Reduire les prompt_tokens

• Resumez l’historique : au lieu de renvoyer toute la conversation, resumez les echanges anciens
• Limitez le message system : un system prompt de 500 tokens est rarement necessaire — visez 100-200 tokens
• Filtrez les messages : ne renvoyez que les echanges pertinents pour la question en cours

Controler les completion_tokens

• Utilisez max_tokens : definissez une limite raisonnable pour eviter les reponses trop longues
• Precisez le format : “Reponds en 3 phrases” coute moins cher que “Explique en detail”
• Choisissez le bon modele : un modele sans raisonnement est moins couteux si la tache ne necessite pas de reflexion complexe

Surveiller les couts 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 cles a retenir

• L’objet usage contient prompt_tokens, completion_tokens et total_tokens
• Les prompt_tokens augmentent a chaque echange a cause de l’historique renvoye
• Les modeles de raisonnement ajoutent des reasoning_tokens dans completion_tokens_details
• Les reasoning tokens sont factures mais invisibles dans la reponse — ils peuvent representer 50-80% du cout
• Optimisez en resumant l’historique, limitant max_tokens et choisissant le bon modele