Guide des coûts du Prompt Caching : Cache Hits, préfixes et dépenses réelles en API

Le coût de la mise en cache des prompts dépend de la ressemblance exacte entre votre deuxième requête et la première, et non de la remise annoncée. Dans notre estimation pour un prompt système de 20 000 tokens sur claude-sonnet-5, 1 000 requêtes coûtent environ 18,18 $ sans cache et environ 2,00 $ lorsque chaque requête après la première atteint le cache. Le même prompt coûte plus cher que la référence sans cache si le préfixe change à chaque appel. Ce guide utilise les prix TokenLab observés le 03/10/2026 pour montrer où se situe cette limite, et il signale ce que nous n'avons pas pu confirmer dans la documentation.

Points clés à retenir

• Sur les cinq modèles que nous avons vérifiés, une lecture en cache coûte entre 2 % et 10 % du prix d'entrée normal. Deux des cinq modèles n'affichent aucun prix d'écriture en cache.
• Lorsqu'un prix d'écriture existe, il est soit égal au prix d'entrée (deepseek-v4.1-flash), soit 1,25 fois supérieur au prix d'entrée (claude-sonnet-5, claude-sonnet-5-5).
• Selon nos calculs, un hit de cache par écriture compense la prime d'écriture de 1,25x. Cela suppose que l'entrée en cache est toujours active, et la durée de vie du cache n'est pas documentée dans les éléments que nous avons consultés.
• La mise en cache ne réduit que la partie « entrée » de la facture. Les tokens de sortie sont facturés comme auparavant.
• La documentation de l'API TokenLab que nous avons consultée ne mentionne pas de champ pour les tokens mis en cache dans usage. Enregistrez l'objet brut de votre propre test et réconciliez-le avec Usage.

Coût de mise en cache des prompts par modèle : prix de lecture, d'écriture et d'entrée

Nous avons consulté l'API des modèles en direct pour chaque modèle ci-dessous le 03/10/2026. Les cinq modèles listent prompt-cache dans leurs capacités, et la tarification a été mise à jour pour la dernière fois le 02/10/2026 à 16:53:30.068Z. Les prix sont en USD pour 1 million de tokens.

Modèle	Entrée	Lecture cache	Écriture cache	Lecture en % de l'entrée	Écriture vs entrée
claude-sonnet-5	0,90	0,09	1,125	10 %	1,25x
claude-sonnet-5-5	0,60	0,06	0,75	10 %	1,25x
gpt-5.5	1,50	0,15	non listé	10 %	non listé
deepseek-v4.1-flash (heures creuses)	0,15	0,003	0,15	2 %	1,0x
deepseek-v4.1-flash (heures pleines)	0,30	0,006	0,30	2 %	1,0x
gemini-3.8-flash	0,375	0,0375	non listé	10 %	non listé

Les deux colonnes de pourcentage sont le résultat de notre propre division des prix listés.

Sources, toutes observées le 03/10/2026 :

• claude-sonnet-5 (page du modèle : /models/claude-5/claude-sonnet-5)
• claude-sonnet-5-5 (page du modèle : /models/claude-5/claude-sonnet-5-5)
• gpt-5.5 (page du modèle : /models/gpt-5-5/gpt-5.5)
• deepseek-v4.1-flash (page du modèle : /models/deepseek-v4/deepseek-v4.1-flash)
• gemini-3.8-flash (page du modèle : /models/gemini-3/gemini-3.8-flash)

Trois détails sont importants lors de la lecture de ce tableau.

Premièrement, gpt-5.5 et gemini-3.8-flash listent un prix de lecture en cache mais aucun prix d'écriture. Nous ne pouvons pas dire à partir de ces données comment un préfixe utilisé pour la première fois est facturé sur ces deux modèles. Les preuves ne disent pas que c'est gratuit, et elles ne disent pas non plus que c'est facturé au tarif d'entrée. Vérifiez Usage après une première requête avant de construire une prévision basée sur l'une ou l'autre de ces hypothèses.

Deuxièmement, lorsque nous avons consulté deepseek-v4.1-flash, nous avons trouvé deux entrées de prix. L'entrée off-peak (sélecteur offPeak: true) et l'entrée peak (offPeak: false) diffèrent d'un facteur de deux sur chaque ligne. Vos économies de cache par token représentent le même pourcentage, mais les dollars absolus doublent en heures pleines.

Troisièmement, il s'agit des prix publics de TokenLab. Le guide de facturation (observé le 03/10/2026) indique qu'une requête terminée est facturée une fois pour l'option de livraison qui l'a produite. Official suit le prix public du créateur du modèle, vérifiez donc quelle option a servi votre requête avant de comparer avec une grille tarifaire du créateur.

La référence Get a Model montre gpt-5.6-terra avec prompt-cache parmi ses capacités. Son exemple de réponse ne contient aucun prix, nous avons donc exclu ce modèle du tableau. Nous n'avons pas vérifié les autres modèles du catalogue.

Exemple concret de coût de mise en cache : un long prompt système

Voici le scénario, avec chaque entrée indiquée afin que vous puissiez insérer vos propres chiffres. Ce sont nos hypothèses, pas des mesures.

• Un prompt système et un bloc d'outils de 20 000 tokens, identiques à chaque requête.
• Un message utilisateur de 200 tokens qui change à chaque requête.
• 1 000 requêtes, avec le cache restant actif pendant toute la durée, soit une écriture et 999 lectures.
• Les tokens de sortie sont ignorés, car ils coûtent la même chose avec ou sans mise en cache.

claude-sonnet-5 à 0,90 d'entrée, 0,09 de lecture et 1,125 d'écriture par 1M de tokens :

• Sans mise en cache : 1 000 × 20 200 = 20 200 000 tokens × 0,90 $/1M = 18,18 $
• Écriture cache : 20 000 × 1,125 $/1M = 0,0225 $
• Lectures cache : 999 × 20 000 = 19 980 000 × 0,09 $/1M = 1,7982 $
• Suffixes sans cache : 1 000 × 200 = 200 000 × 0,90 $/1M = 0,18 $
• Avec mise en cache : 0,0225 + 1,7982 + 0,18 = environ 2,00 $, soit environ 89 % de moins que le chiffre sans cache

Passons maintenant au cas d'échec, où le préfixe change légèrement à chaque appel, de sorte que chaque requête paie une écriture et ne fait jamais de lecture. Cela coûte 1 000 × 20 000 × 1,125 $/1M = 22,50 $ pour les préfixes, plus les mêmes 0,18 $ pour les suffixes. Le total est d'environ 22,68 $, soit 4,50 $ (25 %) de plus que les 18,18 $ sans cache.

Le seuil de rentabilité découle des mêmes prix. Par million de tokens de préfixe, une écriture coûte 0,225 $ de plus qu'une entrée simple, et chaque lecture permet d'économiser 0,81 $. Un hit rembourse l'écriture avec une marge confortable (0,225 ÷ 0,81 ≈ 0,28 lecture par écriture).

Le même scénario sur les autres modèles :

Modèle	Sans cache	Avec cache (estimation)	Hypothèse pour la première requête
claude-sonnet-5	18,18 $	2,00 $	prix d'écriture listé
claude-sonnet-5-5	12,12 $	1,33 $	prix d'écriture listé
deepseek-v4.1-flash heures creuses	3,03 $	0,09 $	prix d'écriture listé
deepseek-v4.1-flash heures pleines	6,06 $	0,19 $	prix d'écriture listé
gpt-5.5	30,30 $	3,33 $	aucun prix d'écriture listé ; nous avons facturé 20 000 tokens au tarif d'entrée
gemini-3.8-flash	7,58 $	0,83 $	aucun prix d'écriture listé ; nous avons facturé 20 000 tokens au tarif d'entrée

Pour gpt-5.5, le calcul est 20 000 × 1,50 $/1M = 0,03 $, plus 19 980 000 × 0,15 $/1M = 2,997 $, plus 200 000 × 1,50 $/1M = 0,30 $. Les deux lignes marquées reposent sur une hypothèse que les preuves ne soutiennent pas, traitez-les donc comme des approximations.

Rendre un prompt compatible avec le cache : ce que confirme la documentation

Les preuves soutiennent une courte liste d'exigences.

1. Choisissez un modèle qui liste prompt-cache. Le tableau capabilities de Get a Model (observé le 03/10/2026) est la vérification à effectuer. Un modèle sans cette mention ne vous donne aucune base pour espérer une remise.
2. Gardez le contenu partagé dans une position stable. Sur le point de terminaison Messages, system est un champ de premier niveau qui accepte une chaîne ou un tableau de blocs de contenu. Sur Chat Completions, les instructions système vont dans messages. Dans les deux cas, le matériel répété doit venir en premier.
3. Envoyez des octets identiques jusqu'à la limite. C'est la règle du préfixe exact de la version originale de cet article, et elle correspond à la façon dont les prix du tableau fonctionnent. Un prix de lecture ne s'applique qu'à la partie du prompt qui correspond.

Requête A : [ Prompt Système + Définitions Outils ] [ Requête Utilisateur A ]
           ▲───────────── PRÉFIXE EN CACHE ────────▲ ▲── SUFFIXE ──▲

Requête B : [ Prompt Système + Définitions Outils ] [ Requête Utilisateur B ]
           ▲─────────── HIT CACHE (LECTURE) ───────▲ ▲── SUFFIXE ──▲

Trois habitudes brisent le plus souvent la réutilisation :

• Les horodatages, les identifiants utilisateur ou les identifiants de session en haut d'un prompt système.
• Les définitions d'outils ou les clés JSON réordonnées entre les requêtes.
• Les changements d'indentation ou de saut de ligne dans le texte partagé.

Une forme de requête documentée par la référence Create Message :

{
  "model": "claude-sonnet-5",
  "max_tokens": 512,
  "system": [
    {
      "type": "text",
      "text": "Vous êtes un assistant de support. La politique suivante régit toutes les réponses : [Texte complet de la politique]"
    }
  ],
  "messages": [
    { "role": "user", "content": "Quelle est la période de retour pour les articles endommagés ?" }
  ]
}

Une version antérieure de cet article plaçait un marqueur cache_control de type ephemeral sur ce bloc système. La référence Create Message que nous avons lue le 03/10/2026 ne liste pas ce champ, nous l'avons donc supprimé de l'exemple. Il en va de même pour la longueur minimale du préfixe et la durée de vie du cache. Nous n'avons trouvé aucun chiffre pour l'un ou l'autre dans la documentation TokenLab que nous avons consultée. Avant de vous fier à un marqueur explicite ou à un TTL, testez le modèle choisi et comparez le nombre de tokens mis en cache sur deux appels identiques.

Lire les prix du cache et confirmer les tokens mis en cache

Ne copiez pas le tableau ci-dessus dans votre code. Le guide de facturation indique de lire le prix actuel lorsque votre application en a besoin. Deux routes documentées :

curl "https://api.tokenlab.sh/v1/models/claude-sonnet-5"
curl "https://api.tokenlab.sh/v1/pricing?provider=openai&tag=chat"

Le premier renvoie les capacités, les limites et la tarification d'un modèle. Un ID de modèle inconnu renvoie 404 model_not_found. Le second est un point de terminaison public qui ne nécessite aucune clé API. Son exemple de réponse documenté montre input_per_1m_tokens et output_per_1m_tokens pour gpt-4o et aucun champ de cache. Son updated_at dans cet exemple est le 20/04/2026, ce qui correspond à des données d'exemple et non à la tarification actuelle. Pour les prix du cache, nous avons utilisé le point de terminaison par modèle.

Pour confirmer que la mise en cache a fonctionné, les objets usage documentés sont plus légers que vous ne pourriez l'espérer. Chat Completions liste prompt_tokens, completion_tokens et total_tokens. Messages liste input_tokens et output_tokens. Aucune référence ne nomme un champ de tokens mis en cache. Le guide des coûts des agents de codage (observé le 03/10/2026) indique de confirmer l'utilisation des tokens mis en cache dans la réponse ou dans Usage, et d'enregistrer les tokens d'entrée, de sortie et mis en cache par tâche.

Un test que nous effectuerions :

1. Envoyez deux fois la même requête avec un long préfixe, à quelques secondes d'intervalle, en ne modifiant que le message utilisateur final.
2. Enregistrez l'objet usage brut complet des deux réponses, plus billing_transaction_id s'il est présent.
3. Comparez la charge de la deuxième requête dans Usage avec le calcul ci-dessus. Un hit de cache devrait se situer près du chiffre « avec cache », pas celui sans cache.
4. Répétez avec une première ligne délibérément modifiée pour voir le coût de l'échec.

Pour le streaming Chat Completions, définissez stream_options.include_usage: true pour recevoir l'utilisation dans les morceaux de flux. Un en-tête de facturation peut être absent sur les flux, utilisez donc Usage pour la charge finale. Le guide de dépannage décrit également GET /v1/management/api-keys/{keyId}/usage, qui filtre par model, startDate et endDate pour une réconciliation côté serveur.

Quand le coût de mise en cache des prompts n'est-il pas rentable ?

La mise en cache est un pari sur le trafic répété. Elle est perdante dans ces situations :

• Le préfixe ne se répète jamais. Un document unique de 20 000 tokens paie toute prime d'écriture et ne rapporte rien.
• Les requêtes arrivent trop lentement. Si l'écart entre les requêtes correspondantes dépasse la durée de vie du cache, chaque appel est une nouvelle écriture. Nous n'avons pas trouvé cette durée de vie dans les preuves, mesurez donc votre propre écart par rapport à ce que la page du modèle indique.
• Le préfixe change avant la limite. Le surcoût de 25 % dans le cas d'échec ci-dessus provient exactement de ce modèle.
• Le préfixe est petit. Les économies sont proportionnelles aux tokens du préfixe. Quelques centaines de tokens permettent d'économiser des fractions de centime par appel, et la taille minimale pouvant être mise en cache ne figure pas dans les preuves.
• La sortie domine la facture. La mise en cache ne réduit que l'entrée. Si les réponses sont longues, la ligne de cache ne représente qu'une petite part du total.
• Le modèle n'affiche aucun prix de cache. Le guide de facturation indique qu'un tiret dans la colonne de prix TokenLab signifie aucune offre vérifiée, pas gratuit. Vérifiez les détails de tarification d'un modèle avant de compter sur une quelconque remise.

Modèle de charge de travail	Viabilité de la mise en cache	Pourquoi
Boucles d'outils multi-tours	Élevée	Les instructions et les définitions d'outils restent fixes entre les étapes.
De nombreux utilisateurs interrogeant un grand document	Élevée	Les pics de trafic amortissent rapidement l'écriture.
Tâches de fond peu fréquentes	Faible	Les écarts plus larges que la durée de vie du cache forcent des écritures répétées.
Prompts système variables	Faible	Les changements avant la limite brisent la correspondance.

La mise en cache des prompts diffère également de l'astuce « Implémenter la mise en cache » du guide de facturation, qui signifie stocker les réponses pour des requêtes identiques répétées dans votre propre application. Cela évite complètement l'appel au modèle, mais cela n'aide que lorsque toute la requête se répète. Pour les sessions d'agent longues, le guide des coûts des agents de codage couvre la taille du contexte, les limites de sortie et le choix du modèle en plus de la mise en cache.

FAQ

Un hit de cache rend-il toujours une requête moins chère ?

Uniquement pour le préfixe correspondant, et uniquement si le modèle liste un prix de lecture en cache. Sur les modèles que nous avons vérifiés, une lecture coûte entre 2 % et 10 % de l'entrée. Le suffixe et tous les tokens de sortie sont facturés aux tarifs normaux. Un échec sur un modèle avec une prime d'écriture peut coûter plus cher qu'un appel sans cache.

Un prix d'écriture en cache manquant est-il synonyme de gratuit ?

Non. Pour gpt-5.5 et gemini-3.8-flash, l'API en direct listait un prix de lecture en cache et aucun prix d'écriture le 03/10/2026. Effectuez une première requête et lisez la charge dans Usage plutôt que de supposer zéro ou le tarif d'entrée.

Où vont les valeurs par utilisateur dans un prompt pouvant être mis en cache ?

Placez-les après le contenu partagé, dans le message utilisateur ou dans une entrée messages tardive. Tout ce qui varie avant le bloc partagé modifie le préfixe et force une nouvelle écriture. Cela inclut les horodatages, les identifiants de session et les listes d'outils réordonnées.

Pourquoi une requête répétée ne montrerait-elle aucun token mis en cache ?

Nous vérifierions quatre choses dans l'ordre. Le modèle liste-t-il prompt-cache ? Le préfixe est-il identique octet par octet entre les appels ? Le deuxième appel est-il arrivé pendant la durée de vie du cache ? Le nombre mis en cache se trouve-t-il dans un champ que votre journalisation supprime ? La documentation que nous avons lue ne nomme pas ce champ, enregistrez donc l'objet usage complet.

Comparez les prix du cache en direct avant de vous engager sur un modèle sur la page des modèles TokenLab.