La plupart des requêtes répètent le même début : un prompt système, des définitions d'outils, un long document, les tours précédents d'une conversation. Les fournisseurs gardent ce préfixe en cache et facturent les tokens qui en sont lus à prix réduit, en général 10 % du prix d'entrée normal. Promptix répercute la remise : le prix d'une requête dans votre journal d'utilisation baisse dès que le cache est touché. Cette page explique comment obtenir ces hits.
1. Garder la conversation chez un seul fournisseur
Les caches de prompt vivent chez le fournisseur, et beaucoup de modèles sont servis par plusieurs fournisseurs. Si deux requêtes d'une même conversation arrivent chez des fournisseurs différents, la seconde repart de zéro. Promptix épingle donc chaque conversation à un fournisseur, à partir du premier de ces identifiants trouvé dans la requête :
- l'en-tête
x-session-id; metadata.user_id(format Anthropic) ;- le champ
userouprompt_cache_key(format OpenAI) ; - sinon votre clé API, pour qu'une application seule reste quand même groupée.
Envoyez une valeur stable par conversation, par exemple son identifiant chez vous. Promptix la hache avant de la transmettre : le fournisseur ne voit jamais vos identifiants.
curl https://promptix.tn/api/v1/chat/completions \ -H "Authorization: Bearer $PROMPTIX_API_KEY" \ -H "Content-Type: application/json" \ -H "x-session-id: conversation-8f3a" \ -d '{ "model": "openai/gpt-6-luna", "messages": [ { "role": "system", "content": "<your long, stable instructions>" }, { "role": "user", "content": "How many days do I have to return a product?" } ] }'2. Mettre la partie stable en premier
Un cache compare le préfixe du prompt, octet par octet. Ordonnez vos messages pour que ce qui ne change jamais vienne d'abord et ce qui change en dernier :
- prompt système et définitions d'outils d'abord, puis documents, puis historique de la conversation, puis la nouvelle question ;
- pas d'horodatage, de nom d'utilisateur ni d'identifiant aléatoire en tête du prompt système : tout changement à cet endroit invalide tout ce qui suit ;
- gardez le même modèle : un cache appartient à un modèle ;
- les prompts courts ne sont pas mis en cache. Les fournisseurs commencent vers 1 024 tokens de préfixe (plus sur certains modèles) : un prompt système de deux lignes n'affichera jamais de tokens en cache.
3. Règles par fournisseur
GPT (OpenAI), Gemini (Google), DeepSeek et la plupart des autres fournisseurs mettent en cache automatiquement. Rien à ajouter à la requête : avec une session stable et un préfixe assez long, le deuxième appel indique des tokens en cache.
Claude (Anthropic) ne met en cache que là où vous le demandez. Ajoutez un point d'arrêt cache_control sur le dernier bloc de la partie stable ; tout ce qui précède est gardé cinq minutes et rafraîchi à chaque hit. Cela fonctionne avec les deux endpoints :
{ "model": "anthropic/claude-sonnet-5.5", "messages": [ { "role": "system", "content": [ { "type": "text", "text": "<your long, stable instructions or document>", "cache_control": { "type": "ephemeral" } } ] }, { "role": "user", "content": "How many days do I have to return a product?" } ], "user": "conversation-8f3a"}{ "model": "anthropic/claude-sonnet-5.5", "max_tokens": 1024, "system": [ { "type": "text", "text": "<your long, stable instructions or document>", "cache_control": { "type": "ephemeral" } } ], "messages": [{ "role": "user", "content": "How many days do I have to return a product?" }], "metadata": { "user_id": "conversation-8f3a" }}Prix du cache Claude
Anthropic facture la première écriture dans le cache 25 % plus cher qu'un token d'entrée normal, puis les lectures à 10 %. Le cache est rentable dès le deuxième appel d'une conversation. Pour une requête isolée, n'ajoutez pas cache_control.
4. Vérifier que ça marche
Chaque réponse contient les compteurs du fournisseur, donc vous voyez le cache à l'œuvre. Au format OpenAI, regardez usage.prompt_tokens_details.cached_tokens. Les deux réponses ci-dessous viennent de la même session avec un prompt système de 2 600 tokens sur openai/gpt-6-luna ; la deuxième requête a coûté environ un dixième de la première.
// First call: the prefix is written to the cache"usage": { "prompt_tokens": 2621, "completion_tokens": 26, "total_tokens": 2647, "prompt_tokens_details": { "cached_tokens": 0, "cache_write_tokens": 2618 }} // Second call, same prefix, same session: read from the cache"usage": { "prompt_tokens": 2617, "completion_tokens": 17, "total_tokens": 2634, "prompt_tokens_details": { "cached_tokens": 2603, "cache_write_tokens": 11 }}Au format Anthropic, la partie en cache apparaît dans cache_read_input_tokens et la première écriture dans cache_creation_input_tokens ; input_tokens ne compte que ce qui n'était pas en cache :
"usage": { "input_tokens": 17, "cache_creation_input_tokens": 0, "cache_read_input_tokens": 5542, "output_tokens": 25}En streaming, le même objet arrive dans le dernier chunk avant [DONE] (voir Streaming). Le montant réellement débité en TND est dans le journal d'utilisation et dans GET /generation.
Claude Code et le chat agent
Claude Code envoie de lui-même un identifiant de session et des points d'arrêt de cache, et l'agent de chat.promptix.tn fait de même pour chaque conversation. Rien à configurer : les longues sessions d'agent lisent l'essentiel de leur contexte depuis le cache.