Compter les tokens avec l'API 📊

L'endpoint de comptage

L'API /v1/messages/count_tokens accepte la même structure que l'endpoint Messages :

curl https://api.anthropic.com/v1/messages/count_tokens \
    --header "x-api-key: $ANTHROPIC_API_KEY" \
    --header "content-type: application/json" \
    --header "anthropic-version: 2023-06-01" \
    --data '{
      "model": "claude-opus-4-8",
      "system": "Tu es un développeur senior",
      "messages": [{
        "role": "user",
        "content": "Crée une API REST avec auth JWT"
      }]
    }'

{ "input_tokens": 28 }

Ce qui est compté

Exemples pratiques

Avec des outils

const count = await client.messages.countTokens({
  model: "claude-opus-4-8",
  tools: [{
    name: "get_weather",
    description: "Obtenir la météo",
    input_schema: {
      type: "object",
      properties: { location: { type: "string" } },
      required: ["location"],
    },
  }],
  messages: [{ role: "user", content: "Météo à Paris ?" }],
});
// { input_tokens: 403 }

💡 Les outils consomment beaucoup de tokens car le schéma JSON est détaillé.

Avec des images

const count = await client.messages.countTokens({
  model: "claude-opus-4-8",
  messages: [{
    role: "user",
    content: [
      { type: "image", source: { type: "base64", media_type: "image/jpeg", data: imageData } },
      { type: "text", text: "Décris cette image" },
    ],
  }],
});
// { input_tokens: 1551 }

Avec la réflexion étendue

const count = await client.messages.countTokens({
  model: "claude-sonnet-4-6",
  thinking: { type: "enabled", budget_tokens: 16000 },
  messages: [
    { role: "user", content: "Prouve qu'il existe une infinité de nombres premiers" },
    { role: "assistant", content: [
      { type: "thinking", thinking: "Réflexion...", signature: "..." },
      { type: "text", text: "Voici la preuve..." },
    ]},
    { role: "user", content: "Écris une preuve formelle" },
  ],
});
// { input_tokens: 88 }

⚠️ Les blocs de réflexion des tours précédents sont ignorés. Seule la réflexion du tour actuel compte.

Limites de débit

⚠️ Le comptage de tokens et la création de messages ont des limites séparées et indépendantes.

Résumé

• L'endpoint /v1/messages/count_tokens est gratuit
• Il accepte le même format que Messages (outils, images, PDF, réflexion)
• Le comptage est une estimation (pas exact)
• Les tokens système ne sont pas facturés
• Utilisez-le pour piloter vos décisions de routage et d'optimisation

curl https://api.anthropic.com/v1/messages/count_tokens \
  --header "x-api-key: $ANTHROPIC_API_KEY" \
  --header "content-type: application/json" \
  --header "anthropic-version: 2023-06-01" \
  --data '{
    "model": "claude-opus-4-8",
    "system": "Tu es un développeur senior",
    "messages": [{
      "role": "user",
      "content": "Crée une API REST"
    }]
  }'