---
title: "Utilisation et facturation du Prompt Caching"
description: "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."
headingIds: {"En résumé":"section-1","Comment l’activer":"section-2","Longueur minimale pour la mise en cache":"section-3","Confirmer un hit":"section-4","Comment c’est facturé":"section-5","Cache d’une heure":"section-6","Le cache dans Claude Code":"section-7","L’interface compatible OpenAI peut-elle utiliser le cache ?":"section-8","Questions fréquentes":"section-9"}
---
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](https://1zheai.com/en/pricing/).
## 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.
```bash
curl https://1zheai.com/v1/messages \
-H "x-api-key: $ONEZHE_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "content-type: application/json" \
-d '{
"model": "claude-sonnet-5-5",
"max_tokens": 256,
"system": [
{
"type": "text",
"text": "这里放一段很长、每次都一样的内容：项目说明、代码规范、参考文档……",
"cache_control": {"type": "ephemeral"}
}
],
"messages": [{"role": "user", "content": "根据上面的规范，审查这段代码：..."}]
}'
```
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](https://platform.claude.com/docs/en/build-with-claude/prompt-caching) (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 :
```json title="第一次：写入缓存"
{
"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
}
```
```json title="第二次：命中缓存"
{
"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](/fr/docs/usage-logs/) ; 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](/fr/docs/pricing-explained/).
### 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 :
```json
"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](https://code.claude.com/docs/zh-CN/prompt-caching). 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 :
```json
{"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
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.
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).