Réduire votre facture d’API Claude : guide pratique du coût des tokens

Le modèle mental du budget de tokens

Chaque requête comporte deux facteurs de coût :

• Tokens d’entrée: le prompt système, le message utilisateur, l’historique de conversation, les définitions d’outils, les documents récupérés et tout préfixe mis en cache qui reste comptabilisé lorsqu’il n’est pas servi depuis le cache.
• Tokens de sortie: la réponse du modèle, y compris la verbosité involontaire et les nouvelles tentatives.

Une formule mentale utile est :

request_cost ≈ input_tokens × input_rate + output_tokens × output_rate

Cela paraît évident, mais change la façon dont vous analysez vos dépenses. Si la requête moyenne est « bon marché » en sortie mais coûteuse en entrée, retirer 400 tokens du prompt système peut avoir plus d’impact que de demander au modèle d’être plus concis.

Commencez par le choix du modèle

Toutes les tâches ne nécessitent pas le modèle le plus performant. Dans les systèmes réels, le choix du modèle est souvent l’optimisation la moins coûteuse.

Un piège fréquent consiste à « choisir par défaut un modèle supérieur ». Les équipes envoient souvent tous les prompts au modèle haut de gamme parce que cela semble plus sûr. En pratique, c’est une assurance coûteuse pour des tâches qui n’en tirent aucun bénéfice. Une couche de routage vaut généralement l’effort :

• Haiku pour la classification rapide, l’extraction de JSON, l’étiquetage des journaux et le tri initial.
• Sonnet pour la plupart des charges de travail des agents ou des outils de développement.
• Opus uniquement lorsque la tâche nécessite réellement un raisonnement plus poussé, une synthèse nuancée ou lorsque vous avez mesuré le coût d’un échec.

Une règle simple qui fonctionne bien :

1. Essayez Haiku pour les tâches structurées peu coûteuses.
2. Passez à Sonnet si le niveau de confiance est faible ou si la sortie est mal formée.
3. Passez à Opus uniquement pour les cas réellement difficiles.

Ce type de chaîne de repli coûte généralement moins cher que de payer les tarifs d’Opus pour chaque requête.

Réduisez le prompt système sans concession

C’est dans le prompt système que le gaspillage de tokens se cache au grand jour. Il a tendance à grossir comme la dette technique : une consigne ici, une règle de style là, cinq exemples que personne n’a supprimés.

Éléments à supprimer

• Les instructions redondantes que l’application fait déjà respecter.
• Les longs passages demandant d’« être utile » qui ne modifient pas le comportement.
• Les anciens exemples de cas limites qui n’ont plus d’importance.
• Les textes de règles répétés dans chaque requête.
• Les descriptions d’outils trop longues lorsqu’un schéma compact suffit.

Éléments à conserver

• Les contraintes de comportement non négociables.
• Les règles de format de sortie.
• Les instructions essentielles à la sécurité.
• Les exemples minimaux qui améliorent sensiblement la fiabilité.

En pratique, j’ai vu des équipes retirer des centaines ou des milliers de tokens du préfixe répété sans modifier la qualité du modèle. L’astuce consiste à traiter le prompt système comme du code de production : supprimer le texte inutile, dédupliquer les règles et ne garder que ce qui influe sur le comportement.

Une meilleure approche consiste à encoder une structure plutôt que de la prose :

{
  "style": "concise",
  "output": "json",
  "must_include": ["root_cause", "next_steps"],
  "must_avoid": ["speculation", "apologies"]
}

C’est plus facile à analyser que trois paragraphes d’instructions rédigées.

Utilisez la mise en cache des prompts pour les préfixes stables

Si votre pile technique prend en charge la mise en cache des prompts, utilisez-la pour tout ce qui se répète d’une requête à l’autre : prompts système, schémas d’outils, exemples d’apprentissage en contexte et longs blocs de règles.

L’idée essentielle n’est pas que « la mise en cache est gratuite ». Elle ne l’est pas. Le gain tient au fait que vous cessez de payer à nouveau le plein tarif pour le même préfixe à chaque appel.

Bons candidats à la mise en cache

• Prompts système communs à l’ensemble du produit
• Définitions volumineuses de fonctions ou d’outils
• Instructions de récupération d’informations réutilisées
• Exemples statiques de mise en forme ou de style
• Structure de base des agents qui change rarement

Mauvais candidats à la mise en cache

• Contexte utilisateur propre à chaque requête
• Documents nouvellement récupérés
• Instructions qui changent rapidement
• Contenu du brouillon de travail propre à la session

L’erreur courante consiste à placer du contenu très variable dans le préfixe, puis à se demander pourquoi le taux de succès du cache est faible. Pour en tirer parti, gardez le segment mis en cache stable et placez les données propres à la requête après celui-ci.

Exemple de structure de requête :

{
  "system": "Stable application prompt + tool definitions + output contract",
  "messages": [
    { "role": "user", "content": "New ticket text here" }
  ]
}

Si vous gardez la partie stable inchangée, vous permettez à la mise en cache d’être réellement utile. Si le préfixe change à chaque requête, vous ne faites que payer les frais de gestion du cache sans aucun bénéfice.

Définissez max_tokens Avec détermination

L’un des coûts cachés les plus faciles à générer est une limite de génération trop élevée. Si vous définissez max_tokens à une valeur énorme « au cas où », vous favorisez les réponses longues, surtout lorsque le modèle est incertain ou verbeux.

Utilisez la limite la plus basse qui permet encore d’accomplir la tâche.

Plages pratiques

• Extraction / classification: 32–128 tokens
• Résumés courts: 128–256 tokens
• Différences de code / explications: 256–800 tokens
• Génération ouverte: uniquement aussi élevée que nécessaire

Si la tâche consiste à « renvoyer un objet JSON », imposez un plafond strict. Si la tâche consiste à « expliquer cette architecture », ne laissez pas au modèle la latitude d’écrire un roman, sauf si c’est ce que vous souhaitez.

Beaucoup d’équipes oublient aussi de limiter les boucles de nouvelle tentative. Si l’analyse échoue et que vous demandez automatiquement au modèle de réessayer avec la même limite de sortie généreuse, vous pouvez doubler ou tripler les dépenses liées à la sortie pour une seule action utilisateur.

Regroupez les petites tâches

Le traitement par lots est utile lorsque vous avez de nombreuses petites tâches indépendantes dont les instructions représentent une surcharge similaire.

Au lieu de ceci :

• 50 requêtes de classification distinctes
• 50 prompts système répétés
• 50 définitions d’outils répétées

Faites ceci :

• Une requête contenant 50 éléments
• Un bloc d’instructions commun
• Un schéma de sortie compact

Exemple de structure de prompt :

Classify each item into one of: bug, feature, question, billing.

Items:
1. "App crashes after login"
2. "Can you add dark mode?"
3. "How do I reset my password?"

Et le contrat de réponse :

[
  {"id": 1, "label": "bug"},
  {"id": 2, "label": "feature"},
  {"id": 3, "label": "question"}
]

Cela réduit la surcharge répétée et améliore souvent le débit. La contrepartie est l’étendue de l’impact d’un échec : si un élément ne respecte pas le format, il peut être nécessaire de reprendre tout le lot. Pour les traitements à forte valeur ou destinés aux utilisateurs et sensibles à la latence, des lots plus petits peuvent rester préférables.

Le streaming améliore la réactivité, pas le coût des tokens

Le streaming est excellent pour l’expérience utilisateur et parfois pour la maîtrise des coûts, mais il ne permet pas pas, à lui seul, de réduire comme par magie les tokens facturés. Vous payez toujours pour tout ce que le modèle génère.

Là où le streaming est vraiment utile, c’est pour l’arrêt anticipé:

• L’utilisateur voit la progression plus tôt.
• Votre application peut annuler la génération dès qu’elle dispose de suffisamment de contenu.
• Vous pouvez interrompre une réponse qui s’emballe avant qu’elle n’atteigne le plafond configuré.

Ce dernier point compte. Si vous générez une réponse pour un analyseur en aval et que les premiers 120 tokens contiennent déjà le JSON nécessaire, ne continuez pas à recueillir 800 tokens d’explication supplémentaires.

En pratique, le streaming vaut la peine lorsque votre application peut réagir pendant la génération. Si vous vous contentez d’envoyer le flux dans un journal et attendez de toute façon la réponse complète, vous bénéficiez de l’avantage pour l’expérience utilisateur, mais sans grande réduction des coûts.

Mesurez le coût par requête, pas seulement par mois

Les dépenses mensuelles vous indiquent qu’il y a un problème. Les métriques par requête vous indiquent où il se trouve.

Suivez au minimum :

• input_tokens
• output_tokens
• cache_hit_tokens si disponible
• le nom du modèle
• le point de terminaison / le parcours fonctionnel
• la latence
• le nombre de nouvelles tentatives
• le taux de troncature ou d’échec d’analyse

Une charge utile simple de journalisation pourrait ressembler à ceci :

usage = response["usage"]

record = {
    "model": response["model"],
    "input_tokens": usage["input_tokens"],
    "output_tokens": usage["output_tokens"],
    "latency_ms": latency_ms,
    "cache_hit_tokens": usage.get("cache_read_input_tokens", 0),
    "request_type": "ticket_summary",
}
print(record)

Calculez ensuite le coût de manière centralisée :

def estimate_cost(input_tokens, output_tokens, input_rate, output_rate):
    return (input_tokens * input_rate) + (output_tokens * output_rate)

Les tarifs exacts dépendent de votre fournisseur et de votre modèle, mais la démarche reste la même. Une fois que vous pouvez classer les requêtes par coût, les responsables sautent généralement aux yeux :

• Un « petit » prompt avec un énorme préfixe caché
• Un appel d’outil qui renvoie des documents complets à chaque échange
• Un plafond de génération qui représente 10x les besoins de la tâche
• Une boucle de nouvelle tentative qui double discrètement la consommation
• Un routage qui devrait utiliser Haiku, mais utilise toujours Opus

Évitez le gaspillage discret

La plupart du gaspillage de tokens est banal, ce qui explique pourquoi il passe les revues de code.

Causes fréquentes

• Renvoyer le même long historique de conversation à chaque échange
• Inclure des fichiers source complets lorsqu’un simple différentiel suffit
• Demander du texte rédigé alors qu’un JSON structuré suffirait
• Renvoyer des explications verbeuses à des systèmes automatisés
• Transmettre des schémas d’outils plus volumineux que la tâche elle-même
• Laisser les nouvelles tentatives automatiques réexécuter le même prompt coûteux
• Conserver des journaux ou des notes internes dans le contexte du modèle

Un piège particulièrement insidieux est « l’enrichissement utile du contexte ». Les systèmes de récupération récupèrent souvent trop de contenu parce que quelqu’un voulait jouer la prudence. Si le modèle n’a besoin que des trois paragraphes les plus pertinents, ne lui fournissez pas le document entier simplement parce que la couche de découpage le facilite.

Autre piège : si vous ajoutez autour du modèle un second prompt indiquant « soyez concis », vous venez peut-être d’ajouter des tokens pour résoudre un problème de verbosité qui aurait dû être réglé par un schéma de sortie plus strict.

Une conception pratique des requêtes

Voici une structure qui fonctionne bien pour de nombreuses tâches en production :

request = {
    "model": "claude-sonnet-4.6",
    "max_tokens": 180,
    "system": "Extract the root cause and next action. Return strict JSON.",
    "messages": [
        {
            "role": "user",
            "content": "Investigate this incident summary: ... "
        }
    ]
}

Pourquoi cette structure fonctionne :

• Le modèle choisi est suffisamment performant pour un raisonnement de complexité modérée.
• Le plafond de sortie limite la verbosité excessive.
• Le prompt système est court et précis.
• Le format de sortie est adapté au traitement automatisé.
• La charge utile utilisateur contient uniquement les données d’entrée nécessaires à la tâche.

Si vous avez besoin de plus de contexte, ajoutez-le délibérément. Ne laissez pas le contexte s’accumuler par accident.

Ce qui fait vraiment varier la facture

Si je devais classer les gains les plus importants, ce serait :

1. Choisir un modèle moins cher pour les tâches simples
2. Réduire les prompts inutilement volumineux
3. Limiter max_tokens strictement
4. Utiliser la mise en cache des prompts pour les préfixes stables
5. Regrouper les petites tâches indépendantes
6. Mesurer la consommation par requête
7. Empêcher les boucles de nouvelle tentative de doubler les dépenses

Cet ordre compte. Les équipes commencent souvent par des optimisations exotiques avant de corriger l’évidence : elles demandent tout simplement trop de choses, trop souvent, au modèle le plus cher, avec trop de contexte.

Conseils pratiques

• Utilisez Haiku pour l’extraction et le routage simples, Sonnet pour la plupart des tâches liées au produit, et Opus uniquement lorsque la tâche le justifie.
• Considérez la prompt système comme un centre de coûts ; supprimez le texte répété et ne conservez que les instructions qui modifient le comportement.
• Activez la mise en cache des prompts pour les préfixes stables comme les politiques, les schémas d’outils et les exemples d’apprentissage en quelques exemples.
• Définissez max_tokens au plafond utile le plus bas et réévaluez-le pour chaque tâche.
• Regroupez les petites tâches indépendantes lorsque la surcharge liée aux instructions prédomine.
• Suivez les tokens d’entrée, les tokens de sortie, les accès au cache, les nouvelles tentatives et la latence par requête.
• Surveillez le gaspillage discret: historique répété, récupération excessive de contenu, sorties verbeuses et boucles de nouvelle tentative automatique.

Si vous le souhaitez, je peux en faire un article complémentaire avec un exemple concret de tableau de bord des coûts et quelques règles de routage pour Haiku/Sonnet/Opus.