Accueil / L'API Claude pour ceux qui construisent

Deux leviers de coût, la mémoire en cache et le traitement par lot

Un préfixe de requête marqué comme réutilisable coûte une fraction réduite du prix normal quand il est relu depuis le cache, et un ensemble de requêtes non urgentes traité en lot coûte moins cher qu'un traitement immédiat, deux réductions qui se cumulent entre elles et avec les autres modificateurs de prix.

Deux mécanismes réduisent le coût d'une requête à l'API Messages sans changer sa réponse : la mémoire en cache réutilise un préfixe stable d'une requête à l'autre, et le traitement par lot regroupe des requêtes non urgentes dans un envoi différé.

La mémoire en cache, une lecture moins chère qu'une entrée normale

Marquer un bloc de contenu comme réutilisable crée un point de rupture dans la requête : tout ce qui précède ce point peut être relu depuis le cache lors d'un appel suivant qui partage exactement le même préfixe. Une lecture en cache coûte une fraction réduite du prix d'entrée normal pour la quasi totalité des modèles actuels, la figure de cette leçon en donne le taux exact avec sa source. L'écriture initiale dans le cache coûte au contraire plus cher que l'entrée normale, et se choisit entre deux durées de conservation, cinq minutes ou une heure, la plus longue coûtant davantage à l'écriture. Le cache se rentabilise dès la première relecture en conservation cinq minutes, la durée par défaut, et à partir de la deuxième relecture seulement en conservation une heure.

Le traitement par lot, un envoi différé à prix réduit

L'API de traitement par lot accepte un ensemble de requêtes indépendantes et les traite de façon différée, avec une réduction fixe sur les jetons d'entrée comme de sortie, quel que soit le modèle appelé, chiffrée elle aussi dans la figure de cette leçon. Cette réduction convient à un travail qui n'attend pas de réponse immédiate : classer un lot de documents, générer des résumés en série, ou reconstituer un jeu de test. Les deux mécanismes se cumulent entre eux et avec les autres modificateurs de prix : un préfixe mis en cache puis relu dans une requête envoyée en lot bénéficie des deux réductions à la fois.

Le même préfixe stable qui bénéficie du cache entre aussi dans le calcul de la fenêtre de contexte avant l'envoi, puisque marquer un bloc comme réutilisable ne change rien à son poids en jetons.

import anthropic

client = anthropic.Anthropic()

instructions_stables = "Vous etes un assistant qui repond en une phrase. " * 200

reponse = client.messages.create(
    model="claude-sonnet-5",
    max_tokens=100,
    system=[
        {
            "type": "text",
            "text": instructions_stables,
            "cache_control": {"type": "ephemeral"},
        }
    ],
    messages=[{"role": "user", "content": "Resume ce texte en une phrase."}],
)

print("jetons ecrits en cache :", reponse.usage.cache_creation_input_tokens)
print("jetons lus depuis le cache :", reponse.usage.cache_read_input_tokens)

Le premier appel avec ce préfixe paie le tarif d'écriture, et un second appel qui réutilise exactement le même texte avant le point de rupture paie le tarif de lecture réduit. Le champ usage de la réponse distingue les deux compteurs, ce qui permet de vérifier que le cache a réellement été touché plutôt que de le supposer. Un préfixe trop court, sous un seuil minimal qui va de 512 à 4 096 jetons selon le modèle appelé, n'est jamais mis en cache et n'affiche aucune erreur, la requête part simplement au tarif normal.