Guide du cache de contexte OpenAI

Pour les modèles GPT-5.6 et ultérieurs compatibles, définissez prompt_cache_options.ttl dans une requête Responses API pour choisir une durée minimale de cache de 30 minutes ou de 12 heures. Les exemples utilisent gpt-6.1-terra.

Le cache de 12 heures est disponible uniquement sur /v1/responses, pas sur /v1/chat/completions. Le TTL indique une durée minimale, pas une échéance de suppression ni une garantie de réutilisation à chaque requête.

Définir la clé API

export API_KEY="YOUR_API_KEY"

Le texte long des exemples est un contenu de remplacement. Utilisez votre contenu réel. Le préfixe à mettre en cache doit contenir au moins 1 024 tokens ; ce court texte de remplacement ne déclenche pas une écriture en cache.

Utiliser le cache de 30 minutes

Définissez prompt_cache_options.ttl sur "30m". Sans ttl, la durée est aussi de 30 minutes. Sans mode, le cache est implicite : le service en amont choisit automatiquement le point de cache.

curl "https://api.apimart.ai/v1/responses" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "gpt-6.1-terra",
  "prompt_cache_options": {
    "ttl": "30m"
  },
  "input": [
    {
      "role": "user",
      "content": [
        {
          "type": "input_text",
          "text": "Long reference material to reuse (at least 1024 tokens)... Summarize the key points."
        }
      ]
    }
  ]
}'

Utiliser le cache de 12 heures

Remplacez la valeur du même champ par "12h" en conservant le reste de la structure :

curl "https://api.apimart.ai/v1/responses" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "gpt-6.1-terra",
  "prompt_cache_options": {
    "ttl": "12h"
  },
  "input": [
    {
      "role": "user",
      "content": [
        {
          "type": "input_text",
          "text": "Long reference material to reuse (at least 1024 tokens)... Summarize the key points."
        }
      ]
    }
  ]
}'

Réutiliser un préfixe fixe pour différentes questions

Pour réutiliser un long document en changeant seulement la dernière question, définissez mode sur "explicit" et ajoutez prompt_cache_breakpoint au bloc input_text qui termine le contenu fixe. Cet exemple utilise 12 heures ; pour 30 minutes, passez le TTL de la requête à "30m".

Avec mode: "explicit" sans point de cache, aucune lecture ni écriture en cache ne se produit. Le point ci-dessous ne possède pas de TTL propre et hérite donc de prompt_cache_options.ttl au niveau de la requête.

curl "https://api.apimart.ai/v1/responses" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "gpt-6.1-terra",
  "prompt_cache_options": {
    "ttl": "12h",
    "mode": "explicit"
  },
  "input": [
    {
      "role": "user",
      "content": [
        {
          "type": "input_text",
          "text": "Long reference material to reuse (at least 1024 tokens)...",
          "prompt_cache_breakpoint": {
            "mode": "explicit"
          }
        }
      ]
    },
    {
      "role": "user",
      "content": [
        {
          "type": "input_text",
          "text": "Summarize the three main points in the reference material."
        }
      ]
    }
  ]
}'

Renvoyez le même modèle, le même préfixe fixe et le même point de cache lors des requêtes suivantes, en modifiant seulement le dernier message utilisateur. Conservez le contenu, son ordre et les paramètres affectant le contexte. Aucun identifiant de cache à créer ou à transmettre.

Vérifier les statistiques du cache

Consultez usage.input_tokens_details dans la réponse :

cached_tokens: Tokens lus depuis le cache pour cette requête. Une valeur supérieure à 0 indique une lecture du cache.
cache_write_tokens: Nombre total de tokens écrits dans le cache pour cette requête.
cache_write_tokens_details.ttl_30m_tokens: Tokens écrits avec un TTL de 30 minutes pour cette requête.
cache_write_tokens_details.ttl_12h_tokens: Tokens écrits avec un TTL de 12 heures pour cette requête.

Après la première écriture, envoyez une nouvelle requête avec le même préfixe stable et vérifiez cached_tokens. La valeur peut être 0 si le préfixe est trop court, si le contenu change ou si le cache ne correspond pas.

Exemple de cache usage et comptage des tokens

Cet extrait de réponse montre uniquement usage pour un modèle OpenAI compatible avec le cache, avec des écritures pour les deux TTL. Les valeurs réelles dépendent de la réponse.

{
  "usage": {
    "input_tokens": 12000,
    "input_tokens_details": {
      "cached_tokens": 4000,
      "cache_write_tokens": 7000,
      "cache_write_tokens_details": {
        "ttl_30m_tokens": 5000,
        "ttl_12h_tokens": 2000
      }
    },
    "output_tokens": 1000,
    "total_tokens": 13000
  }
}

Tokens d’entrée ordinaires:

input_tokens - input_tokens_details.cached_tokens - input_tokens_details.cache_write_tokens

cache_write_tokens = ttl_30m_tokens + ttl_12h_tokens
total_tokens = input_tokens + output_tokens

Les lectures et écritures du cache sont déjà incluses dans input_tokens. Les deux valeurs par TTL sont des composantes de cache_write_tokens : ne cumulez pas le total avec ses composantes et ne rajoutez pas les lectures et écritures au total d’entrée. Ici, l’entrée ordinaire vaut 12000 - 4000 - 7000 = 1000, les écritures 5000 + 2000 = 7000 et le total des tokens 12000 + 1000 = 13000. Consultez le guide officiel OpenAI du cache de prompts pour son fonctionnement.

Aperçu

Modèles

Série Texte

Série Image

Série Vidéo

Série Audio

Série Modération

Gestion des uploads

Gestion des tâches

Gestion du compte

Guide du cache de contexte OpenAI

Définir la clé API

Utiliser le cache de 30 minutes

Utiliser le cache de 12 heures

Réutiliser un préfixe fixe pour différentes questions

Vérifier les statistiques du cache

Exemple de cache usage et comptage des tokens

​Définir la clé API

​Utiliser le cache de 30 minutes

​Utiliser le cache de 12 heures

​Réutiliser un préfixe fixe pour différentes questions

​Vérifier les statistiques du cache

​Exemple de cache usage et comptage des tokens

Définir la clé API

Utiliser le cache de 30 minutes

Utiliser le cache de 12 heures

Réutiliser un préfixe fixe pour différentes questions

Vérifier les statistiques du cache

Exemple de cache usage et comptage des tokens