Maîtriser les coûts Claude Code/API : budgets de tokens, alertes et limites

Claude Code devient beaucoup plus simple à déployer quand le coût est explicable avant la facture. La dépense ne dépend pas seulement du modèle choisi. Elle dépend aussi du contexte, des fichiers lus, de la longueur des réponses, des réussites de prompt caching et du mode d’authentification : abonnement Claude ou facturation directe via l’API Anthropic.

Ce guide a été vérifié le 2026-06-03 avec les sources officielles : Anthropic API pricing, Claude Code cost management, Prompt caching, Token counting et Usage and Cost API. Les prix changent ; vérifiez toujours les pages officielles avant un achat ou un devis client.

Le modèle de coût en clair

Terme	Sens pratique	Effet sur le coût
Tokens	Unités que Claude lit et écrit	Fichiers, logs, prompts et code long augmentent la facture
Contexte	Historique, fichiers lus, CLAUDE.md, définitions d’outils	Un contexte inutile est payé à chaque requête suivante
Prompt cache	Réutilisation d’un préfixe déjà traité	Les entrées répétées deviennent beaucoup moins chères
Budget guard	Limite par tâche, jour, utilisateur ou workspace	Empêche une automatisation utile de devenir illimitée

coût estimé = tokens d'entrée * tarif entrée
            + tokens écrits en cache * tarif écriture cache
            + tokens lus du cache * tarif lecture cache
            + tokens de sortie * tarif sortie

Au 2026-06-03, Sonnet 4.6 est listé à $3/MTok en entrée et $15/MTok en sortie. Haiku 4.5 est à $1 et $5. Opus 4.8/4.7/4.6 est à $5 et $25. Les lectures de cache coûtent 10% du prix d’entrée de base, et les écritures de cache de 5 minutes coûtent 1.25x ce prix.

La sortie est souvent la partie qui dérape. Une consigne comme « explique tout en détail » devrait devenir « liste les 5 risques principaux, par gravité, en deux lignes chacun ».

Boucle de contrôle

flowchart LR
  A["Définir la tâche"] --> B["Réduire l'entrée"]
  B --> C["Choisir le modèle"]
  C --> D["Estimer les tokens"]
  D --> E{"Dans le budget ?"}
  E -- "Oui" --> F["Lancer Claude"]
  E -- "Non" --> B
  F --> G["Journaliser usage"]
  G --> H{"Seuil atteint ?"}
  H -- "Oui" --> I["Arrêter, alerter ou changer de modèle"]
  H -- "Non" --> A

Dans Claude Code, commencez par /usage et /context. Utilisez /clear quand vous changez de sujet, et /compact quand vous voulez garder les décisions sans tout l’historique. Le montant de /usage est une estimation locale ; la référence de facturation reste Console, puis les rapports Usage and Cost pour les organisations.

Exemple 1 : estimateur mensuel

Ce script ne contacte pas l’API. Il convertit une consommation quotidienne en MTok en coût mensuel.

// claude-cost-estimator.mjs
const RATES = {
  opus48: { input: 5, output: 25, cacheRead: 0.5 },
  sonnet46: { input: 3, output: 15, cacheRead: 0.3 },
  haiku45: { input: 1, output: 5, cacheRead: 0.1 },
};

const [model = "sonnet46", days = "22", input = "0.25", output = "0.06", cacheRead = "0.20"] =
  process.argv.slice(2);

if (!RATES[model]) {
  throw new Error(`Unknown model: ${model}`);
}

const rate = RATES[model];
const dailyUsd =
  Number(input) * rate.input +
  Number(output) * rate.output +
  Number(cacheRead) * rate.cacheRead;

console.log({
  model,
  workDays: Number(days),
  dailyUsd: Number(dailyUsd.toFixed(4)),
  monthlyUsd: Number((dailyUsd * Number(days)).toFixed(2)),
});

node claude-cost-estimator.mjs sonnet46 22 0.25 0.06 0.20
node claude-cost-estimator.mjs haiku45 22 0.25 0.06 0.20

L’objectif n’est pas une prévision parfaite, mais un ordre de grandeur. Ajoutez 20 à 30% de marge pour les outils, les retries, les écritures de cache et les réponses plus longues que prévu.

Exemple 2 : appel API avec limite journalière

Cet exemple compte les tokens avant l’envoi, enregistre le usage réel en JSONL et bloque la requête si le budget journalier serait dépassé.

npm init -y
npm i @anthropic-ai/sdk

// budgeted-message.mjs
import Anthropic from "@anthropic-ai/sdk";
import fs from "node:fs";

const anthropic = new Anthropic({ apiKey: process.env.ANTHROPIC_API_KEY });
const model = process.env.CLAUDE_MODEL ?? "claude-sonnet-4-6";
const maxTokens = Number(process.env.MAX_TOKENS ?? 700);
const dailyBudgetUsd = Number(process.env.DAILY_BUDGET_USD ?? 5);

const RATES = {
  "claude-opus-4-8": { input: 5, output: 25, cacheWrite5m: 6.25, cacheRead: 0.5 },
  "claude-sonnet-4-6": { input: 3, output: 15, cacheWrite5m: 3.75, cacheRead: 0.3 },
  "claude-haiku-4-5": { input: 1, output: 5, cacheWrite5m: 1.25, cacheRead: 0.1 },
};

function usdFromUsage(usage, rate) {
  return (
    (usage.input_tokens ?? 0) * rate.input +
    (usage.output_tokens ?? 0) * rate.output +
    (usage.cache_creation_input_tokens ?? 0) * rate.cacheWrite5m +
    (usage.cache_read_input_tokens ?? 0) * rate.cacheRead
  ) / 1_000_000;
}

function todayTotalUsd(path) {
  if (!fs.existsSync(path)) return 0;
  const today = new Date().toISOString().slice(0, 10);
  return fs.readFileSync(path, "utf8")
    .trim()
    .split("\n")
    .filter(Boolean)
    .map((line) => JSON.parse(line))
    .filter((row) => row.date === today)
    .reduce((sum, row) => sum + row.usd, 0);
}

const messages = [
  { role: "user", content: "List only the top three bug risks in this TypeScript function." },
];

const rate = RATES[model];
if (!rate) throw new Error(`No rate table for ${model}`);

const counted = await anthropic.messages.countTokens({ model, messages });
const worstCaseUsd = (counted.input_tokens * rate.input + maxTokens * rate.output) / 1_000_000;
const logPath = "claude-usage.jsonl";

if (todayTotalUsd(logPath) + worstCaseUsd > dailyBudgetUsd) {
  throw new Error(`Budget stop: projected daily spend exceeds $${dailyBudgetUsd}`);
}

const response = await anthropic.messages.create({
  model,
  max_tokens: maxTokens,
  cache_control: { type: "ephemeral" },
  system: "You are a concise senior code reviewer. Return only actionable findings.",
  messages,
});

const usd = usdFromUsage(response.usage, rate);
fs.appendFileSync(logPath, JSON.stringify({
  date: new Date().toISOString().slice(0, 10),
  model,
  usd: Number(usd.toFixed(6)),
  usage: response.usage,
}) + "\n");

console.log({ id: response.id, usd: Number(usd.toFixed(6)), usage: response.usage });

ANTHROPIC_API_KEY=sk-ant-...
DAILY_BUDGET_USD=5 node budgeted-message.mjs

Pour un débutant, la logique est simple : peser la requête, garder le reçu, arrêter avant de dépasser la journée.

Exemple 3 : rapport d’équipe

Les organisations peuvent interroger l’Admin Usage and Cost API. Il faut une clé Admin API ; une clé standard ou un compte individuel ne suffit pas.

curl "https://api.anthropic.com/v1/organizations/usage_report/messages?\
starting_at=2026-06-01T00:00:00Z&\
ending_at=2026-06-08T00:00:00Z&\
group_by[]=model&\
bucket_width=1d" \
  --header "anthropic-version: 2023-06-01" \
  --header "x-api-key: $ANTHROPIC_ADMIN_KEY"

Signal	Risque	Action
Part d’Opus	Des tâches simples utilisent le modèle premium	Router résumé, traduction et formatage vers Sonnet/Haiku
Tokens de sortie	Les réponses sont trop longues	Limiter items, lignes et max_tokens
Lecture cache	cache_read_input_tokens proche de zéro	Retirer timestamps et valeurs aléatoires du préfixe

Trois cas d’usage

Développeur solo : gardez Sonnet par défaut, réservez Opus aux décisions d’architecture ou au débogage difficile, puis nettoyez le contexte quand la tâche change.

Contenu et localisation : mettez en cache le guide de style et ne changez que le corps de l’article. Pour du volume asynchrone, évaluez Batch API et sa réduction de 50%.

Formation d’équipe : les journées de formation concentrent les requêtes. Définissez budget quotidien, seuils et règles de prompts avant l’atelier. Pour un programme complet, consultez /training/.

Pièges fréquents

Une clé API change la facturation. L’aide officielle indique que ANTHROPIC_API_KEY peut prendre le dessus sur l’abonnement connecté dans Claude Code. Vérifiez avec /status.

Le cache est supposé, pas mesuré. Le cache dépend d’un préfixe stable. Un timestamp ou un UUID dans le system prompt peut faire tomber le taux de hit.

La sortie n’est pas bornée. Une revue doit limiter le nombre de constats ; un résumé doit limiter sa taille ; une génération de code doit limiter les fichiers.

Des prix anciens sont recopiés. Les modèles et tarifs évoluent. Vérifiez la page officielle avant de publier un calculateur ou un devis.

Les proxys bon marché sont utilisés sans audit. Si l’identité du modèle, les logs et les identifiants ne sont pas clairs, la remise cache peut-être un risque.

À lire aussi

• Claude Code token optimization
• Claude Code pricing guide
• Claude Code context management
• Claude Code permission budget loop

Des modèles, checklists et feuilles de budget réutilisables sont disponibles dans /products/.

Résultat pratique

Dans les tests ClaudeCodeLab, le meilleur gain venait de contrôles ordinaires : mettre en cache les consignes communes, envoyer traduction et formatage vers Haiku/Sonnet, réserver Opus aux décisions difficiles et écrire chaque usage en JSONL. Commencez par une alerte à 80%, un arrêt à 100% et un nettoyage du contexte quand la tâche change.