cache_control.
La mise en cache des prompts exécute toujours l’inférence à chaque requête. Elle ne renvoie pas une réponse antérieure à une requête identique.
Mettre un prompt en cache
Marquez le dernier bloc de la partie stable. Tout ce qui précède ce bloc, bloc inclus, est mis en cache.- Envoyez la requête une fois pour écrire le cache.
- Envoyez-la de nouveau avec le même contenu pouvant être mis en cache.
- Vérifiez
cached_tokensetcache_write_tokensdans l’utilisation de la réponse (consultez Champs d’utilisation et de tarification), ainsi que les compteurs de cache dans les détails de la requête. - Comparez la latence et le coût sur plusieurs appels, pas seulement le premier.
Phaseo n’envoie à chaque fournisseur que les contrôles de cache qu’il documente et retire les autres. Les contrôles de cache n’excluent jamais un fournisseur du routage. Chaque page de modèle indique ses prix de lecture et d’écriture du cache.
Quels fournisseurs mettent en cache automatiquement
Les autres fournisseurs compatibles OpenAI reçoivent
prompt_cache_key lorsque leur API l’accepte, et aucun autre contrôle de cache. Phaseo envoie toujours un hachage de votre espace de travail et de la clé plutôt que la clé elle-même ; consultez Affinité de fournisseur.
Contrôles de cache
Laisser Phaseo placer les points d’arrêt Claude
Uncache_control de premier niveau sur Chat Completions, Responses ou Anthropic Messages active la mise en cache pour les routes Claude, et Phaseo place les points d’arrêt pour vous. Les autres fournisseurs l’ignorent.
ttl: "5m" (la valeur par défaut) pour un contexte partagé de courte durée, et ttl: "1h" lorsque le modèle prend en charge des entrées de cache plus durables. Un cache_control de premier niveau maintient aussi la conversation chez un seul fournisseur ; consultez Affinité de fournisseur.
provider_options.anthropic.cache_control est le même réglage, et il accepte aussi un scope. Lorsqu’une requête envoie les deux, la valeur de provider_options l’emporte :
Utilisez
agent pour les boucles d’outils en plusieurs étapes. all_text et last_user_message ne marquent pas les messages qui ne contiennent que des résultats d’outils : le préfixe en cache cesse donc de grandir. Les valeurs de scope non reconnues sont traitées comme agent.
Les points d’arrêt que vous placez vous-même sur les blocs l’emportent sur la politique par défaut et comptent dans la limite de quatre par requête d’Anthropic : la politique par défaut cesse d’ajouter des marques à quatre. Si vos propres blocs portent plus de quatre marques, Phaseo conserve la première et les trois plus récentes et retire les autres, afin que la requête ne soit pas refusée.
Points d’arrêt de cache sur les blocs
Une marque de cache sur un bloc de contenu met en cache tout ce qui précède ce bloc, bloc inclus. Phaseo accepte deux écritures :cache_control:{"type": "ephemeral"}, avec unttlfacultatif de5mou1h.prompt_cache_breakpoint: le{"mode": "explicit"}d’OpenAI, avec unttlfacultatif de30mou12h(consultez Cache de 12 heures sur OpenAI). Lorsqu’un bloc porte les deux,prompt_cache_breakpointl’emporte.
cache_control partout où Anthropic l’accepte : blocs de texte system, blocs de texte et d’image des messages, blocs de résultats d’outils et définitions d’outils. Lorsqu’une requête comporte plusieurs TTL, Anthropic exige que les points d’arrêt 1h précèdent les points d’arrêt 5m.
Chaque fournisseur reçoit la marque sous sa propre forme :
Les marques sur les définitions d’outils n’atteignent que les routes Claude, Alibaba Model Studio, Venice et les modèles Claude et Gemini 2.5 d’Inference.net ; OpenAI n’accepte pas de points d’arrêt sur les outils. Retirer une marque laisse le reste du prompt inchangé : le préfixe en cache correspond donc à une requête sans marque.
Amazon Bedrock et Google Vertex AI ne mettent en cache Claude 3.7 Sonnet, 3.5 Sonnet et 3 Opus que pendant 5 minutes, et Bedrock peut refuser un
ttl sur ces modèles. Sur ces routes, Phaseo envoie vos points d’arrêt sans ttl, de sorte qu’ils sont mis en cache pendant 5 minutes, et signale un 1h retiré comme cache_control.ttl dans l’en-tête X-Phaseo-Dropped-Params et dans meta.routing.dropped_params. Inference.net documente des points d’arrêt sans ttl : Phaseo y retire et signale donc un ttl de la même façon, et les écritures sont facturées comme des écritures de 5 minutes.
Conservation et options OpenAI
Les contrôles de cache d’OpenAI dépendent de la génération du modèle. Phaseo n’envoie chacun d’eux que là où il est accepté :
Le mode
explicit ne met en cache que les points d’arrêt que vous placez. DeepInfra exige aussi prompt_cache_key sur chaque requête de la session. Phaseo n’envoie un 1h Moonshot AI qu’aux routes Kimi K3 qui ont un prix d’écriture d’une heure, de sorte que ces écritures sont facturées à ce prix ; ailleurs, il retire le ttl et le signale comme prompt_cache_options.ttl dans l’en-tête X-Phaseo-Dropped-Params. Les autres fournisseurs ne reçoivent aucun de ces champs.
Envoyez l’un ou l’autre champ au premier niveau ou sous provider_options.openai. Lorsque les deux sont présents, la valeur de premier niveau l’emporte :
24h.
Cache de 12 heures sur OpenAI
Sur GPT-5.6 et versions ultérieures, OpenAI conserve une entrée de cache pendant au moins 12 heures lorsque vous définissezttl: "12h", soit pour toute la requête dans prompt_cache_options, soit pour un point d’arrêt dans prompt_cache_breakpoint. Un point d’arrêt sans ttl propre utilise celui de la requête. OpenAI facture une écriture de 12 heures à 2,5× le tarif d’entrée et une écriture de 30 minutes à 1,25× ; les lectures du cache coûtent le même prix dans les deux cas.
- OpenAI ne documente la durée de 12 heures que sur son API Responses. Une requête Chat Completions qui la demande s’exécute sur l’API Responses d’OpenAI, et la réponse conserve le format Chat Completions.
- Les routes qui acceptent un cache de 12 heures sont essayées en premier : l’API d’OpenAI elle-même (
openaietopenai-eu), sur un modèle GPT-5.6 ou ultérieur dont la fiche tarifaire comporte un prix d’écriture de 12 heures. Toute autre route, comme Azure OpenAI, un autre fournisseur ou un modèle antérieur à GPT-5.6, reçoit la requête sans ce réglage : la valeur par défaut de 30 minutes s’applique alors. La requête s’exécute quand même, et le champ retiré est signalé commeprompt_cache_options.ttlouprompt_cache_breakpoint.ttldans l’en-têteX-Phaseo-Dropped-Paramset dansmeta.routing.dropped_params.
Utiliser un cache Gemini explicite
Gemini 2.5 et versions ultérieures mettent en cache implicitement, sans rien à envoyer. Pour utiliser un cache explicite que vous avez créé avec l’API de mise en cache de Google, passez son nom dansprovider_options.google.cached_content :
- Sur Google AI Studio,
cached_contentne fonctionne qu’avec votre propre clé API Google (BYOK). Avec la clé de Phaseo, la requête renvoie400, car le cache appartient au compte qui l’a créé. - Sur Vertex AI,
cached_contentne fonctionne qu’avec votre propre identifiant Vertex AI ; avec celui de Phaseo, la requête renvoie400. Envoyez le nom complet du cache,projects/{project}/locations/{location}/cachedContents/{id}, et Phaseo envoie la requête vers ce projet et cet emplacement. Un nom court tel quecachedContents/abc123utilise leproject_idet laregionde votre JSON de compte de service, et renvoie400si l’un des deux manque. - Google ne prend pas en charge les caches explicites sur Gemini 4 Argon et versions ultérieures.
provider_options.google.cache_control et provider_options.google.cache_ttl sont acceptés mais ne sont pas envoyés à Google.
Responses : envoyer toute la conversation
Phaseo ne stocke pas les réponses. Les requêtes qui définissentprevious_response_id ou conversation renvoient 400 unsupported_param : envoyez donc toute la conversation dans input à chaque étape. Son ouverture stable est le préfixe mis en cache. Dans les boucles d’outils, renvoyez aussi les éléments de sortie reasoning ; consultez Raisonnement dans les boucles d’outils.
Changer l’effort de raisonnement en cours de conversation
Changezreasoning_effort (Chat Completions) ou reasoning.effort (Responses) entre deux requêtes : Phaseo conserve le cache de prompts de Claude, car il envoie le changement sous forme de marqueur d’effort à l’intérieur de messages au lieu d’un nouvel effort de premier niveau. Cela fonctionne tant que vous renvoyez le raisonnement de Claude inchangé. Sur Anthropic Messages, vous envoyez vous-même le marqueur. Consultez Changer l’effort de raisonnement en cours de conversation.
Champs d’utilisation et de tarification
Chaque endpoint texte indique les lectures et écritures du cache. Chat Completions et Responses suivent la sémantique d’OpenAI : le décompte d’entrée inclut les lectures et écritures du cache. Anthropic Messages suit celle d’Anthropic :input_tokens les exclut.
Sur Chat Completions et Responses, l’entrée non mise en cache correspond à l’entrée totale moins les lectures et moins les écritures du cache. Les réponses Anthropic Messages en streaming portent les champs de cache sur
message_delta. L’utilisation Chat Completions n’est pas répartie par durée, car OpenAI n’en documente aucune à cet endroit ; les détails de la requête l’enregistrent tout de même.
Les réponses antérieures indiquaient les écritures du cache dans
output_tokens_details.cached_tokens (completion_tokens_details.cached_tokens sur Chat Completions), et les routes Claude excluaient les lectures et écritures du cache de input_tokens sur Chat Completions et Responses. Ce n’est plus le cas : lisez les écritures dans cache_write_tokens. Les réponses Anthropic Messages hors streaming renvoyaient auparavant cache_creation_input_tokens: null ; elles renvoient désormais les décomptes réels.Tarification des tokens en cache
Phaseo facture chaque token d’entrée une seule fois, à un seul tarif : l’entrée non mise en cache au tarif d’entrée, les lectures du cache au tarif de lecture du cache, et les écritures du cache au tarif d’écriture du cache, ou aux tarifs de 5 minutes et d’une heure (Claude) ou de 30 minutes et de 12 heures (OpenAI) lorsque le fournisseur les tarifie séparément. Certains fournisseurs comptent les écritures du cache dans le total d’entrée, d’autres les indiquent en plus ; dans tous les cas, un token écrit n’est jamais facturé en plus comme entrée ordinaire. Par exemple, à des tarifs indicatifs de $5.00 par million de tokens d’entrée, $0.50 pour les lectures du cache, $6.25 pour les écritures du cache de 30 minutes et $30.00 pour la sortie, une requête de 53 100 tokens d’entrée, dont 48 000 lectures du cache et 3 000 écritures du cache, plus 850 tokens de sortie, coûte :
Si 2 000 de ces écritures avaient une durée de 12 heures, elles coûteraient $12.50 par million au lieu de $6.25, et la requête coûterait $0.09125.
Certains fournisseurs n’appliquent pas de remise aux tokens en cache sur certains modèles. Leurs pages de modèle affichent alors le même prix pour l’entrée et les lectures du cache.
Quand une route n’a pas encore de prix de cache
Si un fournisseur indique des tokens en cache sur une route qui n’a pas encore de prix de cache dans le catalogue, la requête n’échoue pas :- Les lectures du cache sont facturées au tarif d’entrée de la route.
- Les écritures du cache sont facturées au tarif d’entrée multiplié par le multiplicateur d’écriture documenté par le fournisseur.
- La ligne de tarification est marquée
pricing_fallback: "input_rate".
Sur une route Claude dont le catalogue a un seul prix d’écriture du cache, ce prix est le tarif de 5 minutes. Les écritures que le fournisseur indique comme écritures d’une heure sont facturées à 2× le tarif d’entrée, sur une ligne
cached_write_text_tokens_1h marquée pricing_fallback: "input_rate".
Le message_delta final d’une réponse Claude en streaming indique le total des écritures du cache sans répartition par TTL. Les écritures au-delà de la répartition sont facturées comme des écritures de 5 minutes, car les écritures des outils serveur peuvent utiliser 5 minutes même lorsque la requête demande une heure.
Affinité de fournisseur
Un cache de prompt réside chez un seul fournisseur, et souvent dans une seule région ou un seul déploiement de ce fournisseur. Phaseo maintient les requêtes liées chez le fournisseur et sur la route qui les ont servies, afin qu’une boucle d’agent ne paie pas pour reconstruire son cache ailleurs. Envoyezprompt_cache_key ou session_id, ou activez la mise en cache avec cache_control (au premier niveau, provider_options.anthropic.cache_control, ou une marque cache_control ou prompt_cache_breakpoint sur un bloc de message ou un outil), pour épingler une conversation. Phaseo l’épingle au fournisseur et à la route qui ont servi la première requête réussie, et les requêtes suivantes avec la même clé y vont aussi. Les épinglages sont conservés par espace de travail, endpoint et modèle.
La durée d’un épinglage dépend de la conservation du cache du fournisseur :
Un épinglage ne change que lorsque son fournisseur échoue (disjoncteur ouvert ou taux d’erreur récent élevé), lorsque le quota géré par Phaseo chez ce fournisseur est épuisé, ou lorsque la route active, le préréglage, le garde-fou ou la politique de la requête ne l’autorise plus. La requête bascule alors, et l’épinglage passe au fournisseur qui l’a servie. Les détails de la requête l’enregistrent comme
sticky_routing.demotionReason dans les diagnostics de routage. Les requêtes épinglées ne servent pas à sonder les fournisseurs en cours de rétablissement.
Sans clé, session_id ni marque de cache, Phaseo épingle tout de même le contexte d’ouverture pendant 15 minutes à un fournisseur qui a signalé une lecture ou une écriture de cache pour celui-ci, tant que l’entrée en cache de ce fournisseur coûte moins cher que son entrée standard.
Phaseo envoie aux fournisseurs un hachage de votre espace de travail et de prompt_cache_key, jamais la clé brute : la même clé dans deux espaces de travail ne partage donc jamais un cache de fournisseur. Avec seulement un session_id, Phaseo dérive ce hachage de la session pour OpenAI, xAI, Fireworks et Cerebras. Fireworks, Cloudflare Workers AI et Baseten le reçoivent aussi dans l’en-tête x-session-affinity, Morph dans l’en-tête x-session-id, et xAI sous la forme x-grok-conv-id, sauf si vous définissez provider_options.xai.conversation_id. Les réponses renvoient toujours votre propre prompt_cache_key.
Définissez provider.cache_aware_routing sur false pour désactiver ce comportement pour une requête. Définissez routing.session_affinity sur false lorsque la requête porte un session_id mais ne doit utiliser que le routage normal fondé sur le contexte ; Phaseo cesse alors aussi de dériver une clé de cache de fournisseur à partir de la session. Pour l’articulation de l’affinité avec l’ordre des fournisseurs et les solutions de repli, consultez Routage et solutions de repli. Chaque champ de cache figure aussi dans la référence des paramètres.