Utilisation et facturation du Prompt Caching

Utiliser le Prompt Caching de Claude sur 1折AI : comment l'activer, la longueur minimale, comment confirmer un hit, comment il est facturé après un hit, et le comportement du cache dans Claude Code.

Le Prompt Caching permet aux longs préfixes envoyés à plusieurs reprises (invite système, définitions d’outils, longs documents, historique de conversation) d’être facturés en écriture uniquement lors de la première fois, puis en lecture par la suite. Sur ce site, la lecture et l’écriture du cache sont facturées au tarif officiel, sans appliquer la remise sur les entrées/sorties. Les tarifs unitaires du cache par modèle sont disponibles dans Modèles et tarifs.

En résumé

Le cache est activé par défaut dans Claude Code : il prend effet dès la connexion.
Lorsque vous appelez l’API depuis votre propre code, ajoutez cache_control sur le bloc de contenu à mettre en cache, en utilisant l’API native /v1/messages. L’interface compatible OpenAI ne met pas en cache pour l’instant.
Pour déterminer s’il y a eu un hit, vérifiez uniquement si usage.cache_read_input_tokens dans la réponse est supérieur à 0.
Le cache dure 5 minutes par défaut et chaque hit réinitialise le minuteur. Vous pouvez également utiliser "ttl": "1h" pour écrire un cache d’une heure, dont le tarif d’écriture est plus élevé.

Comment l’activer

Ajoutez "cache_control": {"type": "ephemeral"} sur un bloc de contenu dans system, tools ou messages ; ce bloc et tout ce qui le précède seront mis en cache. Une requête peut contenir au plus 4 points de rupture de cache.

1
curl https://1zheai.com/v1/messages \
2
  -H "x-api-key: $ONEZHE_API_KEY" \
3
  -H "anthropic-version: 2023-06-01" \
4
  -H "content-type: application/json" \
5
  -d '{
6
    "model": "claude-sonnet-5-5",
7
    "max_tokens": 256,
8
    "system": [
9
      {
10
        "type": "text",
11
        "text": "这里放一段很长、每次都一样的内容：项目说明、代码规范、参考文档……",
12
        "cache_control": {"type": "ephemeral"}
13
      }
14
    ],
15
    "messages": [{"role": "user", "content": "根据上面的规范，审查这段代码：..."}]
16
  }'

Si le préfixe à mettre en cache est trop court, la requête est traitée normalement, simplement sans mise en cache et sans erreur. La longueur minimale varie selon le modèle, voir le tableau ci-dessous.

Longueur minimale pour la mise en cache

Les valeurs suivantes proviennent de la documentation officielle d’Anthropic (2026-10-14) :

Nombre minimal de tokens	Modèle
512	Fable 5.1, Fable 5, Opus 5.5, Opus 5, Sonnet 5.5, Haiku 5.5
1,024	Opus 4.8, Sonnet 5, Sonnet 4.6, Sonnet 4.5
2,048	Opus 4.7
4,096	Opus 4.6, Opus 4.5, Haiku 4.5

Confirmer un hit

Envoyez deux fois la même requête (avec un intervalle ne dépassant pas 5 minutes) et comparez les usage des deux réponses. Voici les résultats mesurés le 2026-10-15 avec claude-sonnet-5-5, en plaçant environ 18 000 tokens de texte fixe dans system :

第一次：写入缓存
第二次：命中缓存

{
  "input_tokens": 23,
  "cache_creation_input_tokens": 17920,
  "cache_read_input_tokens": 0,
  "cache_creation": {"ephemeral_5m_input_tokens": 17920, "ephemeral_1h_input_tokens": 0},
  "output_tokens": 4
}

{
  "input_tokens": 23,
  "cache_creation_input_tokens": 0,
  "cache_read_input_tokens": 17920,
  "cache_creation": {"ephemeral_5m_input_tokens": 0, "ephemeral_1h_input_tokens": 0},
  "output_tokens": 4
}

Si le cache_read_input_tokens de la seconde réponse est supérieur à 0, cela indique que le cache est lu. Les tokens d’écriture et de lecture du cache de chaque appel apparaissent aussi dans la colonne Token des journaux d’appel ; la lecture est notée « cache↓ » et l’écriture « ↑ ».

Comment c’est facturé

Type	Tarif officiel	Tarif 1折AI
Écriture du cache (5 minutes)	Tarif d’entrée × 1,25	Tarif officiel, sans remise
Écriture du cache (1 heure)	Tarif d’entrée × 2	Tarif officiel, sans remise
Lecture du cache	Tarif d’entrée × 0,1 (0,05 pour Opus 5.5 et Sonnet 5.5, 0,025 pour Fable 5.1)	Tarif officiel, sans remise

Le tarif officiel d’une écriture de cache de 5 minutes correspond généralement à 1,25 fois le tarif d’entrée officiel. Sur ce site, les entrées bénéficient d’une remise mais le cache non ; on ne peut donc pas conclure qu’une seule lecture de cache rembourse l’écriture en se basant sur le multiplicateur officiel — il faut comparer en tenant compte de la remise sur le modèle, du coût d’écriture et du nombre de lectures répétées. Un exemple de calcul complet est disponible dans Tarifs et facturation.

Cache d’une heure

Ajoutez "ttl": "1h" dans cache_control pour conserver le cache pendant 1 heure ; cela convient aux préfixes utilisés à intervalles supérieurs à 5 minutes mais encore répétitivement :

1
"cache_control": {"type": "ephemeral", "ttl": "1h"}

L’écriture est facturée 2 fois le tarif d’entrée officiel, sans appliquer le tarif d’entrée remisé ; la lecture est identique à celle du cache de 5 minutes. Les tokens d’écriture figurent dans cache_creation.ephemeral_1h_input_tokens de la réponse. Le choix du cache d’une heure doit être évalué en fonction de l’intervalle entre les deux requêtes, du coût d’écriture et du nombre de lectures répétées.

Le cache dans Claude Code

Claude Code place automatiquement des points de rupture de cache sur l’invite système, les définitions d’outils et l’historique de conversation ; l’explication officielle est ici. Pour améliorer les hits :

Travaillez en continu dans une session sans pauses prolongées. Le cache expire après 5 minutes d’inactivité.
Les requêtes suivantes d’une même session lisent le cache. Mesure du 2026-10-15 : pour une tâche Claude Code en deux tours, le second tour a lu 31 440 tokens de cache et écrit 115 tokens. Lorsque vous ouvrez une nouvelle session, le premier tour doit peut-être réécrire tout le préfixe (environ 30 000 tokens mesurés), ce qui coûte plus cher que les tours suivants.
Évitez de modifier CLAUDE.md, de basculer de serveur MCP ou de changer de modèle en cours de session ; cela modifie le préfixe.
Ne définissez pas DISABLE_PROMPT_CACHING=1 : cette variable d’environnement désactive le cache pour tous les modèles.

L’interface compatible OpenAI peut-elle utiliser le cache ?

Pas pour l’instant. Mesure du 2026-10-15 : en plaçant environ 3 100 tokens de texte fixe dans le message system de /v1/chat/completions et en envoyant deux fois la requête, que cache_control soit ajouté ou non sur le bloc de contenu, les deux usage étaient :

1
{"prompt_tokens": 3167, "completion_tokens": 4, "total_tokens": 3171}

Sans prompt_tokens_details.cached_tokens, les lectures et écritures de cache dans les journaux d’appel sont également à 0, et tout est facturé au tarif d’entrée. Pour les cas nécessitant le cache, utilisez /v1/messages (SDK Anthropic ou Claude Code).

Questions fréquentes

Pourquoi n'y a-t-il que cache_creation et pas de cache_read ?

Le cache a été écrit mais pas lu à la requête suivante. Vérifiez dans l’ordre : l’intervalle entre les deux requêtes dépasse-t-il 5 minutes ; le contenu avant le point de rupture est-il identique à la lettre (des horodatages ou des ID aléatoires dans system rendent chaque requête différente) ; le modèle a-t-il changé ; le préfixe atteint-il la longueur minimale indiquée ci-dessus.

Peut-on voir le taux de succès du cache ?

Les tokens de lecture et d’écriture du cache de chaque appel figurent dans les journaux d’appel ; vous pouvez calculer vous-même : lecture du cache ÷ (entrée + écriture du cache + lecture du cache).